进阶 pydantic.dev 2026-11-20 05:57:40 · 4 阅读

第16章 Pydantic AI + E2B:构建隔离沙箱的 Python 编码 Agent

一个能跑 python -m unittest 并编辑文件的编码 agent 确实有用。但一个在你笔记本上、以你的身份、带着 ~/.ssh 里的 SSH 密钥和上两级目录下的生产 .env 运行这些操作的编码 agent,等于你没读条款就签下了一份责任书。agent 自己决定执行什么,命令运行前没人审查过——而一个等待审查的 agent 就不算 agent 了。

E2B 现在是 Pydantic AI 的原生沙箱 provider。往 agent 的 capabilities 里加上 E2BSandbox(),agent 执行的每条 shell 命令和文件操作都会运行在隔离的 E2B microVM 里,而不是你的机器上。你环境里的任何东西都进不了沙箱。沙箱可以在一次运行结束后暂停,下次运行时恢复,文件系统和内存原封不动。而且工作区通过一个不含凭证的引用来标识,durable workflow 可以在 worker 崩溃后接手继续使用它。

本文会过一遍 E2B cookbook 里的两个示例:一个是分两次运行的“先诊断再修复” agent,两次运行之间暂停沙箱;另一个是把同样的任务放进 Temporal workflow,中途直接杀掉 worker 进程。

一行代码,让 agent 离开你的机器

安装 harness,带上 E2B 和 Temporal 的 extras、下面代码用到的 provider extras(quick start 用 Anthropic,cookbook 示例用 OpenAI),以及用于追踪运行过程的 Logfire extra。然后设置 E2B_API_KEY 和对应的 provider key:

uv add "pydantic-ai-harness[e2b,anthropic,temporal]" "pydantic-ai-slim[openai,logfire]"

接着把沙箱和会用到它的工具一起交给 agent:

import logfire from pydantic_ai import Agent from pydantic_ai_harness.coder import Coder from pydantic_ai_harness.e2b_sandbox import E2BSandbox

logfire.configure() logfire.instrument_pydantic_ai()

agent = Agent('anthropic:claude-opus-5-5', capabilities=[E2BSandbox(), Coder()]) result = agent.run_sync('Clone https://github.com/pydantic/pydantic-ai and summarize how capabilities work.')

E2BSandbox 只提供执行环境。Coder(或者更细粒度的 Shell 和 FileSystem capabilities)提供工具,这些工具现在会在沙箱里运行。不需要写自定义 E2B adapter,也不需要构建模板。E2B 的默认模板自带 Python 和 git,对本文来说够用了;有自己依赖的项目可以用自定义模板安装,或者在 agent 启动前在沙箱里跑一次 pip install——因为默认模板有 pip 但没有 uv。

第一次运行前,有几个默认行为值得了解。沙箱默认存活一小时,可以通过 sandbox_timeout 调整;超时后 E2B 会暂停而非杀死它。互联网访问默认开启,可以用 allow_internet_access=False 关掉。而且 Pydantic AI 从不在运行结束时杀死沙箱:沙箱的生命周期归创建它的应用所有,一个你忘记的沙箱就是一个你正在付费的沙箱。E2B 沙箱指南里讲了清理,包括一个 on_run_error 钩子,用于那些在产生可读取引用的结果之前就失败的运行。

诊断,暂停,恢复,修复

第一个 cookbook 示例让 agent 处理一个小型 Python CLI,它负责汇总 JSONL 格式的 API 请求日志。测试是失败的:CLI 统计服务器错误的方式不对,p95 延迟的计算也不对。agent 有两次运行机会。第一次读取代码和失败的测试,写出 diagnosis.md,不动源码。然后应用暂停沙箱,构建一个挂接到它的新 backend,第二次运行根据保存的诊断和第一次运行的对话历史修复 bug。

agent 定义就是普通的 Pydantic AI,唯一涉及 E2B 的部分是那个 capability:

import logfire from pydantic_ai import Agent from pydantic_ai_harness.e2b_sandbox import E2BSandbox from pydantic_ai_harness.filesystem import FileSystem from pydantic_ai_harness.shell import Shell

