交接与例行程序——无状态编排

交接与例行程序——无状态编排

本节摘要:OpenAI 的 Swarm(2024/10)把多智能体编排蒸馏成两个原语:例行程序(Routine)= 指令 + 工具作为系统提示;交接(Handoff)= 一个返回另一个 Agent 的工具。没有状态机、没有分支 DSL——LLM 通过调用正确的交接工具来路由。OpenAI Agents SDK(2025/03)是它的生产继任者,加了会话管理、护栏、追踪,同时保留交接原语。Swarm 本身仍是最干净的概念参考——全部源码几百行。这套模式之所以病毒式传播,因为 API 面大概就是「agent = 提示 + 工具;handoff = 返回 agent 的函数」。局限:无状态,所以记忆是调用者的问题。本节用标准库从零实现 Swarm,讲透交接如何用工具调用实现控制转移,以及它何时胜过又何时败给 GroupChat。

学习目标

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

1. 说清 Swarm 的两个原语(例行程序、交接)及其极简 API 面。
2. 用标准库从零实现交接机制(工具返回 Agent,运行时检测切换)。
3. 解释无状态权衡(记忆是调用者的事)与 Agents SDK 如何在生产补上会话/护栏/追踪。
4. 区分 Swarm 与 GroupChat 在「谁选下一个」上的根本不同。
5. 应用工程护栏:交接日志、上下文转移规则、交接护栏、循环检测、回退 Agent。

一、问题与直觉

每个多智能体框架都要你学它的 DSL:LangGraph 的节点与边、CrewAI 的 crew 与 task、AutoGen 的 GroupChat 与 manager。这些 DSL 是真抽象,但让事情显得比必要的更重。

Swarm 反向推进:用模型已有的工具调用能力。交接变成工具调用;编排者就是当前持有会话的那个 Agent;状态机隐式地活在 Agent 的系统提示里。

两个原语

例行程序:定义 Agent 角色与可用工具的系统提示。可看作一组作用域指令:「你是分诊 Agent;用户问退款就交给退款 Agent。」

交接:Agent 可调用的、返回一个新 Agent 对象的工具。Swarm 运行时检测到 Agent 返回值,就把下一轮的活跃 Agent 切换过去。

这就是全部抽象。

def transfer_to_refunds():
    return refund_agent   # Swarm 见 Agent 返回 → 切换活跃 Agent

triage_agent = Agent(
    name="triage",
    instructions="把用户路由到对的专家。",
    functions=[transfer_to_refunds, transfer_to_sales, transfer_to_support],
)
​

分诊 Agent 的系统提示让它按用户消息选对交接。LLM 的工具调用完成路由。

为什么病毒式传播

• API 小:只两个概念要学。
• 用模型已有的:工具调用在各厂商都已是生产级。
• 无状态机负担:你不描述图;Agent 的提示描述了它们交接给谁。

无状态权衡

Swarm 在运行间明确无状态。框架在一次运行内保留消息历史,但不持久化任何东西。记忆、连续性、长时任务——全是调用者的问题。

生产中(OpenAI Agents SDK,2025/03)这是主要变化之一:SDK 加了内置会话管理、护栏、追踪,同时保留交接原语。

何时适合

• 分诊模式:前线 Agent 把用户路由到专家。
• 技能型交接:「任务需要代码就调程序员,需要研究就调研究员。」
• 短而有界的会话:客服、FAQ 转工单、简单工作流。

何时挣扎

• 需共享记忆的长会话:交接把会话状态重置为新 Agent 提示 + 历史;无调用者管理的记忆,则跨 Agent 无持久状态。
• 并行执行:交接是一次一个——活跃 Agent 切换;并行需要调用者编排多个 Swarm 运行。
• 审计与重放:无状态运行难精确重放;LLM 的交接选择不确定。

⚠️ 无状态是 Swarm 的设计核心,也是它最大的局限:它把协调简化到了极致(工具调用即路由),代价是把状态管理的活全甩给调用者。 这正是「协调难点」的另一种切法——要么你管状态(LangGraph),要么调用者管状态(Swarm)。

OpenAI Agents SDK(2025/03)

