airflow.providers.common.ai.toolsets.sandbox¶

Toolset giving an agent shell and file access inside an isolated sandbox, off the worker.

Attributes¶

`log`
`RUN_COMMAND`
`READ_FILE`
`WRITE_FILE`
`LIST_DIRECTORY`

Classes¶

SandboxToolset

Give an agent shell and file access inside a disposable sandbox, off the Airflow worker.

Module Contents¶

airflow.providers.common.ai.toolsets.sandbox.log[source]¶

airflow.providers.common.ai.toolsets.sandbox.RUN_COMMAND = 'run_command'[source]¶

airflow.providers.common.ai.toolsets.sandbox.READ_FILE = 'read_file'[source]¶

airflow.providers.common.ai.toolsets.sandbox.WRITE_FILE = 'write_file'[source]¶

airflow.providers.common.ai.toolsets.sandbox.LIST_DIRECTORY = 'list_directory'[source]¶

class airflow.providers.common.ai.toolsets.sandbox.SandboxToolset(backend, *, spec=None, default_command_timeout=60.0, max_command_timeout=300.0, max_output_lines=2000, max_output_bytes=50 * 1024, max_read_bytes=5 * 1024 * 1024, tool_prefix='')[source]¶

Bases: pydantic_ai.toolsets.abstract.AbstractToolset[Any]

Give an agent shell and file access inside a disposable sandbox, off the Airflow worker.

Exposes four tools – run_command, read_file, write_file and list_directory – against a sandbox provisioned by the given SandboxBackend. The same four names and shapes are what pydantic-ai’s own sandbox capabilities use, so a model that has seen one already knows this one.

What the boundary covers. Only what these tools do runs in the sandbox. The agent loop, the LLM calls, and every other toolset on the same agent still run in the Airflow worker process with its credentials. This contains model-written code; it does not contain the agent. See the toolsets documentation for the full picture of which boundary protects what.

The sandbox is created lazily on the first tool call, shared by every call within one agent run, and destroyed when that run ends. A run that never calls a tool never provisions one. Files persist between calls in a run; each run_command is a fresh shell, so shell variables do not.

A non-zero exit or a timeout is normal tool output – the model reads it and corrects itself. A recoverable sandbox failure becomes a bounded retry. Only a terminal failure (credentials rejected, daemon unreachable) fails the task, so Airflow’s own retry handles it.

Parameters:

backend (airflow.providers.common.ai.sandbox.base.SandboxBackend) – Backend that provisions and drives the sandbox.
spec (airflow.providers.common.ai.sandbox.base.SandboxSpec | None) – What to provision the sandbox with – environment variables and network policy. Defaults to no environment and no egress.
default_command_timeout (float) – Seconds allowed for a run_command call when the model does not ask for one. Default 60.
max_command_timeout (float) – Hard ceiling in seconds for any single command, including a model-supplied timeout_seconds. Default 300.
max_output_lines (int) – Maximum lines retained per output stream or file read. Default 2000.
max_output_bytes (int) – Maximum bytes retained per output stream or file read. Default 50 KiB. Whichever cap is reached first wins.
max_read_bytes (int) – Largest file read_file will transfer. Default 5 MiB; larger files are refused with a hint to slice them in the shell.
tool_prefix (str) – Prefix for the four tool names, e.g. "local" gives local_run_command. Set this when one agent has more than one SandboxToolset, since duplicate tool names are rejected.

property id: str[source]¶

An ID for the toolset that is unique among all toolsets registered with the same agent.

If you’re implementing a concrete implementation that users can instantiate more than once, you should let them optionally pass a custom ID to the constructor and return that here.

A toolset needs to have an ID in order to be used in a durable execution environment like Temporal, in which case the ID will be used to identify the toolset’s activities within the workflow.

async for_run(ctx)[source]¶

Return the toolset to use for this agent run.

Called once per run, before __aenter__. Override this to return a fresh instance for per-run state isolation. Default: return self (shared across runs).

async __aenter__()[source]¶

Enter the toolset context.

This is where you can set up network connections in a concrete implementation.

async __aexit__(*args)[source]¶

Exit the toolset context.

This is where you can tear down network connections in a concrete implementation.

async get_tools(ctx)[source]¶

The tools that are available in this toolset.

async call_tool(name, tool_args, ctx, tool)[source]¶

Call a tool with the given arguments.

Args:: name: The name of the tool to call. tool_args: The arguments to pass to the tool. ctx: The run context. tool: The tool definition returned by [get_tools][pydantic_ai.toolsets.AbstractToolset.get_tools] that was called.