logfire.configure() logfire.instrument_pydantic_ai()

WORKDIR = '/home/user/log-cli'

agent = Agent( 'openai:gpt-4.1-mini', name='log_cli_fixer', instructions='Work only in this sandbox project. Use the supplied tools; verify claims by running tests.', capabilities=[ E2BSandbox( working_dir=WORKDIR, sandbox_timeout=600, allow_internet_access=False, ), Shell(tools=['run_command'], default_timeout=20, max_output_chars=6000), FileSystem(tools=['read_file', 'write_file', 'edit_file']), ], )

cookbook 有意收窄了工具面。Shell 只暴露 run_command,FileSystem 只暴露三个文件工具,互联网访问关闭,因为测试夹具不需要下载任何东西。沙箱本身就是一道边界,而收窄的工具列表让这道边界更容易把握。

应用在 agent 启动前先写入测试夹具——自己构建 backend,然后通过 Workspace 操作它:

from pydantic_ai.workspaces import Workspace from pydantic_ai_harness.e2b_sandbox import E2BSandbox, E2BSandboxBackend

backend = E2BSandboxBackend(working_dir=WORKDIR, sandbox_timeout=600, allow_internet_access=False) workspace = Workspace(backend) for name in ('log_stats.py', 'test_log_stats.py', 'requests.jsonl'): await workspace.write_bytes(name, (FIXTURE / name).read_bytes())

first = await agent.run(DIAGNOSE, workspace=backend, usage_limits=limits()) ref = first.workspace.ref

构建 backend 不会触发任何 I/O。第一次 write_bytes 才创建沙箱,之后 backend.ref 就标识着它。运行结果也在 first.workspace.ref 里携带同一个引用。

接下来是暂停。应用向 backend 拿到带类型的 e2b.AsyncSandbox,暂停它,然后构建一个只知道该引用的新 backend:

sandbox = await backend.get_sandbox() assert await sandbox.pause()

attached = E2BSandbox(working_dir=WORKDIR, sandbox_timeout=600).backend(ref) continued = Workspace(attached) assert (await continued.read_text('diagnosis.md')).strip()

second = await agent.run( FIX, workspace=ref, message_history=first.all_messages(), usage_limits=limits(), ) assert second.workspace.ref == ref

挂接后的 backend 在第一次读文件时会恢复被暂停的沙箱。E2B 会无限期保留暂停中的沙箱——文件系统和内存都保留——所以 diagnosis.md 还停在第一次运行留下的位置。第二次运行通过 workspace=ref 选择沙箱,通过 message_history 携带对话。ref 或包含它的历史都能选中沙箱,但只有历史才携带 agent 已知的信息,cookbook 两者都传了。

这个示例还做了一件我希望更多 agent 演示能做到的事:检验 agent 的工作,而不是轻信它的总结。它从受信任的宿主机夹具恢复测试文件——因为 shell 命令可以绕过文件工具的限制——确认输入日志没有被篡改,然后自己运行测试。四个测试通过,CLI 输出正确的统计结果,应用在 finally 块中杀死沙箱,并确认它已从账户中消失。

Created sandbox: Diagnosis saved. Model usage: ... Paused sandbox: Resumed sandbox: ; checksums unchanged before repair ... Ran 4 tests ... OK CLI: {"requests": 4, "server_errors": 2, "p95_ms": 100} Cleanup verified:

脚本会在暂停前后断言沙箱身份和 SHA-256 校验和。同一个 id,同样的字节。

杀掉 worker,保住沙箱

暂停-恢复示例证明了沙箱能比一次运行活得更久。Temporal 示例证明它能比驱动 agent 的进程活得更久。

任务还是那个日志 CLI。这次两次 agent 运行都在一个 Temporal workflow 内进行,两次之间演示会向 worker 发送 SIGKILL。没有 Python finally,没有优雅关闭。一个新 worker 在同一个 task queue 上启动,Temporal 重放已记录的历史,workflow 在被杀 worker 留下的沙箱里继续修复。