生产继任者加:会话状态(跨运行持久线程)、护栏(输入/输出校验钩子)、追踪(每次工具调用与交接都记日志)、交接过滤器(控制交接时转移什么上下文)。交接原语存活;生产工效在其之上添加。

Swarm vs GroupChat

两者都用 LLM 驱动路由,但在谁选下一个上不同:

• GroupChat:一个选择器(函数或 LLM)从外部选下一个发言者。
• Swarm:当前 Agent 通过调用交接工具选自己的继任。

Swarm 是「Agent 决定下一个」;GroupChat 是「manager 决定下一个」。Swarm 的决策活在活跃 Agent 的工具调用里;GroupChat 的活在 GroupChatManager 里。

二、从零实现

code/main.py 从零实现 Swarm:Agent 数据类、交接机制(工具返回 Agent)、检测 Agent 切换的运行循环。

骨架

class Agent:
    def __init__(self, name, instructions, functions=None):
        self.name = name; self.instructions = instructions
        self.functions = functions or []

def run_swarm(active_agent, user_message, history):
    history.append({"role": "user", "content": user_message})
    while True:
        # LLM 决定调用哪个工具(这里脚本化)
        tool_call = active_agent.decide_tool(history)
        result = tool_call()
        if isinstance(result, Agent):            # 交接!
            active_agent = result
            continue
        history.append({"role": "assistant", "content": result})
        return result, active_agent
​

演示:分诊路由

triage = Agent("triage", "路由用户到专家。",
               functions=[transfer_to_refunds, transfer_to_sales, transfer_to_support])
refund = Agent("refund", "处理退款。", functions=[process_refund])
# 用户说「我要退款」→ triage 调 transfer_to_refunds → 返回 refund_agent
# 运行循环检测 Agent 返回 → 切换活跃 Agent → refund 接管
​

设计要点:运行循环里那个 isinstance(result, Agent) 检查是 Swarm 的全部魔法——它把「控制转移」变成「工具返回值的类型判断」。这种极简是它易于理解也易于被提示注入攻击的根源(练习 4 会探讨)。

三、框架对比

💡 心法:Swarm 的交接是「内聚路由」(谁拿着话谁决定下一个),GroupChat 是「外聚路由」(外部 manager 决定)。 同样是 LLM 驱动,决策位置不同决定了可调试性与攻击面不同。

四、可复用产物

outputs/skill-handoff-designer.md:为给定任务设计交接拓扑——存在哪些 Agent、各自能调哪些交接、什么上下文随交接转移。

五、练习

1. 跑通:跑 code/main.py,分诊到退款 Agent。确认第二轮活跃 Agent 是 refund。
2. 循环检测:加规则——若同样两个 Agent 连续交接 3 次,强制退出。设计回退。
3. 交接时总结:读 Agents SDK 的交接过滤器文档,实现「交接时总结」版——离场 Agent 把上下文压成要点再交接。
4. 注入对比:对比 Swarm 交接与 GroupChatManager 选择器。哪种模式让提示注入更糟,为什么?
5. 读 cookbook:读 Swarm cookbook,识别 Swarm 的一个明确设计决策被 Agents SDK 改了或保留了。

本节要点回顾

1. Swarm 两个原语:例行程序(系统提示 + 工具)、交接(返回 Agent 的工具,运行时检测切换)。
2. 病毒式传播三因:API 小、用模型已有工具调用、无状态机负担。
3. 无状态是核心也是局限:运行间不持久化,记忆/连续性/长时任务全甩调用者。
4. Agents SDK 生产化:加会话状态、护栏、追踪、交接过滤器,交接原语存活。
5. 何时适合:分诊模式、技能型交接、短而有界会话。
6. 何时挣扎:需共享记忆的长会话、并行执行、审计与重放。
7. Swarm vs GroupChat:前者内聚路由(当前 Agent 决定),后者外聚路由(manager 决定)。
8. 工程护栏:交接日志(from/to/上下文快照)、上下文转移规则(全量/近 N/摘要)、交接护栏(防注入强制交接)、循环检测(最近 K 次环检查)、回退 Agent。

下一节,我们深入第 03 节提到的 A2A 协议,把它当作一个完整的工程规范来讲——Agent Card、任务生命周期、流式、协商,以及它在跨组织协作中的落地。