Pydantic AI Harness是 Pydantic AI 官方的能力（capability）库，其中的Code Mode（CodeMode）能力让 Agent 摆脱"每次工具调用都要跑一轮模型"的传统模式：模型只需编写一个 Python 脚本，就能在沙箱里一口气调用10 个甚至更多工具，用循环、条件、asyncio.gather并行取数，只把最终结果带回对话——延迟更低、成本更小，token 膨胀难题就此终结。

痛点：传统工具调用为什么"烧" token？🔥

标准工具调用模式下，Agent 每执行一批依赖调用，就需要一次新的模型往返：

比如"抓取 10 条数据再逐条处理"这类任务，传统方式下每个中间结果都会塞进对话历史；而 Code Mode 下，中间结果只存在于沙箱内存中，模型只看到最终答案。

Code Mode 如何工作：把工具变成函数

CodeMode会把符合条件的工具包装进一个名为run_code的沙箱工具（基于 Monty 沙箱运行时）。模型不再逐个发起工具调用，而是写一段 Python 编排代码，把工具当函数调用：

上图中，一次run_code调用就并行抓取了 3 个 HN feed、去重、按分数过滤并按评论数排序——全部在一段脚本里完成。

官方文档在 docs/code-mode.md，核心实现位于 pydantic_ai_harness/code_mode/ 目录。

快速上手：3 步启用 Code Mode

第 1 步：安装

Code Mode 依赖 Monty 沙箱，通过codemode附加组件安装（code-mode是等价别名，见 pyproject.toml）：

uv add "pydantic-ai-harness[codemode]"

pip 用户执行pip install "pydantic-ai-harness[codemode]"即可。

第 2 步：给 Agent 加上CodeMode()

from pydantic_ai import Agent from pydantic_ai_harness import CodeMode agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[CodeMode()]) @agent.tool_plain def get_weather(city: str) -> dict: """获取城市当前天气。""" return {'city': city, 'temp_f': 72, 'condition': 'sunny'}

第 3 步：照常提问

result = agent.run_sync("巴黎和东京现在多少度（摄氏度）？") print(result.output)

模型会在一次run_code内写出类似这样的代码：

import asyncio paris, tokyo = await asyncio.gather( get_weather(city='Paris'), get_weather(city='Tokyo'), ) {'paris': round((paris['temp_f'] - 32) * 5 / 9, 1), 'tokyo': round((tokyo['temp_f'] - 32) * 5 / 9, 1)}

两次天气查询并行执行，华氏转摄氏在沙箱内完成，对话历史里只多了一条紧凑的消息。

进阶一：只沙箱化你想沙箱的工具 🔧

默认CodeMode(tools='all')会收编所有符合条件的工具。你也可以精细控制，未选中的工具仍保持普通工具调用形式：

# 按名字：仅这两个工具进入 run_code CodeMode(tools=['search', 'fetch']) # 按谓词：排除危险工具 CodeMode(tools=lambda ctx, td: td.name != 'dangerous_tool') # 按元数据：适合共享工具集，用 .with_metadata(code_mode=True) 打标签 CodeMode(tools={'code_mode': True})

注意：Shell 类命令工具（如run_command）会保留为原生工具、与run_code并列，避免模型在生成的 Python 字符串里再套一层 shell 命令。

进阶二：eager 与 speculate 双提速 🚀

Code Mode 提供两种性能模式（实现分别在 pydantic_ai_harness/code_mode/_eager.py 和 pydantic_ai_harness/code_mode/_speculation.py）：

• eager=True（抢先执行）：模型还在逐行生成代码时，已写完的行立刻开始执行，工具延迟与模型生成时间重叠。
• speculate=[...]（推测执行）：流式接收代码的过程中，发现参数为字面量的只读工具调用就提前发起；脚本真正执行到时直接"认领"已在飞行的结果。也可传speculate='declared'信任工具自声明的read_only元数据。

agent = Agent( 'openai:gpt-5.6-sol', capabilities=[CodeMode(eager=True, speculate=['lookup_author', 'lookup_year'])], )

⚠️ 提醒：推测执行可能提前发起外部请求（即使最终用不到），请只把无副作用、可重复的工具列入白名单。

安全边界：沙箱限制与资源配额 🛡️

沙箱默认很"紧"，不用担心失控脚本：

• 无宿主访问：默认没有文件系统、环境变量、时钟；可用mount=MountDir(...)挂载目录、os_access注入环境变量；
• 资源上限：单次run_code默认 30 秒执行时间 + 256 MiB 内存，max_tool_calls默认 100 次嵌套调用；
• 受限标准库：仅允许sys、typing、asyncio、math、json、re、datetime、os、pathlib等，无第三方导入；
• REPL 状态延续：同一 Agent 运行内变量、导入在多次run_code间保留，传restart: true可重置。

返回值也很省心：代码的最后一个表达式自动作为结果返回，无需print()。

验证效果：用追踪面板看工具扇出 📊

配合 Logfire 或任意 OpenTelemetry 后端，run_code的每个 span 都会扇出为沙箱内发起的各个工具调用——这是理解 Code Mode 实际行为的最直观方式：

图中可见两次run_code分别扇出 3 个hn_get_stories并行调用和 3 个后续查询，token 消耗被压缩到 3 轮模型对话。

常用配置速查表

CodeMode还支持在 YAML/JSON Agent 规格中声明：

capabilities: - CodeMode: tools: ['search', 'fetch'] max_retries: 5

结语

Code Mode 用"让模型写代码调用工具"这一思路，把多轮模型往返压缩成一次沙箱执行：并行、过滤、聚合都在 Python 里完成，对话历史保持精简。只需一行capabilities=[CodeMode()]，就能让你的 Agent 告别 token 膨胀。

📚 更多资料：完整文档 docs/code-mode.md、模块说明 pydantic_ai_harness/code_mode/README.md、核心实现 pydantic_ai_harness/code_mode/_capability.py。