第 3 章 · 03 handoffs 任务交接机制

第 3 章 · 03 handoffs 任务交接机制

本节摘要:本节讲透 AutoHedge 多 Agent 编排的「灵魂」——handoffs(任务交接)。Director 之所以能调度四大专家,靠的就是 handoffs=ALL_AGENTS 这一个参数。本节先从代码层面看 handoffs 在 workers.py 里如何声明(一行参数),再讲清它的语义:一个 Agent 把当前任务连同上下文整体交给另一个 Agent,后者接过控制权独立完成;这与「工具调用」有本质区别——工具是「Agent 调一个函数拿结果」,handoff 是「Agent 把活儿整个转给另一个 Agent」。本节还会说清 Director 如何决定交接(全靠 LLM 理解 system_prompt,无显式规则)、交接后的控制流(被交方产出回交、Director 综合),以及这种隐式交接在交易场景的风险。读完本节,你真正理解「多 Agent 协作」在代码里是怎么发生的。

内容来源:原项目源码 autohedge/workers.py、autohedge/prompts.py,结合 swarms 框架的 handoffs 语义,精读并套用体系化模板。

⚠️ 现实澄清:handoffs 的具体调度实现在 swarms 框架内部(本仓库看不到源码),这里讲的是基于参数与 prompt 的可观测行为与语义模型,不深究 swarms 的内部实现细节。

学习目标

阅读完本节,你应当能够:

1. 说清 handoffs 在 workers.py 里如何声明。
2. 用一句话定义 handoff 的语义(整体转交控制权)。
3. 区分 handoff 与工具调用的本质差别。
4. 描述 Director 如何决定交接给谁(隐式 vs 显式)。
5. 指出隐式交接在交易场景的风险。

一、handoffs 在代码里如何声明

回到 workers.py 第 72-86 行,handoffs 的声明就两处:

ALL_AGENTS = [
    sentiment_agent,
    risk_agent,
    execution_agent,
    quant_agent,
]

director_agent = Agent(
    agent_name="Trading-Director",
    system_prompt=DIRECTOR_PROMPT + _SYSTEM_SUFFIX,
    model_name="gpt-4.1",
    max_loops=1,
    handoffs=ALL_AGENTS,        # ← 唯一的关键参数
)
​

关键就是 handoffs=ALL_AGENTS——把四个专家 Agent 装进一个列表,赋给 Director 的 handoffs 参数。这是 swarms Agent 构造器提供的能力:声明「我可以把任务转交给这些 Agent」。

注意几个细节:

• 只有 Director 设了 handoffs:四个专家彼此之间不能互相 handoff(它们的构造里没有 handoffs 参数)。也就是说,协作是星型的——Director 是中心,专家是叶子,专家不能直接找另一个专家。
• 顺序无关:ALL_AGENTS 列表里四个 Agent 的顺序不影响行为。swarms 把它们注册成「可交接目标」,Director 凭 agent_name 与 prompt 自由选择。
• 专家先于 Director 定义:这是 Python 模块级代码的硬约束——ALL_AGENTS 要存在,Director 才能引用它。

二、handoff 的语义:整体转交控制权

handoff 不是「调函数」,而是「换 Agent 主控」。语义上:

当 Director 决定 handoff 给某专家时,它把当前任务连同上下文整体交给该专家;该专家用自己的 system_prompt、自己的模型、自己的工具,独立完成这一子任务;完成后把产出回交给 Director,Director 决定是否再 handoff 给下一个专家或综合输出。

可以把它类比成公司里的「转交」:

总监(Director)收到一个大任务
   │ 「这块需要情绪分析,我交给情绪组」
   ▼
情绪组(Sentiment Agent)用自己的人(模型)/自己的工具(exa_search)做完
   │ 把报告交回
   ▼
总监 看了报告,「再让风控组评估一下」
   │
   ▼
风控组(Risk Agent)...
   │
   ▼
总监 综合所有报告,给最终答复
​

关键特征:专家独立工作——它用自己的 system_prompt(比如 risk_agent 那段「当收到消息时,它包含…请提供…」)、自己的模型(gpt-4.1)、自己的 max_loops(1)。Director 不能干预专家内部怎么想,只能给它输入、收它的输出。

三、handoff vs 工具调用:本质区别

这是初学者最容易混淆的点。对比:

在 AutoHedge 里,两种机制同时存在:

• 情绪 Agent 内部调工具 exa_search(LLM 决定何时搜、搜什么)。
• Director 外部 handoff 给情绪 Agent(把「做情绪分析」整件事交给它)。

💡 核心心法:工具是「Agent 的手」——延长 Agent 的能力边界;handoff 是「Agent 的同事」——把整块工作分工出去。一个 Agent 可以同时有手(工具)和同事(handoffs)。Director 有同事(四个专家)但没手(没 tools);情绪 Agent 有手(exa_search)但没同事(没 handoffs)。

