上个月，我在一个客户项目上撞了南墙。当时我们在搭建一个自动化的内容流水线——涵盖调研、起草、编辑、排版——我一直靠一堆乱七八糟的 Python 脚本把各个独立的 API 调用硬拼在一起。结果只要有一个环节出错，整个链条就全崩了。我经常得花好几个小时去调试，搞清楚为什么“编辑”环节收到的来自“起草”环节的输入格式是错的。代码已经变得根本没法维护了。
我需要一个框架，能让我定义不同的角色，给每个角色配备专属工具，还能让他们自己互相沟通，而不用我一条条消息去手动干预。在试了几个要么太死板、要么太抽象的框架后，我发现了 Agency Swarm。这是一个基于 OpenAI Agents SDK 构建的开源框架，它按照现实世界中的组织架构来搭建多智能体系统。这让我一下子豁然开朗——我不用再去琢磨什么“节点”和“边”了，我可以直接考虑一个 CEO 智能体、一个调研员智能体和一个作者智能体，每个都有自己的岗位职责。
下面是我把它跑通的过程，也包括我踩过的一些坑。
搭建 Agency Swarm
首先，安装这个框架：
pip install agency-swarm
你需要在环境变量里设置好 OpenAI API 密钥：
export OPENAI_API_KEY="sk-your-key-here"
这一步挺简单的。但我踩了个坑：我第一次跑智能体的时候没把密钥设置对，结果报了个让人一头雾水的 Pydantic 校验错误，而不是直白地提示“缺少 API 密钥”。所以吸取我的教训吧：在继续深入之前，一定要反复检查你的环境变量。
构建你的第一个智能体
在 Agency Swarm 中，你可以通过继承基础的 Agent 类来定义智能体。每个智能体都会有一个角色描述，这起到了双重作用：它既能指导该智能体自身的行为，也能告诉其他智能体这个智能体能干什么。这一点非常关键——智能体之间完全是通过这些描述来了解彼此的能力的。
下面是我构建的一个调研员智能体的具体例子：
from agency_swarm import Agent
class Researcher(Agent):
def __init__(self):
super().__init__(
name="Researcher",
description="Conducts thorough web research on given topics and returns structured findings with sources.",
instructions="""You are a research specialist. When given a topic:
1. Search for relevant, recent information
2. Verify facts across multiple sources when possible
3. Structure your findings with clear headings
4. Always include source URLs
5. Flag any information you couldn't verify""",
model="gpt-4o",
tools=[],
)
description 字段是给其他智能体看的。而 instructions 字段是私有的——它是塑造智能体行为的系统提示词。一开始，我在 description 里塞了太多细节，而 instructions 写得不够，结果导致其他智能体总想对调研员指手画脚，而不是简单地把主题交给他。后来我划分了职责——对外沟通用简短的 description，指导行为用详细的 instructions——事情就顺畅多了。
创建自定义工具
这是 Agency Swarm 最出彩的地方。智能体需要工具才能真正干活，而这个框架让你可以很方便地用 Pydantic 校验来构建工具。每个工具的参数都会进行类型检查，这就解决了我之前常遇到的幻觉问题——智能体不能在需要整数的地方传个字符串进去。
下面是我为调研员构建的、用来保存调研结果的工具：
from agency_swarm import Tool
from pydantic import Field, HttpUrl
from typing import List
class SaveResearch(Tool):
"""Save research findings to a structured file."""
topic: str = Field(
..., description="The research topic"
)
findings: str = Field(
..., description="Key findings in markdown format"
)
sources: List[HttpUrl] = Field(
..., description="List of source URLs used"
)
confidence: int = Field(
..., description="Confidence level 1-5", ge=1, le=5
)
def run(self):
filename = f"research/{self.topic.replace(' ', '_')}.md"
content = f"# {self.topic}\n\n{self.findings}\n\n## Sources\n"
for source in self.sources:
content += f"- {source}\n"
content += f"\nConfidence: {self.confidence}/5"
with open(filename, 'w') as f:
f.write(content)
return f"Research saved to {filename}"
在测试时，Pydantic 校验真的抓到了一个真实的 bug：智能体试图传 confidence: "high" 而不是整数。框架自动发现了这个错误，并要求智能体用正确的类型重试。这就是纠错功能在实际发挥作用，省得我再写一大堆手动校验的代码。
将智能体连接成一个 Agency
Agency 是一个编排器，负责连接各个智能体并管理他们之间的通信。下面是我搭建一个简单内容流水线的方式：
from agency_swarm import Agency
class Writer(Agent):
def __init__(self):
super().__init__(
name="Writer",
description="Writes engaging content based on research findings.",
instructions="""You are a skilled writer. Take research findings and craft
well-structured, engaging content. Match the tone requested. Always cite sources
from the research provided.""",
model="gpt-4o",
tools=[],
)
class Editor(Agent):
def __init__(self):
super().__init__(
name="Editor",
description="Reviews and improves written content for clarity, grammar, and style.",
instructions="""You are a strict editor. Review content for:
- Grammar and spelling errors
- Logical flow and structure
- Factual consistency with provided research
- Appropriate tone
Return the edited version with a summary of changes.""",
model="gpt-4o",
tools=[],
)
researcher = Researcher()
writer = Writer()
editor = Editor()
agency = Agency(
name="ContentAgency",
agents=[researcher, writer, editor],
communication_flows=[
(researcher, writer),
(writer, editor),
(editor, writer), # Editor can send revisions back
],
shared_instructions="Focus on producing high-quality, accurate content.",
)
communication_flows 定义了谁可以和谁说话。我一开始犯了个错，允许所有智能体互相交流，结果乱成了一锅粥——编辑跑去搞调研，调研员又想改文章。把通信限制在特定的流程里，就能强制每个智能体各司其职。
运行 Agency
要开始工作，只需这样：
response = agency.get_response(
message="Research the latest developments in Rust's async ecosystem and write a 500-word summary",
recipient=researcher
)
Agency 会自动路由消息。调研员干完活，把结果传给作者；作者起草内容，发给编辑；如果编辑发现问题，就会打回给作者。整个循环无需人工干预就能跑起来。
我在日志里看到这个过程时，感觉是真的很爽——直到作者瞎编了一个调研结果里根本没有的来源。编辑发现了这个问题，直接打回让他修改。这正是系统按预期设计的体现。
使用 AutoSwarm 快速搭建
如果你想快速搞个原型，Agency Swarm 自带了 AutoSwarm 功能，可以自动生成智能体配置：
from agency_swarm import AutoSwarm, AutoSwarmRouter
swarm = AutoSwarm(
name="QuickContentTeam",
description="A team that researches and writes technical articles",
)
agency = swarm.create()
这玩意儿用来快速跑通点子很方便，但我发现自动生成的智能体如果要用在生产环境，还需要大量的人工微调。把 AutoSwarm 当作一个起点就好，别指望它能直接交付成品。
实用建议与坦诚的局限性
用了 Agency Swarm 几周后，这是我总结出的一些经验：
从两个智能体开始，而不是五个。 我一开始就搞了个五智能体的流水线，结果花了好几天调试通信问题。等我先把一个简单的“调研员-作者”组合跑稳了，再加更多智能体就容易多了。
描述比你想象的更重要。 其他智能体是根据描述来决定问什么以及怎么措辞的。描述写得模糊，交接就会出乱子。一定要具体：“进行网络调研，并以带有来源 URL 的 markdown 格式返回结果”可比干巴巴一句“做调研的”强多了。
注意你的 Token 成本。 每个智能体的调用都是一次独立的 API 请求。我的五智能体流水线烧 Token 那叫一个快，尤其是编辑和作者陷入反复修改循环的时候。我后来加了个 max_revisions 参数来设置上限。
这个框架重度依赖 OpenAI。 虽然技术上你也可以用其他提供商，但它和 OpenAI 的 Responses API 结合得最紧密，这意味着老老实实用 GPT 模型体验才最顺滑。如果你需要用 Claude 或者开源模型，做好踩坑的准备吧。
错误处理不错，但不是万能药。 Pydantic 校验能抓到类型不匹配的问题，但它没法搞定本质上就搞不清状况的智能体。我还是得不断迭代指令，才能获得稳定可靠的行为。
可以部署，但还需打磨。 框架自称可用于生产环境，核心的编排逻辑也确实很稳。但如果你想上真实的生产系统，还得自己加日志、监控和重试逻辑。我给自己的 Agency 调用包了一层 try/except，并加了指数退避来应对 API 速率限制。
Agency Swarm 解决了我最初的问题——内容流水线现在跑得很稳，而且出了错，我也能立刻看出是哪个智能体、哪个环节出了问题。这种“专职智能体+清晰沟通渠道”的心智模型，非常契合我思考工作流的方式。它并不完美，但确实是我目前用过的最实用的多智能体框架了。