文档核心能力

子智能体

子智能体把工作拆出去:主智能体理解需求、做计划、写最终答复;子智能体负责跑工具、读代码、驱动 CLI 或调用远程端点。

Rabbit Chat Studio 支持三种运行时:

类型 运行位置 适合
llm 应用内,自带工具循环 推理、调研、总结、可控的工具使用
cli 本机安装的无头编程 CLI 大规模改代码、重构、跑测试
cloud 远程 HTTP 端点 已有远程智能体服务、隔离执行

磁盘上的定义

llm 智能体的身份与提示词存在 Markdown 文件里,不在 sub_agents.json 中:

<应用数据>/agents/
  <分类>/<slug>.md   # 导入/库内定义(面板里只读)
  custom/<slug>.md   # 面板里创建的智能体
  index.yaml         # 发现清单,点"刷新"时替换
  • 文件是 YAML frontmatter(name、description、emoji、color)加正文系统提示——与技能同构。
  • sub_agents.json 只留运行时开关(enabled、model、token 上限、allowed_tools、allowed_skills、max_iterations、enable_mcp)和 file 引用。cli / cloud 智能体的完整定义仍在其中。
  • 发现是显式的:打开面板只读 agents/index.yaml;只有 刷新 才重扫目录并替换清单。上次刷新后新增的文件在下一次刷新前不可见。
  • 被发现但没有配置条目的文件列为一个禁用的虚拟智能体(configured: false),在你启用或编辑它之前不会写进 sub_agents.json。
  • 只有 agents/custom/** 能从面板删除;库内文件在面板里只读——请改为禁用。
  • 面板保存只会在解析后的定义确实变化时重写文件,并先留 .bak.<n> 备份。
  • 旧版内联 llm 提示(旧 sub_agents.json 或旧配置)会自动迁移成 Markdown 文件。

面板与编排

点顶部工具栏的 Agents。编排相关设置(自动规划、智能选择 agent、执行模式、并发、每对消息上限)收在面板的分组开关里,默认把空间留给智能体列表:折叠时只留总开关「子智能体系统」,展开后才是下面这几层开关。

子智能体系统(use_agents)

总开关,决定这套系统是否存在。

  • 关:主智能体直接回答,call_subagent 既不下发也不可调用。
  • 开:call_subagent 下发给主智能体,随时可以手动委派;是否自动规划交给下一层开关。

自动规划(auto_plan,默认开)

  • 关:不做规划,主智能体直接作答;call_subagent 仍然可用,需要时由模型自己调用(手动委派)。

  • 开:只要至少有一个子智能体启用,每条用户消息都先走编排:

    1. 规划器用主模型把需求拆成任务;
    2. 每个任务指派给一个子智能体;
    3. 任务并行或串行执行;
    4. 任务报告注入主智能体上下文;
    5. 主智能体写最终答复。

    编排失败(没有启用的智能体、规划失败)时记一条警告并退回直接回答。

    执行期间,聊天流会显示计划开始、任务开始/流式/完成/报错与汇总事件。

    委派闸门:选择调用只提出候选名单,规划请求本身再回答一次"要不要委派"。明确说不就跳过本次任务——选择结果记为已谢绝,主智能体独自作答。名单芯片只在规划器确认后才发出,所以被谢绝的计划不会留下过期名单。只含一个任务的计划也是合法的。

    实时任务行:每行自带状态——运行中显示思考计数与工具活动行,已停止的任务显示中性状态而不是完成,供应商错误只出现在任务行上,绝不会变成关闭你这一轮的聊天错误。

自动规划开着时每条消息都要付规划开销。简单问答就关掉自动规划(仍可手动委派),或只留一个轻量智能体。

智能选择 agent(auto_configure)

开启后,规划之前先用一次模型调用挑选本轮参与的子智能体,再交给规划器;任务类型变化很大时有用,代价是多一次 LLM 调用。关闭时所有已启用的子智能体全部参与,由规划器自行取舍。这个开关只在自动规划开启时生效。

执行模式

模式 行为
并行 任务并发执行,受 最大并发 限制
串行 按计划顺序逐个执行

规划器也可以把某个计划标为串行;以计划为准。

最大并发 1–10,默认 3。

智能体列表

每个智能体显示:

  • 启用开关;
  • 名称与类型徽标(LLM / CLI / Cloud);
  • 状态(运行中 / 完成 / 报错);
  • 目标(模型、命令或端点);
  • 最近摘要 / 错误 / token 用量;
  • 编辑与删除按钮。

列表可按启用状态筛选——全部 / 已启用 / 已禁用——并与搜索框叠加。

工具栏 Agents 旁的数字是已启用的智能体数量。

任务总线与规划器接管

每个由规划器派发的任务会建一个进程内发布/订阅总线(mbus):规划器与计划内任务是同级,broadcast 到达所有人,支持 +/# 主题订阅,总线还维护任务的实时状态登记。消息只在子智能体的下一个请求边界送达,绝不在流式输出中途插入。

  • 每对上限 —— 面板设置 每对智能体消息数(默认 4,0 为关闭)。双向合并计数;主题发布对每个接收者分别计数;规划器豁免。两个智能体撞到上限时,最后那条仍然送达,规划器被通知一次,此后这对之间的消息被拒并附"已通知规划器",让规划器去协调而不是让两者互相刷屏。
  • 规划器接管 —— 规划器可以用两个总线动作干预运行中的任务:
    • direct(目标 + 目的 + 可选完成条件)在该任务上存一份权威目的,每轮重新渲染进任务提示,因此能扛住上下文压缩;
    • end_task(目标 + 可选说明)要求任务收尾;在它下一个推理边界,任务把当前结果作为成功上报,而不是再花一次请求。cli / cloud 任务无法轮询总线,所以 end_task 对它们会被拒。
  • 每个规划决策都会在聊天的智能体广播里留一行——schedule、send、status、history、subscribe、finish,以及"指令 → 目标"和"已结束任务"标记。

创建 LLM 子智能体

  1. Agents → + 新建智能体。
  2. 类型:LLM。
  3. 名称与描述。描述会出现在主智能体的可用智能体列表里,把职责写清楚。
  4. 系统提示:角色、输出格式、边界。
  5. 模型(可选):留空继承主模型,填写则覆盖。
  6. 最大补全 token 与温度(可选)。
  7. 最大迭代:默认 10;0 表示不限(由外部任务状态决定何时停)。
  8. 可用工具:勾选 file_actions / run_cmd / run_shell 的子集;有 全选 / 全不选 快捷键。
  9. 保存并启用。

面板只提供这三个执行类工具,timer 永远被过滤。每个 llm 子智能体还默认带 memory 工具,且记忆作用域与主智能体共享:session 按主对话的 session_id 归属(主智能体 + 所有同级任务),user / repo 在 <工作区>/.data/memory,evolution 在自我进化模式下存在。子智能体提示要求它开工前先搜记忆、收工前记一条简明结论;它从不执行 consolidate。cli / cloud 智能体调不了应用工具,因此拿不到记忆摘要。自我进化模式下子智能体额外获得 file_actions,因为它可能要演进技能。

任务的静态提示里还带一段主对话摘要(MAIN CONVERSATION,最多 12 条 / 12 KB):委派时给的 description 与 context 可能很薄,这段摘要让它看到用户的原话。它只用于理解背景,任务描述仍然是权威的。

sub_agents.json 里还有 allowed_skills 字段,但面板不暴露它,运行路径也不按它过滤技能;技能由主智能体加载。

创建 CLI 子智能体

CLI 智能体启动本机安装的无头编程 CLI,把任务作为提示传入,并流式读回输出。

必填

字段 说明
命令 可执行名(经 PATH 解析)或完整路径;Windows 的 .cmd / .bat / .ps1 会被处理
参数 每行一个;支持 {prompt}、{model}、{cwd}、{agent_name}
提示传递 作为参数({prompt}) 或 经标准输入

可选

字段 说明
模型参数 每行一个;每次运行都追加——直接写模型 id(如 -m 与模型各占一行)。不继承主配置
环境变量 每行一个 KEY=VALUE;默认含 NO_COLOR=1、CLICOLOR=0、FORCE_COLOR=0、TERM=dumb;同名覆盖
工作目录 相对工作区的目录;留空为工作区根;会做沙箱检查
默认超时 秒,默认 600;0 = 不超时
需要批准 首次运行前询问;关闭后启用开关即长期授权

每次运行都是全新的 CLI 会话,不跨调用保留状态;非零退出或超时会把任务记为 failed。

内置无头调用

参数为空时,已知 CLI 自动套用无头形式:

命令 默认参数
opencode run {prompt}
claude -p {prompt}
codex exec {prompt}
gemini -p {prompt}
qwen -p {prompt}
crush run {prompt}
droid exec {prompt}
cursor-agent -p {prompt}
copilot -p {prompt}
amp -x {prompt}

显式参数永远优先;默认值只在参数列表为空时套用。

示例:opencode

命令:opencode
参数:
run
{prompt}
提示传递:作为参数
工作目录:(空)
超时:900

等价于:

opencode run "<任务>"

测试

编辑器里点 测试:

  • CLI:执行 <命令> --version,显示解析到的路径、退出码与输出;
  • Cloud:对端点发一次 GET,显示可达性、HTTP 状态与详情。

运行行为

  • 子进程 cwd 是工作区(或配置的相对 cwd),并同步 PWD;
  • 输出流向前端并剥离 ANSI 颜色码;
  • 超时、Stop、退出应用会杀掉整棵进程树(Unix 进程组 / Windows job);
  • 非零退出或超时把任务标为 failed(不会出现绿色"完成"徽标);
  • Windows 上不弹控制台窗口;
  • 若提示里可能含 cmd.exe 会展开的文本(如 %VAR%),优先用 stdin。

创建 Cloud 子智能体

请求

字段 说明
端点 URL 接收 POST
令牌 可选,以 Authorization: Bearer <token> 发送
额外请求头 每行一个 KEY=VALUE
请求体模板 JSON;替换并转义 {prompt}、{agent_name}、{cwd}
结果路径 响应中文本的点路径,如 choices.0.message.content 或 result.output
超时 秒,默认 1800

默认请求体:

{"messages":[{"role":"user","content":"{prompt}"}]}

默认结果路径:

choices.0.message.content

异步轮询(可选)

若远端是"提交任务 → 轮询结果":

字段 说明
轮询 URL 如 https://api.example.com/jobs/{id};{id} 会被替换
任务 id 路径 首次响应里的点路径,默认 id
状态路径 轮询响应里的点路径,默认 status
完成值 每行一个;默认 completed / succeeded / success / done / finished
失败值 每行一个;默认 failed / error / cancelled / canceled
轮询间隔 秒,默认 5

轮询 URL 留空表示只取一次响应。

call_subagent

编排开启时,主智能体还会得到 call_subagent:

{
  "agent_id": "精确的智能体 id",
  "task_description": "自包含的任务描述",
  "context": "可选补充上下文",
  "run_in_background": false
}

规则:

  • 子智能体看不到当前对话;task_description 必须自包含。
  • context 会附加到任务描述后;用于放文件路径、发现与约束。
  • 主智能体等待结果。
  • 开启 设置 → 运行时与调试 → 后台执行 后,run_in_background: true 立即返回 bg-… id:子智能体继续跑,主智能体继续干活,报告在它下一个请求前送达(期间本轮保持打开)。子智能体自己永远拿不到这个开关。
  • 每次调用(以及每次规划任务)都有一个交付物交换目录:<工作区>/.data/deliver/<会话 id>/<批次 id>/,含一个 shared/ 和每个任务一个目录。子智能体的提示会点明自己的目录与共享目录;大输出应写在这里而不是硬塞进答复,依赖任务则被告知去读 <交换根>/<任务 id>/<文件>。任务报告与 call_subagent 结果会列出产出文件及大小,主智能体可用 file_actions 打开。
  • 交换区是长期保留的,没有自动清理。打开方式:标题栏 ⋯ 菜单 → 打开交付物文件夹、任务监视器刷新按钮旁的按钮,或任务面板的交付物列表(列出已完成任务留下的文件)。它纳入配置备份,并随会话一起删除。cloud 智能体够不到本地工作区,只能内联返回交付物;llm 与 cli 使用目录。
  • 最终答复仍由主智能体撰写;子智能体从不直接回复用户。

任务状态与监视器

每个子智能体任务在工作区 <工作区>/.data/chat.db 里有任务记录(agent_missions / agent_tasks)。

子智能体可以使用任务工具:

  • add_task
  • update_task_status
  • get_active_tasks
  • mark_mission_accomplished

打开 设置 → 运行时与调试 → 智能体任务监视器 可查看:

  • 任务状态、根任务描述、上下文;
  • 活动任务及其状态;
  • 任务产出的交付物;
  • 情节摘要;
  • 最终报告;
  • 创建/更新时间。

停止与失败

  • 生成过程中按 Stop:

    • 规划阶段:步骤之间检查取消,不再启动新子智能体;
    • 执行阶段:杀掉 CLI 进程树;云端轮询在两次之间检查取消标志并停止等待;剩余任务标为跳过;
    • 任务状态变为 stopped,不是 completed;
    • 主智能体不再继续写最终答复。
  • 单个子智能体失败不会拖垮任务;错误记在该任务上,其他任务继续。

  • 达到最大迭代仍未 mark_mission_accomplished,任务以未完成关闭。

批准

cli 与 cloud 智能体默认 需要批准:

  • 每个智能体在每次应用运行中首次执行前询问一次;
  • 允许后本次运行不再询问;
  • 关掉它,启用开关就是长期授权;
  • 这属于 external_agent 确认类型,不在 工具 → 自动接受 覆盖范围内——后者只覆盖内置命令的 L0–L3 确认。

外部智能体跑在应用之外:CLI 以你的用户权限运行,Cloud 把任务发到远程端点。只启用你信任的智能体。

最佳实践

  • 描述里写清"它负责什么、输出什么、不许做什么"。
  • 给最小的 LLM 工具集;只读任务别给 run_shell。
  • 按任务设 CLI 超时;大重构可能需要 1800–3600 秒。
  • 先用测试或 curl 验证云端结果路径。
  • 简单问答关掉编排;复杂多文件工作再开。
  • 并行任务不要写同一批文件,否则互相覆盖。

常见问题

现象 排查
编排开着却直接回答 有启用的智能体吗?编排失败了吗?看日志/任务监视器
CLI 测试失败 命令在 PATH 里吗?Windows 是否需要 shell 包装?读 --version 输出
CLI 输出为空 参数把提示传进去了吗?试试 stdin;看超时与退出码
Cloud 401/403 令牌与请求头;是否还有其他认证要求
Cloud 结果为空 result_path 与响应 JSON 对得上吗?
轮询一直不结束 poll_status_path、完成值、轮询 URL
子智能体看不到文件 cwd、权限、工具白名单
新增的 agents/*.md 不出现在面板 点 刷新;面板读的是 agents/index.yaml,不是目录
发现的智能体是灰的 它在 sub_agents.json 里还没有条目:启用或编辑一次
删不掉库内智能体 只有 agents/custom/** 可删;请改为禁用
没有 run_in_background 设置 → 运行时与调试 里后台执行没开
Stop 之后仍有进程 正常会杀进程树;检查任务管理器与日志
任务监视器是空的 本次会话没有跑过子智能体;或工作区数据库换了?

源文件: docs/wiki/zh/sub-agents.md ↗ · 文档版本 v3.3.3