四、Director 如何决定交接给谁:隐式判断

这是 AutoHedge 最值得玩味的设计——Director 怎么知道该交谁? 答案是:没有显式规则,全靠 LLM 理解 system_prompt 自由判断。

看 DIRECTOR_PROMPT(第 4 章第 1 节详讲)里的关键句:

3. Collaborate with specialized agents to ensure a cohesive strategy.
​

这句「与专家 Agent 协作」配合 handoffs=ALL_AGENTS,swarms 在背后会把「可交接的专家清单」以一种 LLM 可理解的形式(通常是工具描述或系统消息)告知 Director。Director 的 LLM(gpt-4.1)据此自主推理:

• 任务提到「市场情绪」→ 觉得该叫情绪 Agent
• 任务提到「技术指标」→ 觉得该叫量化 Agent
• ……

但这些都是LLM 的语言理解,不是硬编码规则。代码里找不到任何 if "sentiment" in task: handoff to sentiment_agent 之类的逻辑。

隐式判断的好处:

• 灵活——任务换个说法也能应付。
• 省 code——不用维护一堆规则。

隐式判断的代价:

• 不可预测:同样的任务,Director 可能这次叫情绪、下次叫量化,甚至不叫。
• 不可审计:出了错很难复盘「为什么当时交给了 X 而不是 Y」。
• 依赖 prompt 质量:system_prompt 写得模糊,Director 就会乱交。

⚠️ 现实澄清:在交易场景,这种隐式交接是重大隐患。一次错误的交接(比如该叫风控却没叫)可能让一笔危险交易漏过审查。生产级系统要么用显式规则(确定性 dispatch),要么至少给交接决策加日志与回放能力。AutoHedge 在这点上离生产很远。

五、交接后的控制流

一次典型的 handoff 控制流(基于 swarms 的语义模型):

1. director_agent.run(task="分析原油市场")
2. Director LLM 推理:"需要情绪分析" → 选择 handoff 给 sentiment_agent
3. swarms 把任务+上下文打包,调用 sentiment_agent.run(...)
4. sentiment_agent 用 gpt-4o-mini 推理,期间调 exa_search 取新闻
5. sentiment_agent 产出情绪打分,返回给 Director
6. Director 再推理:"需要风控评估" → handoff 给 risk_agent(带假设+情绪)
7. risk_agent 用 gpt-4.1 推理,产出风控评分
8. ... (可能继续 handoff) ...
9. Director 觉得够了 → 综合所有专家输出,产出最终回复
10. director_agent.run 返回最终回复给调用方(main.py)
​

注意几个要点:

• Director 的 max_loops=1:Director 单轮推理就产出。这意味着 swarms 内部在一次 run 里自行驱动了「handoff → 等专家 → 再 handoff → 综合」的多步流程,而不是靠 max_loops 迭代。这是 swarms 框架帮你做的事。
• 专家的产出回交 Director:专家不直接对外输出,它的产出进 Director 的上下文,Director 综合后才对外。
• 最终输出方是 Director:所以 main.py 里 director_agent.run(task=task) 的返回值,是 Director 综合所有 handoff 结果后的最终回答。

六、为何采用星型而非网状

注意到 AutoHedge 是星型结构(Director 中心,专家叶子),而非网状(专家之间也能互相 handoff)。这是有意的取舍:

教学项目选星型是合理的——它把多 Agent 协作简化成「一个大脑 + 多个执行者」,便于理解。生产系统往往会加「专家间有限互交」或「二级编排者」来平衡。

本节要点回顾

1. 声明:Director 用 handoffs=ALL_AGENTS 一行声明可交接给四个专家;只有 Director 设了,专家间是星型不能互交。
2. 语义:handoff 是「整体转交控制权」——被交方用自己的 prompt/模型/工具独立完成子任务,产出回交;Director 综合后对外输出。
3. vs 工具调用:工具是「Agent 的手」(延长能力),handoff 是「Agent 的同事」(分工外包);AutoHedge 里情绪 Agent 同时有手(exa_search)和被 handoff 的身份。
4. 隐式判断:Director 凭 LLM 理解 system_prompt 自由决定交谁,无显式规则;灵活但不可预测、不可审计。
5. 控制流:swarms 在一次 run 内自行驱动「handoff→专家→回交→再 handoff→综合」的多步流程;最终输出方始终是 Director。
6. 风险:交易场景的隐式交接是重大隐患——该叫风控没叫就让危险交易漏过;生产需显式 dispatch 或至少交接日志与回放。

下一节,我们退一步看 swarms 框架的 Agent 与 Conversation 抽象——这五个 Agent 的「容器」与消息历史是怎么定义的。