数据截至 2026-08-18(上游 commit 375d8081c48c)

Swarms — 架构与原理

30 秒导读: Swarms 是一个 Python 多智能体(multi-agent)编排框架。它先把“一个能调模型、能用工具、能循环思考的 AI”封装成一个 Agent 类,再提供约 60 种把多个 Agent 拼起来协作的“拓扑”(顺序、并行、总监分工、投票、辩论……)。你选一种拓扑、丢进几个 Agent、给一个任务,它就替你把多智能体协作跑完。

1. 这是什么(零基础也能懂)

一句话定义: Swarms 是一个把“单个 AI 智能体”和“多个智能体如何协作”都做成现成积木的编排框架。

它解决什么问题。 单个大模型(LLM)一次只回一段话:它没有“手脚”(不能自己调工具)、没有“长期记忆”(重启就忘)、也不会“分工合作”。真实任务往往需要多步、多角色:先研究、再写作、再审校。Swarms 把这些补齐——让一个 Agent 能循环、能调工具、能记忆,再让多个 Agent 按你指定的方式协作。

给谁用。 想用 Python 搭“AI 工作流 / 多智能体系统”的工程师。典型场景:

• 研究 → 写作 → 审校 的内容流水线
• 多个专家模型并行分析同一问题,再由一个聚合器综合
• 一个“总监”把大任务拆成小任务、分给若干“工人”执行

用起来什么样。 最小的两智能体流水线(研究员的输出喂给写手):

from swarms import Agent, SequentialWorkflow

researcher = Agent(
    agent_name="Researcher",
    system_prompt="研究给定主题并给出详细摘要。",
    model_name="gpt-4o-mini",  # 任意 LiteLLM 支持的模型串
)
writer = Agent(
    agent_name="Writer",
    system_prompt="把研究摘要写成一篇好读的博客。",
    model_name="gpt-4o-mini",
)

# 顺序流水线:researcher 先跑,输出作为上下文传给 writer
workflow = SequentialWorkflow(agents=[researcher, writer])
print(workflow.run("人工智能的历史与未来"))

上面的 model_name 用的是示意值。Swarms 底层通过 LiteLLM(一个统一各家模型 API 的库)调用模型,所以模型串就是 LiteLLM 那套(gpt-4o、claude-3-5-sonnet、groq/llama-3.3-70b 等)。仓库源码里 Agent 的默认 model_name 是一个占位字符串,真正跑之前你几乎总要显式指定。

一句话直觉/类比。 把 Agent 当成一名“员工”:有岗位描述(system_prompt)、有技能(tools)、有记事本(memory)、会自己琢磨几轮(max_loops)。把各种 Swarm 当成“组织结构”:流水线、并行小组、总监制、评审委员会。Swarms 卖的就是这套“员工 + 组织结构”的现成模板。

2. 顶层全景(它大概怎么转)

Swarms 的架构是清晰的两层:底层一个 Agent 原子,上层是它的各种“编排壳”。所有多智能体结构本质上都在做同一件事——决定“哪几个 Agent、按什么先后、看谁的输出”,而每个 Agent 内部各自跑自己的思考循环。

            你的代码: swarm.run("任务")
                     │
     ┌───────────────┴────────────────────────────┐
     │      上层:编排壳 (structs/*.py)            │
     │   顺序 / 并行 / 总监制 / 投票 / 辩论 ...     │
     │   统一入口: SwarmRouter (一个参数切拓扑)     │
     └───────────────┬────────────────────────────┘
                     │ 反复调用每个 Agent.run()
                     ▼
     ┌────────────────────────────────────────────┐
     │      底层:Agent 原子 (structs/agent.py)     │
     │   主循环:调模型→解析→执行工具→写记忆→重复  │
     └───────────────┬────────────────────────────┘
                     │
         ┌───────────┼───────────┬──────────────┐
         ▼           ▼           ▼              ▼
     LiteLLM     工具执行     Conversation    MCP / 记忆
    (调各家模型) (跑函数)    (对话+MEMORY.md) (外部工具)

部件一句话职责:

部件	干什么	在哪个文件
Agent	单个智能体:主循环、工具、记忆、自主模式	swarms/structs/agent.py
Conversation	对话历史 = 多智能体之间传递上下文的“黑板”;可落盘为 MEMORY.md	swarms/structs/conversation.py
AgentRearrange	流程编排引擎:解析 a -> b, c 流程串,决定顺序/并发	swarms/structs/agent_rearrange.py
run_agents_concurrently	并发原语:用线程池同时跑多个 Agent	swarms/structs/multi_agent_exec.py
SequentialWorkflow / ConcurrentWorkflow	顺序/并行拓扑(其实是引擎的薄封装)	swarms/structs/sequential_workflow.py、concurrent_workflow.py
HierarchicalSwarm	总监制:一个 director 拆任务、派单给工人	swarms/structs/hiearchical_swarm.py
MixtureOfAgents	多专家并行 + 一个聚合器综合	swarms/structs/mixture_of_agents.py
SwarmRouter	统一入口:一个 swarm_type 参数在所有拓扑间切换	swarms/structs/swarm_router.py
LiteLLM(封装)	统一调用各家模型 API	swarms/utils/litellm_wrapper.py

主线走一遍(以 SequentialWorkflow 为例,不进代码):

1. 你 SequentialWorkflow(agents=[researcher, writer]).run(task)。
2. 它内部把 agents 变成一条流程串 researcher -> writer,交给 AgentRearrange(见 sequential_workflow.py:152、sequential_workflow.py:256)。
3. 引擎把任务写进共享 Conversation(黑板),按 -> 依次让每个 Agent 跑。
4. researcher.run() 读黑板 → 调模型 → 把回答写回黑板;writer.run() 再读黑板(此时已含研究员输出)→ 写作 → 写回黑板。
5. 引擎按 output_type 把黑板格式化成最终结果返回。

关键心智模型:上层拓扑只是“调度谁、看什么”,真正的智能全在 Agent 的主循环里。 想读懂 Swarms,先读懂一个 Agent 怎么跑(第 1 章),再看编排引擎怎么把多个 Agent 串起来(第 2 章),最后看各种高层拓扑的花样(第 3 章)。

阅读地图

建议顺序:

1. 01-agent.md — 先吃透原子。一次 agent.run() 的主循环、记忆与 MEMORY.md、工具调用、以及最有意思的 max_loops="auto" 自主模式(plan→execute→summary)。
2. 02-orchestration-engine.md — 编排引擎。AgentRearrange 的流程 DSL 怎么解析、Conversation 黑板怎么当传话筒、线程池并发原语,以及为什么 SequentialWorkflow/ConcurrentWorkflow 只是它的薄壳。
3. 03-swarm-patterns.md — 高层拓扑。总监制、专家混合、自选发言的群聊、投票,以及 SwarmRouter 这个“一个参数切换所有拓扑”的统一入口。
4. 04-deep-dive.md — 巧妙之处、边界与局限(含几个源码里的“坑”)、与兄弟框架的横向对比、以及可 grep 的代码地图。