Runtime

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:

Pythonfrom pydantic_ai import Agent, CodeExecutionToolfrom pydantic_ai.capabilities import NativeToolagent = 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 shows it:

Terminalpip install pydantic-ai withruntime
Pythonfrom pydantic_ai import Agentfrom withruntime import Sandboxfrom withruntime.tools import sandbox_toolsdef 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:

Pythonfrom pydantic_ai import Agentfrom pydantic_ai.models.test import TestModelfrom withruntime import Sandboxfrom withruntime.tools import sandbox_toolswith 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.

Pythonfrom pydantic import BaseModelfrom pydantic_ai import Agentfrom withruntime import Sandboxfrom withruntime.tools import sandbox_toolsclass Summary(BaseModel):    rows: int    mean_price: floatdef 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.

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).
  • 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, the OpenAI code interpreter alternative and the Claude code execution tool alternative. New accounts get 50 free sandbox hours, no card:

Terminalnpx withruntime sandbox run --trial -- python3 -c 'print(6 * 7)'

Sources

Facts on this page were checked on 25 September 2026.

Claim 50 hours free