Pydantic Deep Agents架构深度拆解:create_deep_agent()如何拼装出一个完整的Agent Harness
Pydantic Deep Agents架构深度拆解:create_deep_agent()如何拼装出一个完整的Agent Harness
Pydantic Deep Agents 是一款开源、可自托管的终端 AI 助手,而其框架的核心正是工厂函数 create_deep_agent() —— 只传入一个模型名,它就会拼装出一个完整的 Agent Harness:包含文件系统、Shell、任务规划、持久记忆、子代理(subagents)、上下文压缩与成本预算在内的完整 AI Agent 执行环境。本文逐步拆解这个拥有 70+ 参数的工厂函数,带你理清它的组装顺序、工具集(toolsets)清单、能力(capabilities)注册表以及运行时状态容器,新手也能看懂一个 deep agent 是如何被"搭积木"出来的。
为什么叫"Agent Harness" 🧩
Harness 本意是"挽具",在 AI 工程里指包裹在模型外面的一整套运行外壳。模型本身只会"说话",是 Harness 赋予了它动手能力:
| Harness 层 | 职责 | 对应组件 |
|---|---|---|
| 工具层 | 读写文件、执行命令、委派任务 | Toolsets(工具集) |
| 能力层 | 上下文压缩、记忆、成本预算、循环检测 | Capabilities(能力/中间件) |
| 提示层 | 按运行状态动态生成系统提示词 | Instruction Providers |
| 状态层 | 保存 todos、上传文件、检查点等运行状态 | DeepAgentDeps 容器 |
下面这张图就是由这套 Harness 驱动的终端 AI 助手 pydantic-deep 的实际运行效果,模型会思考、写文件、执行命令,全部在一个终端界面内完成:
装配线总览:create_deep_agent() 的 6 步构建流水线
工厂函数的核心实现在 pydantic_deep/agent.py。函数签名之前还有两个 @overload 声明(L509 与 L591),用于根据 output_type 做类型推断,让结构化输出也是 100% 类型安全的。
整个装配过程遵循一条固定流水线:
填默认值 → 组装子代理花名册 → 创建工具集列表
→ 注册能力列表 → 构建动态系统提示 → 创建 Agent 实例
| 步骤 | 做什么 | 关键代码位置 |
|---|---|---|
| 1️⃣ 填默认值 | 模型、workspace、execute 开关兜底 | agent.py#L1056-L1060 |
| 2️⃣ 组装子代理 | planner + 内置子代理 + 工厂注入 | agent.py#L1088-L1111 |
| 3️⃣ 创建工具集 | 按开关依次追加 all_toolsets |
agent.py#L1113-L1273 |
| 4️⃣ 注册能力 | 按开关依次追加 all_capabilities |
agent.py#L1386-L1510 |
| 5️⃣ 动态提示 | build_instruction_providers() |
instructions.py#L130-L178 |
| 6️⃣ 创建 Agent | Agent(model, **kwargs) + 注册 hooks |
agent.py#L1515-L1544 |
💡 工具集决定模型"能做什么",能力决定模型"怎么被约束和管理"。这两条列表就是 Harness 的骨架。
步骤 1:填默认值,先定好"工作区"
工厂函数第一步不是建工具,而是把三个最关键的默认值敲定(agent.py#L1056-L1060):
model缺省时回退到DEFAULT_MODEL;workspace缺省为StateWorkspace()—— 一个纯内存文件系统,不碰真实磁盘;- 若工作区是
StateWorkspace,include_execute会自动关掉,因为内存文件系统里根本没有命令可执行。
这一层设计保证了"零配置也能安全跑起来":不传任何参数,Agent 依然可用,只是没有 Shell。
步骤 2:组装子代理花名册 🎭
子代理(subagents)是 deep agent 能"分身"的关键。装配逻辑分三块:
- 浅拷贝用户配置:调用方传入的
subagents列表会被逐个浅拷贝,避免工厂函数注入配置时污染调用方的字典; - 注入 planner:当
include_plan=True(默认开)时,自动追加一个名为planner的子代理,它提供 Claude Code 风格的 plan 模式——分析代码、向用户提问澄清、生成分步实施计划并保存为 markdown; - 追加内置子代理:
BUILTIN_SUBAGENTS(定义在 pydantic_deep/subagents.py)包含general-purpose通用执行者和 research 研究员,各自都是带文件系统、Web、Shell 的"完整 deep agent"。
每个没有自带工厂的子代理都会被注入 _default_deep_agent_factory,即递归地调用 create_deep_agent() 本身来创建——子代理也是完整的 deep agent,只是特性集做了裁剪(关掉 thinking、嵌套子代理、成本追踪等以节省 token)。
子代理并行工作时,每个任务卡片独立显示进度与完成时间,主代理只接收精简摘要,从而保护主上下文的 token 预算:
步骤 3:创建工具集列表 🔧
工具集是"一批相关工具的打包"。工厂函数按顺序把启用的工具集追加进 all_toolsets,每个都由一个 include_* 开关控制:
| 工具集 | 开关参数 | 给模型什么能力 |
|---|---|---|
| TodoToolset | include_todo(默认开) |
任务清单规划与追踪 |
| ConsoleToolset | include_filesystem(默认开) |
读写文件、编辑、执行 Shell 命令 |
| SubAgentToolset | include_subagents(默认开) |
task 工具,委派子任务给子代理 |
| SkillsToolset | include_skills(默认开) |
从目录发现并加载 SKILL.md 技能 |
| ContextToolset | context_files / context_discovery |
管理 DEEP.md 等上下文文件 |
| CheckpointToolset | include_checkpoints |
保存/回滚会话快照 |
| TeamToolset | include_teams |
组建多智能体团队、共享 todo、消息互通 |
| MonitorToolset | include_monitoring(默认开) |
后台监视命令并即时反应 |
| HistorySearchToolset | include_history_archive(默认开) |
检索被压缩前的完整对话历史 |
| ForkToolset | forking |
运行中分叉成并行分支,由 AI 裁判合并 |
| MCP / 自定义 | mcp_servers / toolsets / tools |
接入 MCP 服务器与用户自有工具 |
文件系统工具集是 Harness 的"手"。下面这张图里,Agent 正在连续调用 edit_file 工具精确替换文件内容,右侧面板实时展示工作区文件树——这正是 ConsoleToolset 与 workspace 能力协同工作的效果:
步骤 4:注册能力列表 🛡️
能力(Capability)是 Pydantic AI 的能力接口,可以理解为包裹在运行生命周期外的中间件。工具集给模型"手",能力则负责"管":管 token 预算、管成本、管安全。
all_capabilities 按顺序注册的核心成员包括:
| 能力 | 作用 |
|---|---|
workspace 能力(如 StateWorkspace) |
为每次运行提供文件与命令环境 |
PatchToolCallsCapability |
修复中断会话遗留的孤立工具调用 |
EvictionCapability |
超大工具输出(默认 20,000 token)自动落盘、只留预览 |
HooksCapability |
Claude Code 风格生命周期钩子(PRE/POST_TOOL_USE) |
CheckpointMiddleware |
按频率自动保存会话快照 |
StuckLoopDetection |
检测重复工具调用死循环并告警 |
ContextManagerCapability + LimitWarnerCapability |
70% 预警、90% 触发 LLM 自动摘要压缩,实现"无限上下文" |
CostTracking |
统计 token/USD 成本,超预算抛 BudgetExceededError |
WebSearch / WebFetch / Thinking |
联网搜索、抓取网页、推理强度控制 |
| Memory 能力 | 跨会话记忆:MEMORY.md 注入每次请求,其余笔记按需检索 |
注意一个细节:Memory 能力被刻意放在列表最后(agent.py#L1485-L1495),因为它的笔记注入若排在压缩/历史处理器之后,就会被改写甚至摘要掉。注册顺序本身就是语义。
步骤 5:动态系统提示,按运行状态"现做"
静态 instructions 无法反映运行中状态,所以工厂函数用 build_instruction_providers() 组装一串提示词供应商(pydantic_deep/instructions.py),再通过 @agent.instructions 装饰器注册一个动态钩子(agent.py#L1534-L1537):
- uploads 段:列出用户上传的文件路径与大小;
- todo 段:静态的任务流工作流说明(刻意静态,保护 prompt cache 前缀);
- console 段:按
edit_format渲染文件编辑格式说明; - subagents 段:列出当前可用的子代理花名册;
- web 段:声明联网工具可用。
每一轮模型调用前,render_instructions() 把非空段落拼接成最终系统提示。开启 tool_search=True 时还会自动切换为精简版提示,配合工具懒加载进一步压缩输入 token。
步骤 6:创建 Agent 并暴露运行时句柄
最后一步水到渠成(agent.py#L1515-L1544):
agent = Agent(model, **agent_create_kwargs) # deps_type + toolsets + capabilities
返回前,工厂函数还把两个运行时句柄挂到实例上:agent._context_middleware(供 CLI 的 /compact、/context 命令直接操作压缩器)和 agent._task_manager(供 /fork 等命令管理子代理任务)。框架层的一行 create_deep_agent(model="..."),最终交付的就是这样一个带全套 Harness 的 Agent 实例。
贯穿始终的运行时容器:DeepAgentDeps 📦
工具和能力都要读取"当前运行状态",这些状态集中存放在 DeepAgentDeps 数据类里:
todos:任务清单;uploads:用户上传文件;ask_user:交互式提问回调(planner 靠它向用户提问);checkpoint_store:会话级检查点存储;message_queue:运行中消息投递;fork_coordinator:Live Forking 分叉状态。
子代理执行时调用 clone_for_subagent() 克隆出一份新容器,按规则选择性共享:workspace 和 uploads 共享、todos 可按 share_todos 共享、fork 与 monitor 状态则强制隔离——子代理是独立的隔离域。
常用开关参数速查表 ⚡
70+ 个参数不用死记,常用的开关如下:
| 参数 | 默认值 | 一句话说明 |
|---|---|---|
include_checkpoints |
False |
会话快照,forking 场景建议开启 |
forking |
False |
运行中分叉并行分支 + AI 裁判合并(收费能力,显式开启) |
include_teams |
False |
多智能体团队协作 |
context_manager |
True |
token 追踪 + 自动压缩,"无限上下文"的开关 |
cost_tracking |
True |
成本统计,配 cost_budget_usd 可设预算上限 |
stuck_loop_detection |
True |
重复调用死循环检测 |
thinking |
"high" |
推理强度,"minimal"~"xhigh" 五档 |
web_search / web_fetch |
True |
联网搜索 / 网页抓取 |
不想手填参数?用 Spec 引擎声明式建 Agent 📝
create_deep_agent() 的全部常用参数都镜像到了一个 Pydantic 模型 DeepAgentSpec(pydantic_deep/spec.py),配合工厂类 DeepAgent 可以直接用 YAML 声明 Agent(spec.py#L147):
model: anthropic:claude-opus-4-6
instructions: You are a helpful coding assistant.
include_todo: true
include_filesystem: true
include_memory: true
memory_dir: .pydantic-deep
retries: 3
DeepAgent.from_file("agent.yaml") 会自动完成三件事:Pydantic 校验(extra="forbid" 保证拼错参数名直接报错)→ 拆出不可序列化的透传项 → 调用 create_deep_agent() 返回 (agent, deps) 元组。
写在最后
回过头看,create_deep_agent() 的本质是一条确定性的装配流水线:先定默认值,再拼子代理,然后两条列表(toolsets + capabilities)按开关逐项追加,动态提示按运行状态渲染,最后交给 Pydantic AI 的 Agent 收尾。理解了这条流水线,你就掌握了 Pydantic Deep Agents 的骨架——无论是终端助手 CLI 还是 deepresearch 应用,都只是在这条流水线之上配置了不同的参数组合。
📚 延伸阅读:
- Agent 工厂 / Deps 容器 / Spec 引擎深度解析:docs/c4/4a-deep-dive-agent-factory.md
- Agent API 参考:docs/api/agent.md
- 能力系统详解:docs/advanced/capabilities.md
- 最小示例:examples/basic_usage.py