TemporalDurability 加入 capability 列表,其余部分和第一个示例的 agent 相同。cookbook 把它封装在一个共享的 make_agent() 帮助函数里;完整写出来,并带上示例使用的 Temporal activity 设置,是这样的:

from datetime import timedelta

import logfire from pydantic_ai import Agent from pydantic_ai.durable_exec.temporal import TemporalDurability from pydantic_ai_harness.e2b_sandbox import E2BSandbox from pydantic_ai_harness.filesystem import FileSystem from pydantic_ai_harness.shell import Shell from temporalio.common import RetryPolicy

logfire.configure() logfire.instrument_pydantic_ai()

WORKDIR = '/home/user/log-cli'

agent = Agent( 'openai:gpt-4.1-mini', name='log_cli_fixer', instructions='Work only in this sandbox project. Use the supplied tools; verify claims by running tests.', capabilities=[ E2BSandbox(working_dir=WORKDIR, sandbox_timeout=600, allow_internet_access=False), Shell(tools=['run_command'], default_timeout=20, max_output_chars=6000), FileSystem(tools=['read_file', 'write_file', 'edit_file']), TemporalDurability( activity_config={ 'start_to_close_timeout': timedelta(seconds=45), 'retry_policy': RetryPolicy(maximum_attempts=2), }, ), ], )

agent 需要一个 name,且 agent 和 workflow 都必须在模块级别定义,这样 Temporal 才能注册 activities。两个 worker 进程导入的是同一个模块。

workflow 以沙箱引用作为输入。这一点很关键:控制器创建并写入一个沙箱,然后把一个不含任何凭证的 WorkspaceRef 交给 workflow。Temporal 会在任何 worker 接触 agent 之前记录这个输入,所以无论哪个 worker 最终执行任务的后半段,都知道该挂接哪个沙箱。

下面是 cookbook 的 workflow.py,只保留关键部分。DIAGNOSE、FIX、fingerprints 和 limits 分别是示例 project.py 里的提示词、校验和助手和 UsageLimits:

from temporalio import workflow

with workflow.unsafe.imports_passed_through(): from agent import agent from project import DIAGNOSE, FIX, fingerprints, limits from pydantic_ai.durable_exec.temporal import PydanticAIWorkflow from pydantic_ai.workspaces import WorkspaceRef

@workflow.defn class FixLogCLI(PydanticAIWorkflow): __pydantic_ai_agents__ = (agent,)

def __init__(self): self.checkpoint = None self.proceed = False

@workflow.query def diagnosis_checkpoint(self) -> dict | None: return self.checkpoint

@workflow.signal def continue_fix(self) -> None: self.proceed = True

@workflow.run async def run(self, ref: WorkspaceRef) -> dict: first = await agent.run(DIAGNOSE, workspace=ref, usage_limits=limits()) saved = await fingerprints(first.workspace) self.checkpoint = {'sandbox_id': ref.id, 'checksums': saved}

await workflow.wait_condition(lambda: self.proceed, timeout=180) assert await fingerprints(first.workspace) == saved second = await agent.run( FIX, workspace=ref, message_history=first.all_messages(), usage_limits=limits(), ) return {'sandbox_id': ref.id, 'summary': second.output}

诊断和修复之间的 wait_condition 给崩溃一个可复现的发生位置。控制器轮询 diagnosis_checkpoint 查询,直到第一次运行保存好诊断,然后杀掉 worker,启动一个新的,再次轮询同一个查询,最后才发送 continue_fix。恢复出来的 checkpoint 与被杀 worker 记录的一致。

Created sandbox: Worker started: pid= Durable checkpoint: ; diagnosis and files saved Worker crashed: pid=, exit=-9 Worker started: pid= Checkpoint recovered by pid=; sandbox= ... Ran 4 tests ... OK Exactly one sandbox; original workflow completed after worker restart Cleanup verified:

