第5章 AI Agent中的Code Mode与沙箱(Sandboxes)
"Code mode"和"sandbox"经常出现在同一个话题里,很多时候被当成一回事来用。其实不是。Code mode 关注的是模型如何调用你的工具,sandbox 关注的是代码在哪里运行、能接触到什么。
两者可以单独使用,也可以组合起来——当模型的代码和你的工具需要不同的边界时。这篇文章会讲清楚各自的用途、sandbox 边界可以放在哪三个位置,以及 Pydantic AI 的 workspace 如何让你移动这个边界而不用重写工具。
Code mode 是什么
普通的 tool calling 流程是:模型选一个工具,填好 JSON 参数,然后等待。你执行工具,把结果返回,模型再决定下一步。当一个调用依赖另一个调用时,每一步都要消耗一次模型请求,而且所有中间结果都会进入 context window。
Code mode 则是给模型一个单独的工具 run_code,让它写一小段 Python 程序,把你的工具当函数来调用。循环、过滤、asyncio.gather 都作为代码执行,而不是多轮对话。这个模式由 Cloudflare 命名,Anthropic 也从模型侧得出了同样的结论。
在 Pydantic AI 中,code mode 是 Pydantic AI Harness 提供的 CodeMode 能力:
from typing import TypedDict
import logfire from pydantic_ai import Agent from pydantic_ai_harness import CodeMode
logfire.configure(service_name='code-mode') logfire.instrument_pydantic_ai()
class Order(TypedDict): id: str total: float
ORDERS = {'cus_42': ['ord_1', 'ord_2', 'ord_3']} TOTALS = {'ord_1': 120.0, 'ord_2': 35.5, 'ord_3': 210.0}
agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[CodeMode()])
@agent.tool_plain def list_orders(customer_id: str) -> list[str]: """List the order IDs for a customer.""" return ORDERS.get(customer_id, [])
@agent.tool_plain def get_order(order_id: str) -> Order: """Fetch one order.""" return Order(id=order_id, total=TOTALS[order_id])
result = agent.run_sync('How many orders over $100 does cus_42 have, and what is their total?') print(result.output)
用 uv add "pydantic-ai-harness[codemode,anthropic,logfire]" 安装,然后设置模型提供商的 API key,这里是 ANTHROPIC_API_KEY。
模型看到的不是两个独立的工具 list_orders 和 get_order,而是 run_code 描述中的带类型标注的 Python 函数:
class Order(TypedDict): id: str total: float
async def list_orders(*, customer_id: str) -> list[str]: """List the order IDs for a customer.""" ...
async def get_order(*, order_id: str) -> Order: """Fetch one order.""" ...
然后它写出一个程序:
import asyncio
order_ids = await list_orders(customer_id='cus_42') orders = await asyncio.gather(*[get_order(order_id=i) for i in order_ids]) big = [o for o in orders if o['total'] > 100] {'count': len(big), 'total': sum(o['total'] for o in big)}
不用 code mode 的话,模型需要一次请求列出订单,再一次请求获取详情,最后一次请求给出答案,过程中每个订单都进入 context。用 code mode 的话,它写一个程序,读回一个小 dict 就完事。依赖步骤越多,差距越大。
下面是这次运行在 Logfire 中的追踪。list_orders 和三次 get_order 调用都嵌在单个 run_code span 里,夹在两次模型请求之间:
可以展开上面的 span,或打开完整 trace。
程序在执行前会针对这些签名做类型检查。如果模型拿 string 和 int 做比较,会收到类型错误并重试,而不是给出错误答案。
Jiri 写过这对 Logfire MCP server 的效果:三个工具替代了四十多个。
Code mode 在 agent 旁边运行
程序总要有地方跑。在 Pydantic AI 中,run_code 运行在 Monty 上——一个用 Rust 写的 Python 解释器,跑在与 agent 同一台机器的 worker 进程池里。
在 run_code 内部,程序没有文件系统、没有网络、没有环境变量、也没有时钟,除非你主动传入。它接触外部世界的唯一方式是调用你暴露的函数。当它调用 get_order 时,Monty 暂停,Pydantic AI 在 agent 进程里执行真正的 get_order,然后把结果送回程序。
所以有两件事同时成立:
程序是隔离的。它无法打开 socket,也无法读取 ~/.ssh。默认情况下,每次 run_code 调用有 30 秒、256 MiB 和 100 层嵌套工具调用的限制。
你的工具不是。get_order 以 agent 进程的全部权限运行:数据库凭证、API key、宿主机文件系统都在它的能力范围内。
Code mode 下,安全边界就是你暴露的函数列表。把 refund_order 放进去,模型就能写一个循环调用它 100 次。CodeMode(tools=['list_orders', 'get_order']) 可以选择哪些工具进入 run_code,其余的仍作为普通工具调用对模型可见。
Monty 也只运行 Python 的一个子集,标准库模块很少,且不支持第三方包。模型没法在里面 pip install pandas、跑 pytest 或调用 git。要这些就得有真正的执行环境:信任这些工作时用自己的机器,不信任就用 sandbox。
Sandbox 是什么
Sandbox 是一个隔离环境:容器、microVM、云 VM,或你机器上的受限进程。和 Monty 不同,它通常有真实的文件系统、shell 和 CPython,所以模型能运行普通程序。这些程序能运行什么、能访问什么,取决于 sandbox 的镜像、网络规则和挂载。
Code mode with Monty / Sandbox 对比:
解决的问题:前者是模型往返次数太多,后者是运行不信任的程序。
运行内容:前者是 Python 子集,后者是镜像和权限允许的一切,通常是 CPython、shell、git、pytest。
新会话启动:前者从热池启动只需 0.8 ms,后者据一次实测,新建 Daytona sandbox 约 1.5 s。
对外访问:前者只能通过你暴露的函数,后者取决于网络和挂载配置。
你的工具运行位置:前者在你的 agent 进程,后者由你指定。
Sandbox 边界放哪里
一旦需要 sandbox,下一个问题是把什么放进去。有三种答案。
整个 agent
整个 agent 都跑在 sandbox 里:agent 循环、模型客户端、工具、以及它处理的文件。Cloud coding agent 就是这种模式。网页版 Claude Code 把每个会话跑在隔离 VM 里,agent 循环也在其中。在 dev container 或 CI job 里跑的 coding agent 则是自托管版本。
这是最简单的方案,一个边界包住一切。代价是 agent 需要的一切都得放进去。能执行 shell 命令的模型可以读取 agent 持有的任何凭证,除非你像网页版 Claude Code 对 git 那样,在 VM 外面加一层代理来注入凭证。而且每个会话都需要一个 sandbox 陪伴它的整个生命周期,agent 的状态也随 sandbox 生死。
只有工具
agent 循环跑在你的进程里,用你的 key 和数据库。接触文件、执行命令的工具则在别处的 sandbox 里行动。模型只能通过这些工具触达 sandbox,sandbox 用不到的凭证绝不进入。
这就是 Pydantic AI workspace 给你的结构。工具是主要使用者,但任何持有 RunContext 的东西都能访问 workspace,包括 hooks,你自己的代码也能在运行结束后用 result.workspace。
只有代码
agent 和它的工具跑在你的进程里,只有模型写的程序被隔离。这就是 code mode:Monty 充当 sandbox,暴露的函数是它唯一的出口。如果连解释器都不想放在 agent 所在的机器上,CodeMode(monty_sandbox_url=...) 可以把程序发送到远程 Monty worker(比如 Monty 的 Commercial Support),工具仍在本地运行。
后两种可以组合:agent 可以在 Monty 里跑代码,同时工具在 sandbox 里执行。这种组合需要一种把工具指向某个环境的方式——这正是 workspace 的作用。
Pydantic AI 的 workspace
Workspace 是 agent 工具的工作环境:命令在哪里执行、文件在哪里读写。工具通过 ctx.workspace 访问它,它不知道这是你笔记本上的一个目录还是云上的一台 VM。
import logfire from pydantic_ai import Agent, ModelRetry, RunContext from pydantic_ai.capabilities import LocalWorkspace from pydantic_ai.workspaces import WorkspaceError
logfire.configure(service_name='workspaces') logfire.instrument_pydantic_ai()
agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[LocalWorkspace('.')])
@agent.tool async def execute(ctx: RunContext, command: list[str]) -> str: """Run a command in the project directory.""" try: result = await ctx.workspace.run(command, timeout=60) except WorkspaceError as error: raise ModelRetry(str(error)) return result.stdout if result.exit_code == 0 else f'[exit {result.exit_code}] {result.stderr}'
result = agent.run_sync('Write fizzbuzz to fizzbuzz.py and run it.') print(result.output)
LocalWorkspace 不是 sandbox。命令以你的身份在你的机器上执行,目录只是设定了工作目录。它们只能拿到 PATH、HOME 和 locale 变量,不会继承你环境里的其他东西,所以模型的命令拿不到你的 API key。只把它用于你自己可信的工作。
要隔离 agent,换掉 workspace capability 即可。execute 无需改动,因为它只和 ctx.workspace 通信。
不过你很少需要自己写 execute 这样的工具。Harness 的 Coder、FileSystem 和 Shell capabilities 为模型提供文件、搜索和 shell 工具,且在运行时的任意 workspace 中工作。下面这个 agent 在 Modal sandbox 中使用 Coder:
import logfire from pydantic_ai import Agent from pydantic_ai_harness import Coder, ModalSandbox
logfire.configure() logfire.instrument_pydantic_ai()
agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[ModalSandbox(), Coder()])
用 uv add "pydantic-ai-harness[modal,anthropic,logfire]" 安装,并用 modal token new 登录 Modal。之后每条命令、每次文件编辑都在 sandbox 里发生。
下面是之前那个 LocalWorkspace agent 写并运行 fizzbuzz 的 trace。每次 execute 调用是一个 span,两侧各有一次模型请求:
可以展开上面的 span,或打开完整 trace。
Pydantic AI 和 Pydantic AI Harness 提供这些 workspace:
LocalWorkspace:在这台机器上以你的身份运行命令,无隔离。
SSHWorkspace:通过你的 ssh 在远程主机上运行,无隔离。
BubblewrapSandbox:在 bwrap 之下运行于本地或 SSH workspace,宿主机只读、工作目录可写、默认无网络。防的是意外,不是恶意 agent。
SmolSandbox:本机上的一个 microVM,提供 VM 级隔离,不需要云账号。
ModalSandbox、E2BSandbox、SpritesSandbox:云 sandbox,一台独立的机器。
Workspace 的生命周期超过单次运行。一旦某次运行用过 sandbox,把它的 message history 传给下一次运行就会继续使用同一个 sandbox,文件和已安装的包都还在:
first = agent.run_sync('Clone https://github.com/pydantic/pydantic-ai and run its tests.') second = agent.run_sync('Fix the first failing test.', message_history=first.all_messages())
Code mode 和 workspace 一起用
Code mode 和 workspace 解决的是不同的问题,所以可以组合。下面的例子中,模型的 Python 跑在 agent 旁边的 Monty 里,而它从 Python 中调用的文件工具则在 Modal sandbox 里执行:
import logfire from pydantic_ai import Agent from pydantic_ai_harness import CodeMode, FileSystem, ModalSandbox, Shell
logfire.configure() logfire.instrument_pydantic_ai()
agent = Agent( 'anthropic:claude-sonnet-5-5', capabilities=[ModalSandbox(working_dir='/root/project'), FileSystem(), Shell(), CodeMode()], )
result = agent.run_sync('Find every TODO in the project and summarize them by file.') print(result.output)
用 uv add "pydantic-ai-harness[codemode,modal,anthropic,logfire]" 安装,并用 modal token new 登录 Modal。
模型看到三个工具:run_code、run_command 和 start_command。read_file、edit_file、list_directory 等文件工具变成 run_code 内部的函数,所以一个程序可以读二十个文件、过滤它们、再编辑重要的三个。Shell 命令保留在外部作为普通工具调用,模型不用在 Python 字符串里转义 shell 命令。
每一层各司其职:
agent 循环和你的模型 key 留在你的进程里。
模型写的程序跑在 Monty 里,只能访问你暴露的函数。
文件和 shell 工具在 Modal sandbox 里执行,编辑和命令都不会碰你的机器。
你需要哪一个
想让链式工具调用任务减少模型往返次数:用 CodeMode()。
想让模型对自己的仓库跑测试、装包、用 git:用 LocalWorkspace 加 Coder()。
同样的事,但不信任仓库或 prompt:用 sandbox workspace 加 Coder()。
想要托管云 sandbox:用 E2BSandbox()、ModalSandbox() 或 SpritesSandbox()。
没有云账号也要隔离:用 SmolSandbox()。
既要编排又要隔离:CodeMode() 加 sandbox workspace。
Monty
多亏 Monty,code mode 才便宜到可以一直开着。它是一个 MIT 许可、用 Rust 写的 Python 解释器,专为模型写的代码打造。不配合 Pydantic AI 也能用,支持 Python、JavaScript 或 Rust:
import logfire from pydantic_monty import Monty
logfire.configure(service_name='monty') logfire.instrument_monty()
code = """ kcal = nutrition('chocolate bar')['kcal'] hours = kcal * 4184 / (bulb_watts * 3600) print(f'a chocolate bar powers a {bulb_watts} W bulb for {hours:.1f} hours') """
with Monty() as pool: with pool.checkout() as session: session.feed_run( code, inputs={'bulb_watts': 10}, external_lookup={'nutrition': lambda food: {'kcal': 230}}, ) #> a chocolate bar powers a 10 W bulb for 26.7 hours
Monty() 会启动一个 monty worker 进程,代码在其中运行。inputs 把变量 bulb_watts(值为 10)放进 sandbox。external_lookup 允许代码调用 nutrition,但函数本身留在你的 Python 进程里。当代码调用 nutrition('chocolate bar') 时,worker 等待,你的进程执行函数,{'kcal': 230} 送回代码。代码可以调用函数并读取返回值,但函数本身从不在 Monty 内运行。
用 uv add pydantic-monty logfire 安装。
为什么用 Monty
你的密钥留在你的进程里。nutrition 可以用你的凭证查数据库,而模型写的代码只能看到 {'kcal': 230}。
可以暂停、稍后继续。worker 等待 nutrition 时,Monty 可以把整个运行状态保存成字节,之后在另一个进程或另一台机器上恢复。
它很小。Monty 是为 agent 写的短脚本而生的,以进程形式跑在 agent 旁边,不需要容器,也不需要云账号。
任务链式调用多个工具、想减少模型往返时,用 CodeMode()。模型需要跑测试、装包或用 git 时,给它 Coder():自己的仓库用 LocalWorkspace,不信任的仓库或 prompt 用 sandbox workspace。sandbox 可以是托管的云 sandbox(E2BSandbox()、ModalSandbox() 或 SpritesSandbox()),没有云账号就用 SmolSandbox()。既想减少往返又想隔离,就用 CodeMode() 加 sandbox workspace。
Monty on GitHub Monty 文档,包含安全模型和替代方案对比 Pydantic Monty: you probably don't need a full sandbox,Samuel 关于 Monty 为何存在的文章 Pydantic AI 文档中的 Code mode 和 workspaces