文档 · MCP 工具
MCP 工具
每个支持 MCP 的工具的会话，在启动和恢复时都会带上 agent-manager MCP 服务器，因此智能体能以原生工具的形式看到整个工作区：它自己的会话、在旁边运行的其他智能体、它们所属的分组，以及受管理的终端。无需为每个项目单独配置。该服务器内置在同一个二进制中（agent-manager mcp，stdio），通过环境变量识别发起调用的会话。
工具一览
| 工具 | 智能体用它做什么 |
|---|---|
| rename | 在弄清工作内容后给自己的会话命名，替换占位名。 |
| review | 一次调用声明要审查的仓库、base ref 和 diff 范围。 |
| review_comment | 用审查提示词中的固定评论 id，把一条已发送的审查评论标记为已处理。 |
| list_sessions | 列出所有智能体会话，包括 id、CLI、分组、目录、worktree 分支和状态。 |
| create_session | 为一个指定任务启动另一个智能体 CLI，可选在独立的 git worktree 中。 |
| read_session | 读取另一个智能体屏幕上当前显示的内容。 |
| send_session | 给另一个智能体排队一条消息，在它静止时送达。 |
| message_status | 查看消息是排队中、暂缓、已送达、已丢弃还是已回复。 |
| wait_for_session | 挂起等待另一个会话停止工作，而不必轮询它。 |
| revive_session | 恢复已结束的会话，接上它原来的对话。 |
| kill_session | 结束运行中的智能体，保留它的行和最后的屏幕。 |
| archive_session | 把完成的会话移出活动列表，或将其还原。 |
| archive_self | 在当前回合结束后归档发起调用的会话，效果同 a。 |
| kill_self | 在当前回合结束后结束发起调用的会话，保留行以便恢复，效果同 x。 |
| task | 共享工作列表合并为一个工具：action 取 list、create、claim、finish、release 或 delete。 |
| reserve_files | 声明本会话正在编辑的文件，并查看还有谁占用了它们。 |
| release_files | 归还这些占用。 |
| list_reservations | 查看每个会话当前正在编辑什么。 |
| list_groups | 列出分组及其默认目录、worktree 默认值和会话数量。 |
| create_group | 添加一个分组（用斜杠路径表示嵌套），用来归置一批会话。 |
| delete_group | 删除工作已完成的分组；仍在其中的会话会移到根节点，而不会被停止。 |
| list_terminals | 列出活动的受管理终端及其当前目录。 |
| create_terminal | 在发起调用的会话下打开一个终端，如果该会话本身是终端则开在它旁边，除非 nest 为 false。 |
| send_terminal | 向运行中的终端提交命令或发送精确的按键。 |
| read_terminal | 读取终端当前可见的纯文本内容。 |
| close_terminal | 关闭嵌套在调用者下、已完成的终端：结束面板并删除行。 |
| report_issue | 代用户在公开仓库上提交 bug 报告或功能请求。它先生成预览，在用户批准之前不发布任何内容，提交的内容与用户看到的完全一致。 |
启动和指挥其他智能体
你对一个运行中的智能体说“为这个启动一个智能体”。它调用 create_session，这和
n 表单给你的启动是同一个操作：名称、CLI、分组、工作目录、第一条提示词和 worktree
选项。新会话是列表中普通的一行。
每个字段的默认值与表单一致。CLI 默认为发起调用的智能体所用的 CLI，分组和目录默认为调用者的，明确指定的目录优先于两者。名称应描述工作内容；留空则生成一个占位名，并请新会话自己重命名。传入 worktree: true 会基于该目录的仓库添加一个 git worktree 和分支。model、effort 和 profile 让 CLI 以它列出的值启动，与表单中的行一样，CLI 未列出的值会被拒绝，并返回它支持的值。saved 指定一条已保存的提示词放在任务前面，send_session 也接受它。
read_session 返回目标当前的屏幕，会话停止后则返回最后捕获的屏幕。kill_session
结束进程，把行留作已结束状态并保留最后的屏幕。revive_session 让它在原来的对话上恢复。archive_session 把完成的行归档或将其还原。
结束自己的会话
智能体用 archive_self 或 kill_self 结束自己的会话（在 shell 中为
agent-manager archive-self 和 kill-self），所以“合并后把自己归档”这种要求无需回到列表操作。调用会登记请求并立即返回，智能体把回复写完，管理器在第一次读到该会话处于静止状态的轮询时执行。在此之前，该行名称旁边显示 ↓（归档）或 ■（结束）。按 c，或在该行菜单中选 Cancel，可以保留会话，智能体也可以用 cancel
撤回请求。
智能体之间的消息
send_session 把消息排队，而不是立即输入。有些智能体 CLI 在审批对话框下方仍然绘制输入行，此时写入的消息会变成对对话框的回答，而不会被当作消息读取。管理器会暂存消息，在目标静止后的第一次轮询时输入：它的输入区域已绘制，状态不在回合中，提示符处也没有人写了一半的内容。
消息送达时会标明来自用户的另一个智能体会话，附带发送者的名称和用于回复的 id。接收方智能体将其视为同一操作者的指令，完成其中要求的常规工作。权限提示和该会话的 CLI 设置仍由键盘前的人掌控，提交、推送、合并、发布和删除也是如此。message_status 报告消息是排队中、暂缓、已送达、已丢弃还是已回复。
send_session
会在结果中说明这一点。
等待与共享任务列表
wait_for_session 让单次工具调用挂起，直到某个会话进入表示停止工作的状态之一，这样分派了工作的智能体就不必循环读取屏幕。超时会返回该会话的当前状态，reached 为 false，因为超时是一种答案，而不是失败。
任务列表是管理器的共享待办清单，所有会话都可见，全部通过 task 这一个工具操作。create 添加工作，claim 认领一项，finish 标记完成，并解除所有依赖它的任务的阻塞。认领是一次原子写入，所以两个智能体抢同一个任务时不可能都成功。
文件占用
当工作可以干净地拆分时，每个会话一个 worktree 就能避免两个智能体覆盖同一份检出。reserve_files
用于另一种情况：有意共用同一份检出的会话声明它们即将编辑的路径。与其他会话持有的占用重叠时会返回冲突，并指出持有者，两者可以在任何一方提交之前通过 send_session 协商解决。占用只是建议性的：不会阻止任何操作。
终端
create_terminal 默认嵌套在发起调用的会话下，除非 nest 为 false；从终端发起的调用会把新 shell 开在它旁边。它默认使用调用方智能体的分组和面板当前所在目录。close_terminal 在任务完成后结束面板并移除行，且只能作用于嵌套在调用会话下的终端。send_terminal 只接受以下两者之一：一条命令（粘贴后按 Enter 提交），或一串 tmux
按键名，例如 C-c、Up 和 Enter。
服务器的说明会告诉智能体何时使用这些工具。智能体按照 coordination
模式对待其他会话，并为 SSH 这类需要人看到的工作打开终端。它们会先列出并复用正在运行的终端，发送命令并在任务运行时读取屏幕，任务结束时调用 close_terminal，除非该终端是留给用户的。
send_terminal 要像在已进入的 shell 里打字一样谨慎，并如实看待
create_session 和 kill_session：前者启动一个会消耗 token 的真实智能体进程，后者会打断一个可能正在执行任务的智能体。
其他机器上的会话
添加 SSH 连接后，list_sessions、list_terminals 和 list_groups 会刷新每个连接，并在本机的行之后列出它的行，每行的 host 设为连接名称，id 写作 host::id。无法刷新的主机永远不会让列表调用失败：它上次的行会带着 stale: true 返回，connection_errors
说明原因。
read_session、send_session、kill_session、revive_session、archive_session、read_terminal、send_terminal 和 close_terminal 接受 host::id，并在那台主机上执行。create_session、create_terminal、create_group 和
delete_group 接受 host。发往那里的消息无法用 message_status
跟踪，请改为读取智能体的屏幕。只有在那里打开终端的会话才能向它发送内容或关闭它。wait_for_session、task 和 review_comment 拒绝
host::id，因为这些状态保存在各自的主机上。
协作模式
设置（s）中的 coordination 行决定智能体在多大程度上主动与其他会话打交道。默认值 on request 会告诉每个新会话其他会话的存在，并且只有在你要求时，它才会列出、发消息给、启动或等待其他会话，以及创建或认领共享任务。“为这个启动一个智能体”照样有效，因为所有工具都保持注册。proactive 让智能体无需等你开口，就把可并行的工作分派给新会话，并在开始工作前查看共享任务列表。会话在启动时获得说明，所以已在运行的会话保持它们启动时的模式。
注册
注册按工具自动进行。内置工具会自行注册：
| 工具 | 注册方式 |
|---|---|
| claude | 生成的 --mcp-config 文件。 |
| codex | 命令行上的 -c mcp_servers… 覆盖项。 |
| opencode | 一个 OPENCODE_CONFIG 合并文件。 |
| grok, gemini, command-code | 首次启动时一次性添加的 mcp add --scope user 条目。 |
| antigravity | 首次启动时一次性执行 agy mcp add，写入 ~/.gemini/config/mcp_config.json。 |
| hermes | 它自己的一次性 mcp add 流程，需要其安装程序视为可选的 MCP SDK。仍缺少该 SDK 的 Hermes 会拒绝启动，并弹出对话框，给出适用于运行 Hermes 的那个 Python 的 pip install mcp 命令。 |
| cursor | 首次启动时把 agent-manager 服务器写入 ~/.cursor/mcp.json，并运行 cursor-agent mcp enable agent-manager。 |
| muse | Muse 只从它的设置文件读取 MCP 服务器，所以首次启动时会把 agent-manager 服务器添加到 ~/.config/muse/settings.json，并保留其他所有设置和服务器。 |
Pi 和 Oh My Pi 没有 MCP 注册，它们的会话使用下面的子命令。CLI 不在 PATH 上的启动请求会以同样的方式被拒绝：内置智能体给出厂商的便携安装程序，其他的则给出本机的包管理器命令。
在 shell 中做同样的事
Pi 和 Oh My Pi 会话通过子命令访问同一个工作区。agent-manager --help 列出这些子命令，从 sessions、spawn、send 和 wait，到共享任务列表、文件占用、终端和审查声明。每个子命令都以它所在的会话或终端的身份执行。
agent-manager rename "auth token refresh"
agent-manager review-repo /path/to/repo
agent-manager review-base main
agent-manager spawn --name "cover the parser" --prompt "write the tests"
agent-manager archive-self在脚本中使用
一个脚本遍历工单列表，为每张工单打开一个智能体。sessions、groups、snapshot、spawn、read、wait、kill、revive、archive、create-group 和 delete-group
在没有调用者时也能运行，所以 Agent Manager 之外的脚本、cron 任务或 CI 步骤也能打开会话，并显示在你的列表中。这样的 spawn 使用设置中选定的 CLI，位于根分组和脚本运行时所在的目录，除非用 --tool、--group 或 --directory 另行指定。--model、--effort 和 --profile 决定 CLI 启动时使用的值。
agent-manager spawn --tool claude --group "Sprint Manager" --worktree \
--name ticket-123 --prompt "Fix TICKET-123 and open a pull request" --json
排队的消息、状态，以及回合结束后的归档和结束，只有在管理器运行时才会推进。agent-manager serve
运行一个没有界面的管理器，适用于没人一直开着 TUI 的机器，serve --background 以后台方式启动它，日志写入 agent-manager 数据目录（存放 state.db 的目录）中的 serve.log。每个数据目录只运行一个。它支持 macOS 和 Linux。