构建一个编排模式

MessagesContext 管理

构建一个会话级模式:它为多代理 fan-out(扇出)授予常驻许可,并可通过对话中途的 system 消息随时开启或关闭。

编排模式是一个会话级开关:开启时,模型会以最大的彻底程度处理每一个实质性请求——先自行侦察任务,然后默认把工作扇出给并行的子代理;关闭时,同一个编排工具会退回到每次请求单独选择启用(per-request opt-in)。

这个模式不是一个 API 参数。它完全由文档中已有的部件搭建而成:

  1. 一个 effort 级别: 请求以文档中记录的 Effort 值运行,例如 xhigh。该页面所列级别之上没有任何隐藏级别。
  2. 一条模式提醒: 一条对话中途的 system 消息告诉模型该模式处于激活状态,每隔几轮发送一行简短的刷新提醒,并在模式关闭时发送一条退出通知。顶层的 system 字段从不改变,因此被缓存的前缀始终保持完好。
  3. 工具描述中的常驻许可: 编排工具的描述声明:当该模式开启时,模型应当为每一个实质性任务直接撰写并运行一个 workflow,无需事先询问。

本示例使用对话中途的 system 消息,该能力目前仅在 Claude Opus 4.8 上可用。fan-out 本身会成倍放大 token 用量:单个请求可能派生出许多子代理对话,因此请把这个模式留给那些值得为此付出成本的工作。

搭建循环

示例是单个文件。其中的常量控制 effort 级别、fan-out 的宽度,以及模式刷新提醒的重新发送频率。

定义模式提醒

这些提醒刻意保持简短。它们负责翻转模式,并指向工具描述——那些重量级的指令都放在那里。完整文本在模式开启时发送一次,刷新提醒仅在经过若干个用户轮次之后才重新发送,退出通知则在模式关闭时发送一次。

在工具描述中授予常驻许可

Workflow 工具承载着真正的行为契约:opt-in 规则、模式开启期间生效的常驻许可,以及模型可以动用的质量模式(一轮验证、一个完整性评审者、多阶段编排)。子代理还会获得一个 report_findings 工具,使其结果以结构化的 JSON 而非散文形式返回;而 bash 工具则是由 Anthropic 定义、在本地执行的 bash_20250124 工具。

在本地执行 bash 工具

bash 处理程序会以超时限制运行所请求的命令,捕获合并后的 stdout 与 stderr,并对结果进行截断,使失控的命令无法淹没上下文窗口。这里没有沙箱:命令以启动该示例的那个进程的权限运行。为清晰起见,本示例在一个全新的子 shell 中运行每一次调用,而不是维护 bash_20250124 契约所描述的持久会话;生产环境的代理应当用一个长期存活的 shell 来支撑该工具,从而让工作目录、环境变量以及 restart 动作的行为与文档保持一致。

把子任务作为并行子代理运行

每个 workflow 子任务都会变成它自己的小型代理循环,配备 bash 工具,并以与主循环相同的 effort 运行。fan-out 会限制并行代理的数量并隔离故障,使得一个出错的子代理只会退化成一个错误字符串,而不会终止整个运行。

用对话中途的 system 消息切换模式

代理会先追加用户的消息,然后再追加任何到期的 system 消息:退出通知、进入模式时的完整模式文本,或周期性的刷新提醒。把 system 消息放在用户轮次之后,可以让它之前每一个被缓存的字节都保持不变,同时也满足“system 消息须紧随某个用户轮次之后”这一放置规则。

运行它

本示例中的 bash 工具会在你的机器上直接运行由模型编写的命令,没有沙箱,而 fan-out 会并行运行其中若干个这样的代理。请在一个你愿意暴露的目录和环境中运行它,并在将它改造用于本地实验之外的任何用途之前,先加上沙箱。

模式开启时,可以预期模型会用几条 bash 命令进行侦察,在没有提示的情况下主动派发 Workflow 工具,并把子代理们的报告综合成最终答案。正如提醒所指示的,琐碎或纯对话式的请求仍保持单代理处理。