跳到主要内容

数据截至 (上游 commit 375d8081c48c)

Swarms — 深入

本章面向要真正读源码 / 做技术选型的人:提炼可借鉴的设计、诚实列出边界与坑、和兄弟框架对比,并给一张可 grep 的代码地图。

1. 巧妙之处(可借鉴的技术)​

① 共享对话即接口。 多智能体间不靠显式的“返回值 → 入参”链传数据,而是共读共写一份 Conversation 黑板。好处:任意拓扑(顺序、并发、总监)都用同一种上下文传递方式,新拓扑几乎零成本复用。见 AgentRearrange._run 里对 self.conversation 的读写(structs/agent_rearrange.py:711、660-670)。

② 强制结构化工具调用来做“控制流”。 凡是需要“机器读懂 Agent 意图”的地方,都用 forced function call 而非解析自然语言:GroupChat 用 RESPOND_TOOL 让 Agent 用 (score, message) 竞价发言(structs/groupchat.py:74-98);HierarchicalSwarm 用 SwarmSpec 让总监吐出结构化 orders(structs/hiearchical_swarm.py:85-111);自主模式用 create_plan/subtask_done 等工具驱动状态机(structs/agent.py:2280-2319)。这把“不可靠的自然语言”转成“可校验的 JSON”,是全框架反复出现的模式。

③ 一切收敛到 Agent.run。 无论多复杂的 Swarm,叶子节点永远是 agent.run(task=...)。这让 Agent 成为唯一需要吃透的执行单元,也让“单智能体”和“多智能体”共用同一套重试/记忆/工具逻辑。

④ 顺序感知用临时 system_prompt 注入、跑完还原。 既让 Agent 知道自己在流程中的位置,又不把这些私有信息污染进共享黑板(try/finally 还原,structs/agent_rearrange.py:630-668)。

⑤ 编排层薄封装。 SequentialWorkflow 不重复造轮子,直接转包给 AgentRearrange(structs/sequential_workflow.py:152、256)——用组合而非继承扩展能力。

2. 边界与局限(诚实清单)​

这些是从源码读到的真实约束,不是评判。

  • Agent 是一个巨型类。 structs/agent.py 超过 6400 行、100+ 方法,构造函数有 80+ 个参数(structs/agent.py:331-419)。功能极全,但认知负担重、行为面广。
  • context_length 参数不生效。 构造函数在 structs/agent.py:514 无条件 self.context_length = 16000,覆盖你传入的值。想控制上下文预算的人会被这行“坑”。
  • 同名 Agent 共享持久记忆。 MEMORY.md 仅按 agent_name 落盘(structs/agent.py:1043-1045),多个 Agent 起同名 → 互相读写同一份记忆,可能污染。多智能体场景要么给唯一名字,要么 persistent_memory=False。
  • 并发结果顺序 = 完成顺序。 run_agents_concurrently 默认用 as_completed 收集(structs/multi_agent_exec.py:180),返回列表顺序和输入顺序不一致;要对齐得用 return_agent_output_dict=True。
  • 线程池并发受 API 侧限制。 默认吃满 ~95% CPU 核开线程(structs/multi_agent_exec.py:142-144),但真正瓶颈通常是模型服务商的速率限制;线程开太多可能撞 429。
  • 可变默认参数。 tools_list_dictionary=[] 作默认值(structs/agent.py:388)是 Python 经典陷阱写法;阅读/子类化时要小心跨实例共享。
  • 命名遗留。 文件名 hiearchical_swarm.py(hierarchical 拼写错)等历史命名保留在源码里,import 时按真实文件名来。

3. 横向对比(同 shelf 兄弟)​

Swarms 在 ai-agent-reference 这层属于“多智能体编排框架”。它的取舍相对同类:

维度Swarms取舍解读
定位拓扑“大杂烩”:约 60 种现成结构 + 统一 SwarmRouter广度优先——想要哪种协作模式基本都有现成的
抽象核心一个巨型 Agent + 共享 Conversation 黑板概念少、易上手;但单类过重
编排表达字符串流程 DSL(a -> b, c)+ 工厂表轻量、可读;复杂依赖仍需 GraphWorkflow 的 DAG
模型接入统一走 LiteLLM,模型只是一个字符串换厂商零改代码,便于多模型混合(MoA)
状态/协作隐式共享对话历史简单直观;但没有强类型的消息契约

与“图/DAG 优先”的框架相比,Swarms 用一行流程串覆盖了大多数顺序+并行需求,只有真需要复杂依赖时才上 GraphWorkflow(DAG,structs/graph_workflow.py)。与“把编排逻辑交给模型自己规划”的思路相比,Swarms 两条路都留:显式拓扑(你定结构)和 max_loops="auto" / swarm_type="auto"(让模型定)。

具体到本 shelf 的其他子库对比,请对照总库 doc 中“多智能体编排”一节的对比表。

4. 代码地图(导航索引)​

用符号名 grep,比行号抗漂移。

主题文件路径符号名
Agent 构造与全部参数swarms/structs/agent.pyAgent.__init__
固定轮数主循环swarms/structs/agent.pyAgent._run
入口与 auto 分流swarms/structs/agent.pyAgent.run
自主模式(plan→execute→summary)swarms/structs/agent.pyAgent._run_autonomous_loop
自主模式工具处理器表swarms/structs/agent.py_run_autonomous_loop(all_planning_tool_handlers)
记忆初始化 / MEMORY.md 路径swarms/structs/agent.pyAgent.short_memory_init
LLM 配置组装swarms/structs/agent.pyAgent.llm_handling
工具 → schemaswarms/structs/agent.pyAgent.tool_handling
工具执行swarms/structs/agent.pyAgent.execute_tools
工具执行器(跨厂商)swarms/tools/base_tool.pyBaseTool.execute_function_calls_from_api_response
上下文压缩swarms/structs/agent.pyContextCompressor(self._context_compressor)
流程 DSL 解析与执行swarms/structs/agent_rearrange.pyAgentRearrange._run
顺序执行 + 顺序感知swarms/structs/agent_rearrange.pyAgentRearrange._run_sequential_workflow
并发原语(线程池)swarms/structs/multi_agent_exec.pyrun_agents_concurrently
顺序工作流(薄封装)swarms/structs/sequential_workflow.pySequentialWorkflow(self.agent_rearrange)
对话黑板 / 持久化swarms/structs/conversation.pyConversation(compact、_append_to_memory_md)
总监制:计划数据结构swarms/structs/hiearchical_swarm.pySwarmSpec、HierarchicalOrder
总监制:一步与多轮swarms/structs/hiearchical_swarm.pyHierarchicalSwarm.step、HierarchicalSwarm.run
专家混合swarms/structs/mixture_of_agents.pyMixtureOfAgents._run
群聊竞价发言swarms/structs/groupchat.pyRESPOND_TOOL、GroupChat
统一入口工厂表swarms/structs/swarm_router.pySwarmRouter._initialize_swarm_factory、_create_swarm
支持的拓扑类型swarms/structs/swarm_router.pySwarmType