多Agent协作实战:如何用Cayu SubagentTool与Fork构建可委派的团队式工作流
多Agent协作实战:如何用Cayu SubagentTool与Fork构建可委派的团队式工作流
Cayu 是一个开源 Python 框架,专为构建和运行"长程(long-horizon)"领域 Agent 而设计,内置持久化运行时(durable runtime)。在多 Agent 协作场景中,Cayu 提供了两大核心能力:SubagentTool 让主 Agent 把子任务委派给专职子 Agent,Fork(会话分叉)则让外部系统安全地接管并复用已有会话。本文将带你快速上手这两种委派方式,搭建一个真正可协作的"团队式"工作流。
为什么需要多Agent协作
单 Agent 应用常见的痛点:
- 上下文膨胀:审查、检索、生成混在一个会话里,token 成本飙升;
- 职责不清:模型既要写代码又要评审,质量难以保证;
- 无法并行:安全评审和产品评审只能串行排队。
Cayu 的思路是把"委派"做成一等公民:主 Agent 像团队负责人,子 Agent 像各有专长的同事。
SubagentTool:三步定义你的"子Agent团队"
SubagentTool 位于 cayu.tools 模块,只需三步:
- 声明子 Agent:用
SubagentSpec指定名字、职责描述、执行模式和结果长度上限; - 注册工具:把
SubagentTool挂到主 Agent 的 tools 上; - 注册对应 Agent:为每个子 Agent 编写独立的系统提示词。
最小示例(参考 subagent_live.py):
from cayu.tools import SubagentExecutionMode, SubagentSpec, SubagentTool
subagents = SubagentTool(
app,
agents={
"reviewer": SubagentSpec(
agent_name="reviewer",
description="Review short implementation plans and return concrete risks.",
mode=mode,
result_max_chars=4_000,
)
},
)
主 Agent 在对话中只需一句 agent='reviewer',就能把"评审计划"这件子任务交出去。
三种执行模式:前台、后台、持久化
SubagentExecutionMode 提供三种委派节奏,按任务特性选择:
| 模式 | 行为 | 适用场景 |
|---|---|---|
FOREGROUND |
阻塞等待子 Agent 完成 | 结果必须立刻用上 |
BACKGROUND |
立即返回 child_session_id,后台继续跑 |
并行评审、边跑边做别的事 |
DURABLE |
持久化到 TaskStore,进程重启不丢 | 长任务、需要跨进程恢复 |
💡 DURABLE 模式需要挂载
InMemoryTaskStore+TaskStoreDispatcher(或 SQLite 持久存储),配置方式同样在 subagent_live.py 中给出。
并行协作:一次派活,多个子Agent同时开工
这是最能体现"团队感"的用法。在 subagent_parallel_live.py 中,主 Agent 在同一步骤里连续调用两次 SubagentTool:
security_reviewer:专职安全与滥用风险;product_reviewer:专职产品与用户体验风险。
两个后台子 Agent 并行运行,主 Agent 期间可以继续起草内容,最后通过 SubagentResultTool 一次性汇总。相比串行评审,墙钟时间几乎减半。
SubagentResultTool:拿回委派结果
后台/持久化模式下,SubagentTool 只返回 child_session_id。要取结果,再注册一个 SubagentResultTool:
- 传入
child_session_id:拉取单个子 Agent 的结果; all=True, wait=True:等待所有子 Agent 并合并返回(见 subagent_parallel_live.py 的用法)。
result_max_chars 参数控制结果截断长度,防止子 Agent 的长篇大论撑爆主会话上下文——这是控制多 Agent 成本的关键旋钮。
Fork:让外部系统"分叉"接管一个会话
SubagentTool 解决的是"Agent 内部委派",而 Fork 解决的是"跨系统委派":外部控制器(如监督进程、另一套业务系统)可以把宿主的一个会话分叉出去,注入自己的指令、自己的工具、自己的记忆上下文,宿主应用无需内置任何控制器代码。
核心概念来自 docs/fork-overlays.md:
| Overlay 部件 | 作用 |
|---|---|
instructions |
分叉后模型在原始历史之后看到的附加指令 |
memory |
仅该分叉可见的记忆项 |
tools |
控制器可提供的工具授权 |
注册一个控制器只需一次 enroll_fork_controller:
from cayu.fork_controllers import ForkController
from cayu.budgets import BudgetLimit, BudgetReservation
app.enroll_fork_controller(
ForkController(
name="compass",
subjects=("svc:compass",),
agents=("finance-monthend",),
host_tools=("lookup_ledger",),
allow_model_runs=True,
fork_budget_limit=BudgetLimit.usd(
2,
reservation=BudgetReservation(max_input_tokens=200_000, max_output_tokens=16_000),
),
)
)
安全设计值得注意:
- 每个分叉都有独立的预算上限(
fork_budget_limit),控制器无法突破; allow_model_runs默认关闭——控制器可以创建分叉,但不被允许烧钱跑模型;- 通过 bearer token 的 SHA-256 摘要鉴权,宿主进程永远拿不到明文 token(详见 docs/fork-overlays.md 的 "Enrolling from the environment" 一节,支持纯环境变量注册)。
选型指南:SubagentTool 还是 Fork?
| 维度 | SubagentTool | Fork Overlay |
|---|---|---|
| 委派发起方 | 主 Agent 自己在对话中调用 | 外部系统(控制器进程) |
| 上下文 | 子 Agent 独立会话 | 复制源会话历史 + 注入 overlay |
| 工具来源 | 子 Agent 注册的工具 | 宿主工具白名单 + 控制器 MCP 工具集 |
| 预算控制 | 结果长度截断 | 每分叉美元级预算上限 |
| 典型场景 | 并行评审、检索、起草 | 监督系统接管、跨服务复用会话 |
简单判断:委派发生在会话内部 → SubagentTool;委派来自会话外部 → Fork。
实战建议
- 一个子 Agent 只做一件事:
description写清职责边界,主 Agent 才不会"派错活"; - 限制结果长度:
result_max_chars是成本护栏,先给 4000 字符,不够再加; - 并行优于串行:多个独立评审任务尽量用 BACKGROUND 模式同批发出,再用
all=True汇总; - 长任务上 DURABLE:配合 TaskStore,进程崩溃后子 Agent 任务可恢复,不丢进度;
- Fork 默认最小授权:
host_tools和allow_model_runs都保持默认关闭,按需逐项放开。
小结
Cayu 的多 Agent 协作不是拼凑的"多个独立 Agent",而是一套有预算、有鉴权、可恢复的委派体系:
- SubagentTool:会话内的前台/后台/持久化三级委派;
- 并行子Agent:一次派活,多线开工;
- Fork Overlay:跨系统的安全会话分叉。
从"一个全能 Agent"走向"一个会分活的团队",就是 Cayu 长程 Agent 框架的核心价值。