# Pydantic AI code execution tool: run code in a sandbox with any model

Pass `sandbox_tools(sbx)` to a Pydantic AI `Agent` and every command runs in a Runtime microVM, whichever model provider you use.

**On Runtime code execution stops depending on the model provider.** Pydantic
AI's native `CodeExecutionTool` asks the provider to run the code, so it works
with some providers and not others, and the code runs on their machines. With
Runtime's four sandbox tools, the model only chooses a command: it runs in a
Firecracker microVM that your application created, with your network rules and
your spending cap. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour while the
model thinks and $0.08 with both CPUs busy. pydantic-ai 2.49.0 was the current
PyPI release on 25 September 2026.

## Native tool or sandbox tools?

| Question                   | `CodeExecutionTool` (native)                                             | Runtime `sandbox_tools`                                  |
| -------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------- |
| Which models               | OpenAI Responses, Google, Anthropic, xAI, Bedrock (Nova 2.0 models only) | Any model Pydantic AI supports, including `TestModel`    |
| Not supported              | Groq, OpenAI Chat Completions, Mistral, Cohere, Hugging Face             | None                                                     |
| Where code runs            | The provider's own environment                                           | A Runtime microVM with its own kernel                    |
| What the model gets        | The provider's code tool                                                 | A shell, file reads and writes, a directory listing      |
| Packages, files, processes | Whatever the provider's environment allows                               | Ubuntu 24.04 with `pip`, `apt` and `sudo`; files persist |
| Network                    | The provider's policy                                                    | Your allow-list, or internet off                         |

The provider list is Pydantic AI's own, from its native tools page. The native
tool is enabled as a capability:

```python check
from pydantic_ai import Agent, CodeExecutionTool
from pydantic_ai.capabilities import NativeTool

agent = Agent("anthropic:claude-sonnet-4-6", capabilities=[NativeTool(CodeExecutionTool())])
```

## The Runtime version

Pydantic AI registers plain functions passed in `tools=[...]`, builds each
schema from the signature, and takes parameter descriptions from the
docstring. The four Runtime functions carry both, so this is the whole
integration, as the [framework guide](/docs/frameworks#pydantic-ai) shows it:

```bash no-run
pip install pydantic-ai withruntime
```

```python check
from pydantic_ai import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        return Agent(model, tools=sandbox_tools(sbx)).run_sync(task).output
```

`model` is a model string in Pydantic AI's `provider:model` form, such as the
`"anthropic:claude-sonnet-4-6"` in its own docs, or a model object. The
sandbox stops when `solve` returns, even after an exception.

## Test the agent without a model

Pydantic AI's `TestModel` calls every tool it is given with generated
arguments and returns their results as JSON. Pointed at a real sandbox, it
proves the wiring end to end without a model bill:

```python check
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from withruntime import Sandbox
from withruntime.tools import sandbox_tools

with Sandbox.create(network={"internet": False}) as sbx:
    result = Agent(TestModel(), tools=sandbox_tools(sbx)).run_sync("smoke test")
    print(result.output)  # {"runtime_exec": {"exit_code": ..., "stdout": ...}, ...}
```

This ran against pydantic-ai 2.49.0 on 25 September 2026 and called all four
tools.

## A data agent with a typed answer

Pydantic AI's `output_type` pairs well with a sandbox: the model does the work
with real code, and the answer comes back validated.

```python check
from pydantic import BaseModel
from pydantic_ai import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


class Summary(BaseModel):
    rows: int
    mean_price: float


def summarize(model, csv_text: str) -> Summary:
    with Sandbox.create(
        network={"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]},
        timeout_seconds=600,
        on_lease_end="stop",
    ) as sbx:
        sbx.files.write("/workspace/prices.csv", csv_text)
        agent = Agent(
            model,
            output_type=Summary,
            tools=sandbox_tools(sbx),
            instructions="prices.csv is in the working directory. Use pandas to answer.",
        )
        return agent.run_sync("How many rows, and what is the mean price?").output
```

The file is written before the agent starts, so the data never passes through
the model's context. For more on that pattern see
[a data analysis agent](/use-cases/data-analysis-agent).

## Keep the account safe

- **The model sees tools, not credentials.** Your application creates the
  sandbox; the model picks commands and paths inside it and cannot reach the
  account or pick another sandbox.
- **Keys the code needs stay outside it.** A token stored as a Runtime secret
  appears in the sandbox as a placeholder; the host adds the real value only on
  HTTPS requests to the hosts you named
  ([secrets](/docs/security#secrets-sandboxes-never-see)).
- **Spending has two ceilings.** `max_cost_micros` on the create refuses a
  sandbox whose first lease would cost more. A daily spending limit on the
  application's key refuses anything past it with `spending_limit_reached`.
- **Async agents** get coroutine tools: pass an `AsyncSandbox` to
  `sandbox_tools` and use `await agent.run(...)`.

## Which one to use

Use `CodeExecutionTool` when you already use a supported provider and short
scripts in the provider's environment are enough. Use Runtime when
you switch providers, test with `TestModel`, need packages or files that
persist through the run, or must decide what the code can reach. Runtime's
sandboxes start in 351 ms at the median (24 September 2026),
so a fresh one per request is practical.

Related: [code interpreter](/glossary/code-interpreter),
[the OpenAI code interpreter alternative](/compare/openai-code-interpreter-alternative)
and [the Claude code execution tool alternative](/compare/claude-code-execution-tool-alternative).
New accounts get 50 free sandbox hours, no card:

```bash no-run
npx withruntime sandbox run --trial -- python3 -c 'print(6 * 7)'
```

## Sources

- [Pydantic AI: Native tools](https://pydantic.dev/docs/ai/native-tools/), `CodeExecutionTool` and its provider table, read 25 September 2026
- [Pydantic AI: Function tools](https://pydantic.dev/docs/ai/tools/), read 25 September 2026
- [pydantic-ai on PyPI](https://pypi.org/project/pydantic-ai/), version 2.49.0, read 25 September 2026

Facts on this page were checked on 25 September 2026.