Pydantic Deep Agents架构深度拆解:create_deep_agent()如何拼装出一个完整的Agent Harness

原创2026-10-15 18:20:331,689 阅读
文章标签:人工智能AI Agent多智能体工具调用MCP ClientsCLI

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 的实际运行效果,模型会思考、写文件、执行命令,全部在一个终端界面内完成:

Pydantic Deep Agents 终端 AI 助手 pydantic-deep 的 Agent Harness 运行界面

装配线总览: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 能"分身"的关键。装配逻辑分三块:

  1. 浅拷贝用户配置:调用方传入的 subagents 列表会被逐个浅拷贝,避免工厂函数注入配置时污染调用方的字典;
  2. 注入 planner:当 include_plan=True(默认开)时,自动追加一个名为 planner 的子代理,它提供 Claude Code 风格的 plan 模式——分析代码、向用户提问澄清、生成分步实施计划并保存为 markdown;
  3. 追加内置子代理:BUILTIN_SUBAGENTS(定义在 pydantic_deep/subagents.py)包含 general-purpose 通用执行者和 research 研究员,各自都是带文件系统、Web、Shell 的"完整 deep agent"。

每个没有自带工厂的子代理都会被注入 _default_deep_agent_factory,即递归地调用 create_deep_agent() 本身来创建——子代理也是完整的 deep agent,只是特性集做了裁剪(关掉 thinking、嵌套子代理、成本追踪等以节省 token)。

planner 子代理在创建研究计划后向用户发起澄清提问的界面

子代理并行工作时,每个任务卡片独立显示进度与完成时间,主代理只接收精简摘要,从而保护主上下文的 token 预算:

deep agent 主代理通过 task 工具并行生成多个 general-purpose 子代理的界面

步骤 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 能力协同工作的效果:

deep agent 使用文件系统工具集连续编辑 workspace 中的 report.md 文件

步骤 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 应用,都只是在这条流水线之上配置了不同的参数组合。

📚 延伸阅读:

登录后查看全文
pydantic-deepagents