Pi Subagents：Pi AI 助手的异步子 Agent 委托框架指南

做功能时需要有人同时做代码审查、技术调研、或实现另一个相关模块——传统做法是开多个对话窗口手动复制上下文。Pi Subagents 让 Pi Agent 在会话内 Spawn 子 Agent，分工协作，结果自动汇入主会话。

项目概览

为什么值得看

Pi Subagents 的设计思路值得 AI 工具链开发者关注：它把"委托"做到了极致——不需要写配置、不需要定义 Agent，只需要用自然语言描述你想做什么。系统自动解析意图、选择子 Agent 类型、管理并行或串行执行、将结果返回主会话。这种"意图驱动 + 自动路由"的做法，在 AI 原生工作流里是一种值得尝试的方向。

核心概念

Parent Agent（父会话）与 Child Agent（子会话）

安装扩展后，Pi 成为父会话。当用户描述需要委托的工作时，Pi 会启动一个专注的子 Pi 会话（Child Agent），赋予其任务目标，并在完成后将结果带回到父会话。

• 前台运行（Foreground）：流式输出，实时显示子 Agent 进展
• 后台运行（Background）：在父会话返回控制权后继续工作，可随时查询状态

安装即增强

安装扩展后，Pi 会获得一个 subagent 工具，但这个工具不会自动在后台启动任何东西，只是让 Pi 在判断需要委托时有了这个选项。你可以在 prompt 中自定义行为规则，例如"实现完成后自动运行 reviewer 子 Agent"。

内置 Agent 角色

Pi Subagents 内置了 8 种角色，覆盖了软件开发的常见分工模式：

推荐工作流编排

Pi Subagents 官方推荐的工作循环是：

clarify → planner → worker → fresh reviewers → worker

子 Agent 的默认上下文行为是forked context（继承父会话上下文），如果需要完全干净的子会话，在命令中显式传入 context: "fresh"。

子安全边界（Child Safety Boundaries）

这是 Pi Subagents 中一个被认真设计的安全机制：

1. Spawn 的子会话不继承 pi-subagents skill（避免递归委托）
2. Forked context 会过滤父辈的 subagent artifacts：包括旧的隐藏编排指令、slash/status/control 消息和父辈 subagent 工具调用历史
3. 默认子 Agent 不注册 subagent 工具：边界指令明确告知它"你不是父级编排器，不应提议或运行子 subagents"
4. 例外机制：如果父 Agent 明确允许嵌套 fan-out（tools: subagent），子 Agent 才会获得受 maxSubagentDepth 限制的子安全 subagent 工具

自然语言驱动的委托示例

安装后不需要学习任何命令格式，直接用自然语言：

# 获取第二意见
"Ask oracle for a second opinion on my current plan."

# 解决疑难bug
"Use oracle to help solve this hard bug."

# 并行代码审查
"Run parallel reviewers on this diff. I want one focused on correctness, one on tests, and one on unnecessary complexity."

# 审核直到干净
"Run a review loop on this change until reviewers stop finding fixes worth doing, with a max of 3 rounds."

# Scout + Planner 组合
"Use scout to understand the auth flow, then have planner turn that into an implementation plan."

Pi 会自动解析意图、决定使用哪个子 Agent、是否需要并行或链式执行。

动态调整 Agent 模型

内置 Agent 默认继承父会话的默认模型，保证新安装不需要依赖特定的模型配置。

单次运行覆盖：

/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"

持久覆盖（在 ~/.pi/agent/settings.json 或 .pi/settings.json 中）：

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "anthropic/claude-sonnet-4",
        "thinking": "high",
        "fallbackModels": ["openai/gpt-5-mini"]
      }
    }
  }
}

并行后台运行与进度追踪

并行后台运行时，每个子 Agent 的进度在父会话中直接可见，不存在"假 Chain 步"（即 Chain 模式下只有第一个完成后第二个才开始，实际上是串行假装成并行）。

状态查询支持：

# 查看当前所有异步运行
"Show me the current async runs."

# 诊断配置问题
"Check whether subagents and intercom are set up correctly."

适用边界

适合：

• 在 Pi 中进行复杂软件任务，需要多角度分析或分工协作
• 需要"第二意见"或"代码审查"的场景，但不想要切换窗口
• 探索性开发任务，需要 Scout 先侦察再 Planner 规划

不适合：

• 其他 AI 助手（不是 Pi）的用户需要类似功能（目前只有 Pi 可用）
• 需要在子 Agent 间共享复杂状态的场景（当前模型的上下文隔离机制尚不完善）
• 严肃的多 Agent 生产系统（Pi Subagents 定位是"AI 辅助个人工作流"，不是企业级多 Agent 编排引擎）

结语

Pi Subagents 把多角色协作融入了单一对话界面。并行审核、代码审查等工作流在很多工具链中都有，Pi Subagents 的差别在于把"委托"的认知负担降到最低——不需要配置、不需要定义 Agent 模板，用你想做事的方式说出来，Pi 自己完成路由和执行。