最后的资源检查是我最先会看的那一行:整个流程结束后,账户里只有一个新沙箱,无论在运行还是暂停状态。朴素的恢复方案会创建第二个沙箱,然后在一个空目录里从头开始。当引用指向的沙箱已不存在时,E2BSandbox 会抛出 WorkspaceUnavailableError,而不是悄悄重新分配一个。恢复要么从诊断中断处继续,要么明确失败。

cookbook 的 README 对这个示例证明了什么、没证明什么说得很清楚,这份严谨值得复述一遍。崩溃发生在空闲的 checkpoint,没有命令正在执行。如果 worker 在完成被记录前消失,Temporal activities 可能会重跑,所以 shell 命令是 at-least-once 而非 exactly-once。恢复不会回滚文件写入。把写工具设计成替换具名结果而非追加写入,那么无论 activity 重跑多少次,得到的答案都一样。

追踪数据去了哪里

E2BSandbox 自身不产生 span。Pydantic AI 的 instrumentation 会在 agent run span 上记录 pydantic_ai.workspace.provider 和 pydantic_ai.workspace.id,工具执行的每条命令或文件操作都在该工具调用的 span 内。加上上面代码里的两行 logfire 配置,Pydantic Logfire 就能展示诊断运行和恢复运行,其中每一条 run_command,以及两次运行相同的沙箱 id,追踪结果与 E2B dashboard 一一对应。在 Temporal 示例中,两次运行位于同一个 workflow 之下,崩溃看起来是两个 activity 之间的间隙,而不是两个不相关的任务。

如果你还没发送追踪数据,Pydantic Logfire 有一个 Personal 计划:每月 1000 万条遥测记录,硬性费用上限 $0,对这两个 cookbook 示例绰绰有余。创建一个项目,跑一次 logfire auth,上面代码里的两行配置搞定其余一切:每一次模型请求、每一条 run_command,以及把运行和 E2B dashboard 关联起来的沙箱 id,都在一个可以用 SQL 查询的 trace 里。

选 E2B 还是 Modal,或者都要

Pydantic AI Harness 还提供了 ModalSandbox,我们在 Harness Week 期间写过介绍。两者都把 agent 的 shell 放进一个你不需要亲自配置的隔离环境,而且都只是 capabilities 列表中的一个 capability。Modal 那篇文章讲的是扇出:五百个容器各跑六分钟,测试套件结束就销毁。这篇讲的是保住一个沙箱:一次运行后暂停它,存好引用,下周恢复时 clone、virtualenv 和改了一半的分支都还在。跨多次 agent 运行的编码会话,或者必须熬过自身 worker 崩溃的 workflow,是 E2B 的形态;测试矩阵是 Modal 的形态。当然,一个应用对两者各用其一也没什么不行。

开始使用

两个 cookbook 示例都能在一个 checkout 里通过 uv sync --locked 和两个环境变量(E2B_API_KEY 和模型 provider key)跑起来。每次 agent 运行通过 UsageLimits 限制在最多八次模型请求和 $0.10 的预估成本上限内,所以提示词里的错误很容易低成本发现。成本估算依赖 provider 的定价数据,最后一次请求可能超出估算,而且这两个限制都不是账户级的消费上限。Temporal 示例会自己启动本地 dev server,不需要 Docker。

刚接触 Pydantic AI?quick start 大约五分钟,而 E2BSandbox 只要在 agent 跑起来后就是 capabilities 列表里的一个 capability。本文开头的安装命令覆盖这里的所有示例,包括 Temporal 那个。

Pydantic AI 文档中的 E2B 沙箱指南,涵盖配置、清理钩子和 dev-server 预览模式。

E2B cookbook 中的暂停-恢复示例。

E2B cookbook 中的 Temporal 崩溃恢复示例。

Pydantic AI 文档中的 Temporal durable execution。

E2B 沙箱持久化,了解暂停和恢复保留了什么、保留多久。

这个 agent 照样运行 python -m unittest、照样编辑文件——只是换个地方做,不在你的笔记本上,而且你说一声,它就能从上次中断的地方接着干。

评论 (0)