多Agent协作实战:如何用Cayu SubagentTool与Fork构建可委派的团队式工作流

原创2026-11-03 17:49:531,862 阅读

多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 模块,只需三步:

  1. 声明子 Agent:用 SubagentSpec 指定名字、职责描述、执行模式和结果长度上限;
  2. 注册工具:把 SubagentTool 挂到主 Agent 的 tools 上;
  3. 注册对应 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。

实战建议

  1. 一个子 Agent 只做一件事:description 写清职责边界,主 Agent 才不会"派错活";
  2. 限制结果长度:result_max_chars 是成本护栏,先给 4000 字符,不够再加;
  3. 并行优于串行:多个独立评审任务尽量用 BACKGROUND 模式同批发出,再用 all=True 汇总;
  4. 长任务上 DURABLE:配合 TaskStore,进程崩溃后子 Agent 任务可恢复,不丢进度;
  5. Fork 默认最小授权:host_tools 和 allow_model_runs 都保持默认关闭,按需逐项放开。

小结

Cayu 的多 Agent 协作不是拼凑的"多个独立 Agent",而是一套有预算、有鉴权、可恢复的委派体系:

从"一个全能 Agent"走向"一个会分活的团队",就是 Cayu 长程 Agent 框架的核心价值。

登录后查看全文
cayu