sub-pi-agent

把任务交给可复用的 Pi agent，让主 agent 专注规划和审查。

独立的 stdio MCP 服务，适用于 Codex 和其他 MCP 客户端。支持命名 agent、跨 MCP 重启保留上下文、提问交回和运行中纠偏；等待由 MCP 处理，无需主模型反复轮询。无需 Codex App Server、桌面事件注入或专用启动器。

怎么用

例如，让 Pi 检查一个模块并运行相关测试，主 agent 同时处理其他工作。Pi 缺少信息时交回问题，主 agent 回答后继续同一个会话；任务完成后读取结果并审查，需要修改时也不用从头交代背景。

快速开始

需要 Node.js ≥22.19.0，以及已配置模型和认证的 Pi。尚未配置时，先按 Pi 官方说明安装 CLI，运行 pi，用 /login 和 /model 完成配置。本服务内置 Pi SDK 1.2.0，读取同一套配置，不依赖全局 Pi CLI 执行任务。

1. 接入 Codex

把下面配置加到 ~/.codex/config.toml，然后重新加载 MCP：

[mcp_servers.pi]
command = "npx"
args = ["-y", "sub-pi-agent@0.1.1"]
startup_timeout_sec = 120
tool_timeout_sec = 600

Windows 若无法启动 npx，将 command 改为 "npx.cmd"。其他 MCP 客户端、源码安装及配置说明。

2. 派发第一个任务

在客户端让主 agent 调用 pi_spawn_agent，传入下面的参数。将 cwd 替换为实际项目的绝对路径：

{
  "name": "review-project",
  "description": "梳理项目结构和测试入口",
  "cwd": "/absolute/path/to/project",
  "task": "阅读项目说明，概括项目结构和测试入口。不要修改文件；缺少必要信息时交回问题。"
}

省略 model 使用该项目下的 Pi 默认模型。任务会调用模型，可能产生费用。

3. 等待并读取结果

保存返回的 session_id。有独立工作就继续做；没有时调用 pi_wait_agent，传入 {"session_id":"<返回的 ID>"}。

• done：调用 pi_get_result 读取交付并审查
• needs_input：调用 pi_poll_agent 读问题，再用同一 ID 调用 pi_continue_agent，将答案放在 task 中
• 等待超时：任务仍在运行，可以再次等待
• error / interrupted：用 pi_get_result 查看错误和部分结果

以上读取工具都使用同一个 session_id。任务结束后可用 pi_release_agent 卸载资源，之后仍能继续上下文。完整流程和参数见工具参考；首次接入可按冒烟测试验证。

使用边界

• Pi 以启动 MCP 的本机用户权限访问文件和执行命令，没有独立沙箱；请只在可信项目中使用
• 会话和结果保存在本机，跨重启可恢复；MCP 退出会中断执行，需显式继续
• 没有反向实时通知，不会在上层聊天结束后自动唤醒主 agent

文档

• 安装与配置：客户端接入、模型设置优先级
• 工具参考：11 个工具、状态、纠偏、提问与未读提醒
• 数据与生命周期：存储目录、环境变量、恢复与权限
• 验证与排障：冒烟测试、常见错误和处理方法
• 开发与发布：测试、打包和发布

来源与许可

基于 Courtney Andrew Richardson 的 crichalchemist/agent-pi 1.8.0（f3ac8c1）修改，保留原版 MIT LICENSE。本版本增加持久化会话、提问交回、未读事件、等待与精简活动状态，并整理为独立 MCP/npm 入口。