Swarm

python multi MIT repo ↗ agents-example/swarm/
7/12 组件

Swarm

一句话定位
OpenAI 出品的教学型极简多智能体编排库（核心仅约 300 行）：用”函数即工具 + 返回 Agent 即移交（handoff）“两个原语，演示轻量、人体工学的多 agent 协作。无状态、不为生产设计。

设计理念 / 顶层架构

Swarm 刻意做到最小，只为讲清两个概念：**Agent（轻量角色）**与 handoff（控制权移交）。整个库就 4 个文件（agents-example/swarm/swarm/）：core.py（循环）、types.py（数据模型）、util.py（函数转 schema）、__init__.py。

  • Swarm 类仅包一个 OpenAI client（core.py:26），无额外状态——无状态设计：history 由调用方传入、随 Response 传出。
  • Agent 是 pydantic 模型（types.py:14）：name / model / instructions(可为函数) / functions / tool_choice / parallel_tool_calls。
  • 核心循环 Swarm.run()（core.py:231）：取补全 → 若无 tool_calls 则结束 → 执行工具 → 若某工具返回了 Agent，则切换 active_agent（core.py:285）。

最小示例：

from swarm import Swarm, Agent
client = Swarm()

def transfer_to_spanish():            # 工具返回一个 Agent = 移交
    return spanish_agent

english = Agent(name="English", instructions="Only English.", functions=[transfer_to_spanish])
spanish = Agent(name="Spanish", instructions="Solo español.")

resp = client.run(agent=english, messages=[{"role":"user","content":"Hola"}])
print(resp.messages[-1]["content"])   # 自动 handoff 到 spanish_agent

组件实现（横向逐项）

组件实现方式关键抽象 / 文件
推理循环/范式ReAct 式工具循环；while 直到无 tool_call 或 max_turnscore.py:257
规划/任务分解N/A，无显式规划—
记忆N/A，无记忆；history 调用方自管（无状态）core.py:253
工具调用普通 Python 函数 → function_to_json 自动转 OpenAI tool schema；原生 function callingutil.py:function_to_json, core.py:50
模型抽象仅 OpenAI，硬编码 OpenAI() client，无抽象层core.py:8,29
多智能体编排网状 handoff：工具返回 Agent/Result(agent=...) 即移交控制权core.py:76,134,285
上下文工程system=instructions + history；context_variables 注入函数且对模型隐藏core.py:42,51,120
技能/插件N/A—
可观测/评估仅 debug_printutil.py:debug_print
运行时/部署纯库，同步；工具在本进程直接执行（无沙箱）core.py:122
人在环/治理N/A—
状态/持久化N/A，无持久化；Response 含 messages+agent+context_variables 供下次传入types.py:23

设计权衡与特性

  • 极简优雅：handoff 抽象（工具返回 agent）是全库最大亮点，被后来许多框架借鉴。
  • 无状态：可控、易测，但记忆/编排/持久化全交给使用者。
  • 教学定位：官方明确不维护、不为生产；要生产用 AG2 / AutoGen。
  • 与 CrewAI（角色+流程）、AutoGen（群聊）相比，Swarm 是”去框架化”的极小内核。

关联