与子 Agent 协作¶
委派范围明确的任务,检查专用 Agent 实际完成的工作,并在需要修改时继续正确的会话。 Raven 同时提供委派任务与有状态 Agent 实例,两者不是一回事。
先按Agent 集成完成配置。本页介绍如何协作,不介绍传输安装。
宿主做什么、交出去什么¶
Raven 本身是你的 Agent 管家:把请求拆成任务、交给合适的子 Agent,跟踪每个任务
直到你认可结果,再把各 Agent 的汇报汇总成一个回答。回答里涉及的每个任务都单独成节、
配一个写明任务的小标题,不论写的是这个任务的结果,还是一句进展。它请你决定几件事、而你只答复了
其中一部分时,它会先处理你答复的部分,再在每次回复的末尾接着询问其余的,直到你逐一
做出决定、表示不做,或让它先放着。在网页上开着任务看板时,其余的问题改为留在看板上:
仍未回答的问题都列在各自任务的卡片里,所以回复只问新的问题。针对某个任务工作的后续消息,
无论是修改、追加的工作,还是问为什么这样做,都会交回做这件事的实例,它仍保有
上下文。闲聊、Raven 已经知道的内容,以及它自己记录的任务进展,由 Raven 直接回答;
任何要用到工具的工作,再小也交给最合适的 Agent,没有合适的 Agent 时才交给内置的
Raven-General:查找东西、核对结果、清理环境,和写脚本、写文档一样都交出去。Raven
自己干活时会占住这个会话,把工作交出去,它就能随时接你的下一句话。Agent 的汇报
先交给 Raven,网页上默认折叠、终端里只显示一行,所以汇报回来后,Raven 会用自己的话讲清做了什么、结果如何:
每条发现说清是什么,而不是只报汇报里的编号,下结论时也给出汇报里的依据。
如果会话运行在带 worker 的 Harness(例如 Persona)上,Raven 只把工作交给这些 worker;
没有 worker 负责的工作,它会告诉你并询问如何继续,而不是自己去做。
如果这一轮两个派发工具都被禁用,Raven 会自己完成工作。
在登记机器上工作¶
配置了 machine 的 Agent 会在那台登记机器上运行,在那里工作,文件也留在那里;
没有配置的 Agent 仍像以前一样在本机运行。登记机器、安装节点、配置条目,以及断线时会
发生什么,见在登记机器上工作。
远端 ACP Agent 可通过 Raven 节点使用配置授权给它的 MCP 服务器。服务器定义、 凭据、工具限制和沙箱规则仍在本机;节点按发起连接的进程判定每条流属于哪个任务, 本机再核对该任务与授权的对应关系,别的任务不能凭授权名称冒用。
系统支持 Unix socket 时,本机通过 Unix socket 提供每个授权的服务器;否则(例如
Windows)监听 127.0.0.1 上的端口,只为出示该端点随机令牌的连接打开服务器,
令牌只留在本机。机器上的 CLI Agent 暂不借用 MCP;本机重启后可以接回任务结果,
但不会恢复之前的 MCP 连接。
选择协作形式¶
| 需求 | 方式 | 完成证据 |
|---|---|---|
| 单个专用任务 | 请宿主通过 spawn 委派 |
返回结果及相关文件/测试 |
| 并行或有依赖的工作 | DAG 编排 | 节点输出、依赖和 verdict |
| 重复已审核流程 | Playbook | 实际图结果,而不只是调度回执 |
| 继续与特定专用 Agent 协作 | 与其有状态实例直聊 | 该实例的回复/历史 |
| 执行并持续观察长任务 | Oncall | Campaign 状态与最终报告 |
spawn 和 run_subagent_dag 是模型工具,不是 Shell 命令。委派会增加模型调用,
也可能启动子进程或外部工作。
第一次只读协作¶
- 在项目工作目录中打开会话,检查目标 Agent 已启用且就绪。
- 请求:“让 Raven-Code 检查这个仓库的公开 API,不修改文件,返回带文件引用的 兼容性风险,再为我汇总。”
- 在 WebUI 子 Agent 面板或任务视图检查委派记录和结果。活动流只是进展,不是成功证明。
- 如果产生了可恢复实例,打开它并追问:“展开最高优先级风险,暂时不要修改实现。”
- 返回主会话,请主 Agent 把追问结果纳入最终总结。
没有准备好专用配置时,也可以使用通用 raven Agent。需要后续会话时选择有状态后端;
一次性的无状态任务不会自动变成可恢复聊天。
会话、实例与任务 ID¶
宿主 session 是你打开的主会话。实例由该 session 内的 Agent 和 handle 共同定位。 DAG 节点 ID 标识任务与输出,不是可以直聊的会话地址。
复用实例可以保留子 Agent 上下文,新建实例则开启独立状态。WebUI 可为启用且有状态的 Agent 创建实例,不必先由宿主委派。创建只记录 idle 实例,本身不会执行任务。
不要假设所有 Agent 都看到宿主的完整 transcript。应传入所需的具体要求和附件。 路径指向接收它的执行环境,不会自动把文件传到所有远程 Agent。
直聊与交接¶
子 Agent 面板展示实例历史,并在支持时提供面向该实例的输入框。直聊使用独立执行通道, 可以与宿主或其他实例并行,但忙碌的实例不一定能再接收普通轮次。
直聊记录与主 transcript 分开保存。下一次向主 Agent 发消息时,运行时提供 Handoff Block:实例身份、时间和已记录 prompt/result 的路径。 它不会粘贴整个交流,也不会自动生成语义总结。决策依赖这些内容时,应要求宿主读取相关记录。
宿主也会收到用户创建实例、直聊仍在运行的信息。这些是活动证据,不是完成证明。 忘记实例会移除它的访问地址,但不会删除用于审计的记录目录。
引导正在执行的轮次¶
Steer 向正在执行的轮次补充修正,而不是另起任务。例如:“只审查公开接口,不包含内部 helper。” 修正会在后续模型调用之前读取,不能撤销已经执行的动作。
服务端提供 subagents.instance.steer。客户端 UI 支持可能不同;当前 WebUI 实例
输入框发送普通直聊轮次,因此不能假定输入文字就会调用 steer。实现该 RPC 的客户端可发送:
{
"session_key": "HOST_SESSION_KEY",
"agent": "Raven-Code",
"handle": "INSTANCE_HANDLE",
"text": "Limit the review to public interfaces; do not edit files."
}
这是 RPC 参数,不是 CLI 命令。Session、Agent 和 handle 应从当前实例列表取得, 不要凭空构造地址。
| 回复 | 含义 |
|---|---|
injected |
已接收供当前轮次读取,不代表已按此行动 |
no_turn |
没有活跃轮次;仍需要时发送普通追问 |
unsupported |
本次运行的传输不支持中途引导 |
CLI-agent 和没有协商 Raven steering 扩展的 ACP Agent 不能假定支持此功能。 详见Agent 协议。
模型、模式与共享文件¶
实例公布模式或模型时,控制项使用该实例自己的菜单。模式覆盖可优先于宿主 session 的 tier,清除后恢复继承;清除模型覆盖则回到 Agent 自己的选择。两者都不会授予新文件或工具权限。
编程任务由宿主按内置的 multi-agent-coding skill 安排:同一个 Git 项目里有多个编程任务并行时,
宿主让每个编程 Agent 自己创建独立的 worktree 和以任务命名的分支,并汇报 worktree 的路径和分支。
改动留在这些分支上,直到你要求合并;worktree 也会一直保留,直到你要求删除。
同一个 skill 还让每个任务对应一个实例:未完成任务的后续要求交给该任务的实例继续,
某个编程 Agent 报告额度用尽时,任务转交给另一个编程 Agent。
创建 worktree 是编码 Agent 按宿主指令执行的一步,并发修改前应检查其汇报的路径和分支。 自行构建任务图时,应分配工作副本或明确文件所有权;调度器不会创建 worktree 或锁定文件。 Raven-Code 的共享工作目录报告可用于识别重叠。
排障¶
| 现象 | 检查 |
|---|---|
| 找不到 Agent | 启用的 roster、安装就绪情况和当前 session |
| 无法创建或恢复实例 | 后端是否有状态,Agent 是否启用 |
| 忙碌时直聊被拒绝 | 等待该实例;中途修正需使用支持 steer 的客户端 |
| 主 Agent 没有使用追问结果 | 发送新宿主轮次,并要求检查交接记录 |
| 重启后能看历史但没有运行活动 | 记录恢复不等于自动恢复执行 |
| 返回正常但结果错误 | 重试前核对文件、证据和 DAG verdict |
停止或重试前检查副作用。取消会话不证明远程进程或 campaign 已停止; 定时长任务应按Oncall 生命周期处理。