Code Execution#

AG2 supports two ways to let an agent run code: have the LLM provider execute it inside their own sandbox, or run it client-side through a sandboxed backend you control. Both produce the same conversational pattern — the model writes code, code runs, results come back — but the trade-offs are different.

Built-in Provider Code Execution#

Some providers expose a server-side Python sandbox the model can drive directly. AG2 surfaces this through CodeExecutionTool — a declaration-only tool that maps to each provider's native capability:

1
2
3
4
5
6
7
8
9

from autogen.beta import Agent
from autogen.beta.config import AnthropicConfig
from autogen.beta.tools import CodeExecutionTool

agent = Agent(
    "analyst",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[CodeExecutionTool()],
)

See the Built-in Tools page for the provider support matrix and version pinning.

Remote Code Execution#

SandboxCodeTool exposes a run_code(code, language) function the agent can call. Because it's a regular function tool, it works on any model provider. Where the code actually runs is decided by the CodeEnvironment you hand it.

Two environments are available: Daytona (hosted) and Docker (local container). You can also implement your own — see the Custom tab below.

pip install "ag2[daytona]"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from autogen.beta import Agent
from autogen.beta.config import AnthropicConfig
from autogen.beta.tools import SandboxCodeTool
from autogen.beta.extensions.daytona import DaytonaCodeEnvironment

agent = Agent(
    "analyst",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[SandboxCodeTool(DaytonaCodeEnvironment())],
)

reply = await agent.ask("Compute the 50th Fibonacci number in Python.")
print(await reply.content())

pip install "ag2[docker]"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from autogen.beta import Agent
from autogen.beta.config import AnthropicConfig
from autogen.beta.tools import SandboxCodeTool
from autogen.beta.extensions.docker import DockerCodeEnvironment

agent = Agent(
    "analyst",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[SandboxCodeTool(DockerCodeEnvironment(image="python:3.12-slim"))],
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from autogen.beta.tools import SandboxCodeTool
from autogen.beta.tools.code import CodeEnvironment, CodeLanguage, CodeRunResult

class MyEnvironment(CodeEnvironment):
    @property
    def supported_languages(self) -> tuple[CodeLanguage, ...]:
        return ("python",)

    async def run(self, code: str, language: CodeLanguage, *, context=None) -> CodeRunResult:
        # ship code to wherever you run it; return stdout + exit code
        ...
        return CodeRunResult(output="...", exit_code=0)

sandbox = SandboxCodeTool(MyEnvironment())

Lifecycle#

The sandbox / container is created lazily on the first run_code call and reused for the lifetime of the environment instance. Cleanup is registered via atexit so resources are released even if you forget to close the environment. For tighter scoping, use the environment as an async context manager:

1
2
3
4
5
6
7
8

async with DaytonaCodeEnvironment(image="python:3.12") as env:
    agent = Agent(
        "analyst",
        config=AnthropicConfig(model="claude-sonnet-4-6"),
        tools=[SandboxCodeTool(env)],
    )
    await agent.ask("...")
# sandbox deleted here

The same pattern works with DockerCodeEnvironment (container stopped + removed) and any other backend that implements __aenter__ / __aexit__.

Credentials and runtime config#

DaytonaCodeEnvironment accepts Variable markers for api_key, api_url, target, image, snapshot, and env_vars. DockerCodeEnvironment accepts them for image, env_vars, and network_mode. Variables resolve from context.variables on the first run_code call — useful for multi-tenant setups:

1
2
3
4
5
6
7

from autogen.beta import Variable
from autogen.beta.extensions.daytona import DaytonaCodeEnvironment

env = DaytonaCodeEnvironment(
    api_key=Variable("daytona_key"),  # resolved from ctx.variables["daytona_key"]
    image=Variable("tenant_image"),
)

State persistence#

A single CodeEnvironment instance reuses the same sandbox / container across every run_code call routed through it. Files written in one call are visible in the next, and packages installed once stay installed. Each snippet still runs as a fresh process, so Python globals defined in one call are not visible to the next — persist state on disk.

For most chat-style agents, instantiate one CodeEnvironment per agent (or per conversation) so state is scoped the way you'd expect. The first tool call pays the sandbox-creation round-trip; subsequent calls reuse it.