第9章 Pydantic AI 成为 AgentEnv 框架支持的官方 Agent
用玩具级的提示词测试 agent,能看出的问题非常有限。而让它处理一个塞满邮件的收件箱、一个有真实工单的客服系统、一个不断走动的时钟,能看出的问题就多得多。AgentEnv Framework 正是为此而生,从今天起,Pydantic AI 成为其官方支持的 agent 之一。
什么是 AgentEnv Framework
AgentEnv Framework 是 Scale AI 的开源框架,用于构建让 agent 在真实应用、数据和多步任务上演练的环境。环境是一个可组合的小世界:邮件、Slack、客服系统,附带种子数据。任务则是一个步骤图:部署环境、部署 agent、发出提示、验证结果。任务会锁定版本,因此重跑可以完全复现。环境通过 MCP 暴露工具,agent 通过 A2A 接入。
一个环境可以承载多个任务和多个 agent,这让它在同一基准下对比不同 agent 时特别好用。
Pydantic AI 在 AgentEnv 中的实现
pydantic-ai agent 在进程内直接运行 Pydantic AI,而不是包在一层 CLI 后面。每个任务就是一次 Agent 的运行,使用 Pydantic AI Harness 提供的 Coder 能力,即 CLAI 所基于的那套编码工具:shell、read_file、write_file、edit_file、list_files、grep 和 delegate_task。shell 命令能访问 PATH、HOME 和 locale,但永远拿不到模型密钥。
它可以对接任何 OpenAI 兼容端点。在模型名上加 vllm: 前缀即可选用 Pydantic AI 的 vLLM provider,它会按照 vLLM 服务器期望的方式,针对不同模型家族(Qwen、DeepSeek、GLM、Llama 等)组织请求。每个 context 对应一段对话,保存在 agent 自己的磁盘上,因此同一 context 里的后续任务会在 agent 存活期间延续这段对话。如果要迁移到新实例,则走 snapshot 流程,保存并恢复对话,必要时还包括工作区。MCP 服务器、skills、对等 agent 和实时轨迹都通过标准 A2A 扩展传递。
如果你已经在生产环境使用 Pydantic AI,现在你拿到的是同一个 agent,只是放进了一个可以打分的沙箱里。Harness 是 Pydantic AI agent 背后的能力库,也就是最近新增 You.com 网络搜索和研究功能的那一个。
试用
安装框架并验证它能跑起来:
uv tool install agentenv-framework agent-env run hello
默认没有任何配置,所以你需要提供一个模型端点,并把 Pydantic AI 设为所有未指定 agent 的任务步骤的默认 agent。端点可以是任何支持 OpenAI chat completions API 的服务。本例使用 Logfire Gateway。在 Gateway 的 Settings 中开启 Telemetry 并选择一个项目,之后 agent 用 Gateway API 密钥发出的每一次模型调用,都会作为 span 出现在 Pydantic Logfire 里,agent 代码无需任何改动。URL 中的 openai 是 provider 路由,us 是 Gateway 区域。Gateway 的 Connect 页面会为你的组织生成这个 base URL,直接从那里复制即可:欧盟组织对应 gateway-eu.pydantic.dev。保持原样,不要加 /v1 后缀,因为 agent 会自己拼接 /chat/completions:
# .agentenv/config.toml [model] base_url = "https://gateway-us.pydantic.dev/proxy/openai" api_key = "env:PYDANTIC_AI_GATEWAY_API_KEY"
[model.roles] agent = "gpt-5.5"
[agents] default_a2a_agent_id = "pydantic-ai"
运行前先导出 PYDANTIC_AI_GATEWAY_API_KEY。env: 会在运行时读取它。其他端点的配置见 model provider 文档。
框架自带一个小示例包 mail-mcp:一个 MCP 服务器,里面有一个固定的收件箱,包含三封邮件,其中一封是发票;还有一个 verifier,负责检查能否找到这封发票。它的任务只部署环境并运行 verifier。复制这个示例包,然后在 tasks/smoke.json 里加两个步骤,把 Pydantic AI 接进来:
[ {"id": "env", "type": "deploy_env", "env_id": "mail"}, {"id": "assistant", "type": "deploy_agent", "env_ids": ["mail"], "a2a_agent_id": "pydantic-ai", "agent_name": "assistant", "depends_on": [{"task_step_id": "env"}]}, {"id": "find-invoice", "type": "prompt_agent", "agent_name": "assistant", "prompt_id": "find-invoice", "prompt": "Find the invoice in the inbox and tell me who sent it.", "depends_on": [{"task_step_id": "assistant"}]}, {"id": "finds-the-invoice", "type": "env_outcome_verifier", "env_id": "mail", "file_artifact_id": "check_mail", "verifier_id": "finds-the-invoice", "depends_on": [{"task_step_id": "find-invoice"}]} ]
运行你复制的版本:
agent-env run ./my-mail
agent 会通过 MCP 拿到收件箱的 search_emails 工具,它的回复和完整轨迹会写入本次运行的输出,verifier 会给结果打分,每次模型请求都会成为 Logfire 中的一个 span。第一次运行时框架还会构建环境所依赖的 gateway,需要几分钟。
想看看 Pydantic AI 和其他 agent 在同一任务上的表现差异?把 a2a_agent_id 改成 claude-code 再跑一次就行。同样的环境、同样的提示、同样的 verifier,只是换了一个 agent。
为什么这件事重要
在固定数据集上跑 eval 能发现回归,但发现不了那种因为收件箱和昨天长得不一样、就把正确的邮件发给错误的人的 agent。一个带有可复现种子的真实环境能抓住这类问题,而且它的 verifier 还能说明究竟哪里出了错。这正是我们希望 Pydantic AI 拥有的反馈闭环,也是每个 agent 框架都应该有的。
这个 agent 的代码在 AgentEnv Framework 仓库里,所有受支持 agent 的文档见这里。快去试试吧,有问题随时告诉我们。