agency-swarm

🐝 Agency Swarm：像管理公司一样编排 AI Agent 团队

从一个"疯狂想法"开始的框架

2024 年，一位名叫 Arsenii Shatokhin（网名 VRSEN）的开发者决定把自己的 AI 咨询公司彻底自动化——不是用 AI 辅助人类工作，而是让 AI Agent 代替人类去运营公司。他花了大量时间研究如何让多个 AI 智能体像真实公司里的员工一样协作：有人做决策、有人写代码、有人与客户沟通。经过数月的实践和迭代，他将这些经验总结为一个开源框架——Agency Swarm。

这个框架的核心洞察很朴素：与其让一个超级 AI 解决所有问题，不如让多个专业 AI Agent 各司其职，像真实团队一样通过明确分工和通信协议协作。 这个理念直接借鉴了现实世界的组织架构——CEO 统筹、工程师执行、助理协调，各有各的角色和能力边界。

核心架构：从 Agent 到 Agency 的层级设计

Agency Swarm 的架构分为三层设计：

第一层：Agent（智能体）。每个 Agent 是一个独立的 AI 实例，拥有专属的角色定义（instructions）、专属工具集和对话上下文。你可以为"后端开发者""产品经理""客服专员"分别创建 Agent，每个 Agent 的 prompt 被精心设计为只关注自己的职责范围。Agent 使用 Pydantic 模型定义工具参数，实现类型安全的参数验证，避免模型幻觉导致的工具调用错误。

第二层：Tool（工具）。工具是 Agent 能力的延伸，通过 @function_tool 装饰器或继承 BaseTool 定义。框架支持从 OpenAPI Schema 自动生成工具（ToolFactory），也支持 MCP（Model Context Protocol）服务器扩展，这意味着 Agent 可以连接到任何外部 API——邮件系统、数据库、GitHub、Slack，不一而足。

第三层：Agency（机构）。这是整个编排的核心。你定义各个 Agent 之间的通信流向（Communication Flows），用类似 ceo > dev > va 的符号明确谁可以主动联系谁。通信是定向的、显式的，而不是全员广播式的混乱对话。Agency 还支持 shared_instructions（共享指导原则），让所有 Agent 在同一套价值观下运作。

用 FastAPI 构建生产级服务

项目大量使用 FastAPI + Uvicorn 构建 Web 服务，支持通过 AG-UI 协议（ag-ui-protocol）实现前端集成。这让开发者可以将 Agent 对话能力嵌入任何 Web 应用。integrations/fastapi.py 模块提供了开箱即用的 FastAPI 集成，可以快速将 Agency Swarm 暴露为 REST API 端点。此外，框架还支持通过 OpenClaw 协议实现持久化存储和更复杂的 Agent 编排。

测试覆盖率达到 92%，使用 pytest + pytest-asyncio + pytest-mock 进行单元和集成测试，代码质量较高。

谁在用它？

Agency Swarm 的用户群体正在快速扩张。超过 1000 个 Fork、4400+ Stars 的数据表明它已获得开发者社区的高度关注。典型的使用场景包括：构建 AI 驱动的软件开发团队（CEO Agent 接收需求 → Developer Agent 写代码 → Reviewer Agent 检查）、自动化客户支持流程、以及复杂的多步骤研究任务。项目主页还提供付费的"Agents-as-a-Service"企业服务，适合不想自建基础设施的团队。

上手门槛：CLI 是最容易的入口

最简单的方式是 pip 安装后直接用 CLI：

pip install -U agency-swarm

安装 Python 3.12+ 环境和配置 API Key 是唯一的前提条件。官方推荐从 agency-starter-template 模板仓库开始，可以快速获得一个包含 CEO、Developer、VirtualAssistant 三个 Agent 的示例项目。CLI 界面（agency-swarm tui）提供交互式终端体验，copilot_demo() 则启动一个 Web 界面。异步 API（agency.get_response()）适合集成到现有 Python 应用中。

局限与挑战

需要正视的是：这个框架目前高度依赖 OpenAI API 或通过 LiteLLM 支持的其他服务。这意味着你必须拥有可靠的 LLM API 访问，并且 API 成本会随 Agent 数量和对话轮数线性增长。此外，虽然框架提供了结构化的通信协议，但设计多个 Agent 的角色边界和通信流程本身需要一定的经验——设计不当会导致 Agent 陷入互相等待或循环通信的死锁状态。没有 Docker 支持也意味着在非 Python 环境（如 Windows）或 CI/CD 流程中部署相对麻烦。

行业意义

Agency Swarm 代表了 AI Agent 领域的一个重要趋势：从"一个超级 Agent 做所有事"转向"多 Agent 协作分工"。这种范式与人类组织的运作方式高度一致，使得 AI 系统的行为更可预测、更可调试。框架作者 VRSEN 本人通过"AI 自动化 AI 咨询公司"的实践证明了这一路径的可行性。随着 OpenAI Responses API 和 Responses SDK 的成熟，预计会有更多类似的编排框架涌现，而 Agency Swarm 已经在这个方向上建立了先发优势。

图1：Cursor IDE 与 Agency Swarm 集成概览

图2：Agent Swarm CLI 交互界面

图3：多 Agent 协作流程示意图