🐝 代理集群

概述

代理集群是一个用于构建多智能体应用的框架。它基于并扩展了 OpenAI Agents SDK，提供了专门的功能来创建、编排和管理协作性的智能体群。

该框架延续了 Arsenii Shatokhin（又名 VRSEN）的原始愿景，即通过将自动化视为现实世界的组织结构，从而简化 AI 机构的创建过程，使智能体和用户都能直观地理解和使用。

从 v0.x 迁移吗？ 请参阅我们的 迁移指南，了解如何将您的项目适配到这个基于 SDK 的新版本。

核心特性

• 可自定义的智能体角色：在代理集群框架中，利用底层的 OpenAI Agents SDK，定义不同的智能体角色（如 CEO、虚拟助理、开发者），并为其配备定制化的指令、工具和能力。
• 完全掌控提示/指令：您可以完全控制每个智能体的引导提示（指令），以实现精确的行为定制。
• 类型安全的工具：使用 Pydantic 模型开发工具，实现自动参数验证，兼容 OpenAI Agents SDK 的 FunctionTool 格式。
• 协调的智能体通信：智能体通过专用的 send_message 工具进行通信，交互由 Agency 上明确、定向的 communication_flows 规则管理。
• 灵活的状态持久化：通过为 Agency 提供 load_threads_callback 和 save_threads_callback，管理对话历史，实现跨会话的持久化存储（如数据库或文件存储）。
• 多智能体编排：在 OpenAI Agents SDK 的基础上构建智能体工作流，并通过代理集群的结构化编排层进一步增强。
• 面向生产环境：专为可靠性设计，易于部署于实际环境中。

安装

pip install -U agency-swarm

v1.x 注意事项： 该框架针对的是 OpenAI Agents SDK + Responses API。 从 v0.x 迁移吗？请参阅 迁移指南。

兼容性

• Python：3.12 及以上版本
• 模型后端：
  • OpenAI（原生）： GPT-5 系列、GPT-4o 等
  • 通过 LiteLLM（路由器）： Anthropic（Claude）、Google（Gemini）、Grok（xAI）、Azure OpenAI、OpenRouter（网关） 等
• 操作系统：macOS、Linux、Windows

如果您遇到环境问题，请参阅 安装指南。

开始使用

推荐：在自定义任何内容之前，请先从 Agency Starter Template 开始。

1. 设置 OpenAI API 密钥：

   • 创建一个包含 OPENAI_API_KEY=your_key 的 .env 文件（自动加载），或者在你的 shell 中导出它：

   export OPENAI_API_KEY="YOUR_API_KEY"
   

2. 创建工具： 使用现代的 @function_tool 装饰器定义工具（推荐），或扩展 BaseTool（兼容）：

   from agency_swarm import function_tool
   
   @function_tool
   def my_custom_tool(example_field: str) -> str:
       """自定义工具的简要描述。"""
       return f"结果：{example_field}"
   

   或者使用 BaseTool：

   from agency_swarm.tools import BaseTool
   from pydantic import Field
   
   class MyCustomTool(BaseTool):
       """
       自定义工具的简要描述。
       文档字符串应清晰说明工具的目的和功能。
       代理将根据此文档决定何时使用该工具。
       """
   
       # 使用 Pydantic Field 定义带有描述的字段
       example_field: str = Field(
           ..., description="示例字段的描述，解释其用途及对代理的意义。"
       )
   
       def run(self):
           """
           run 方法的实现，执行工具的主要功能。
           """
           # 在这里编写自定义工具的逻辑
           # do_something(self.example_field)
   
           # 返回工具操作的结果
           return "MyCustomTool 操作的结果"
   

   或者从 OpenAPI 模式转换：

   from agency_swarm.tools import ToolFactory
   # 使用本地文件
   with open("schemas/your_schema.json") as f:
       tools = ToolFactory.from_openapi_schema(
           f.read(),
       )
   
   # 使用 requests
   import requests
   tools = ToolFactory.from_openapi_schema(
       requests.get("https://api.example.com/openapi.json").json(),
   )
   

3. 定义代理角色：首先定义你的代理角色。例如，一个 CEO 代理用于管理任务，一个开发者代理用于执行任务。

   from agency_swarm import Agent, ModelSettings
   
   ceo = Agent(
       name="CEO",
       description="负责客户沟通、任务规划与管理。",
       instructions="您必须与其他代理对话，以确保任务的完整执行。"，# 可以是像 ./instructions.md 这样的文件
       files_folder="./files", # 将上传到 OpenAI 的文件
       schemas_folder="./schemas", # 将转换为工具的 OpenAPI 模式
       tools=[my_custom_tool],  # 由 @function_tool 返回的 FunctionTool（或通过 ToolFactory 转换 BaseTool）
       model="gpt-5.4-mini",
       model_settings=ModelSettings(
           max_tokens=25000,
       ),
   )
   

   从示例入手：

   • 浏览 ./examples 查看可运行的演示和模式，以便进行调整。
   • 使用仓库根目录下的 .cursorrules 文件，配合你的 AI 编码代理（Cursor、Claude Code 等）。
   • 参阅 Cursor IDE 指南：https://agency-swarm.ai/welcome/getting-started/cursor-ide

4. 定义机构通信流程： 确定你的代理之间如何相互沟通。

   from agency_swarm import Agency
   # 如果从本地文件导入
   from Developer import Developer
   from VirtualAssistant import VirtualAssistant
   
   dev = Developer()
   va = VirtualAssistant()
   
   agency = Agency(
       ceo,  # CEO 将作为与用户沟通的入口点
       communication_flows=[
           ceo > dev,  # CEO 可以发起与开发者之间的沟通
           ceo > va,   # CEO 可以发起与虚拟助理之间的沟通
           dev > va    # 开发者可以发起与虚拟助理之间的沟通
       ],
       shared_instructions='agency_manifesto.md', # 所有代理共享的指令
   )
   

   在 Agency Swarm 中，通信流程是单向的。> 运算符定义了允许的发起方（左侧可以发起与右侧的对话）。

5. 运行演示

Web UI：

agency.copilot_demo()

终端：

agency.tui()

首次运行时，Agency Swarm 会自动设置终端应用，显示简短的设置信息，并在后续运行中重复使用。

查看终端工作流指南：https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli

程序化（异步）：

import asyncio

async def main():
    resp = await agency.get_response("创建一个项目框架。")
    print(resp.final_output)

asyncio.run(main())

需要同步吗？agency.get_response_sync(...) 也存在，但建议使用异步方式。

文件夹结构

推荐的代理文件夹结构如下：

/your-specified-path/
│
├── agency_manifesto.md 或 .txt # 机构的指导原则（如不存在则会创建）
└── AgentName/                  # 特定代理的目录
    ├── files/                  # 将上传到 OpenAI 的文件目录
    ├── schemas/                # 将转换为工具的 OpenAPI 模式的目录
    ├── tools/                  # 默认导入工具的目录
    ├── AgentName.py            # 主代理类文件
    ├── __init__.py             # 初始化代理文件夹为 Python 包
    ├── instructions.md 或 .txt # 代理的指令文档
    └── tools.py                # 专属于该代理角色的自定义工具。

这种结构确保每个代理都有独立的空间，包含开始执行特定任务所需的所有文件。tools.py 可以根据代理的角色定制工具和功能。

了解更多

• 安装：https://agency-swarm.ai/welcome/installation
• 从零开始指南：https://agency-swarm.ai/welcome/getting-started/from-scratch
• Cursor IDE 工作流：https://agency-swarm.ai/welcome/getting-started/cursor-ide
• 工具概述：https://agency-swarm.ai/core-framework/tools/overview
• 代理概述：https://agency-swarm.ai/core-framework/agents/overview
• 机构概述：https://agency-swarm.ai/core-framework/agencies/overview
• 通信流程：https://agency-swarm.ai/core-framework/agencies/communication-flows
• 运营机构：https://agency-swarm.ai/core-framework/agencies/running-agency
• Agent Swarm CLI：https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli
• 可观测性：https://agency-swarm.ai/additional-features/observability

贡献

有关如何为 Agency Swarm 做贡献的详细信息，请参阅 贡献指南。

许可证

Agency Swarm 是开源项目，采用 MIT 许可证。

需要帮助吗？

如果您需要帮助为您的企业创建自定义智能体集群，请查看我们的智能体即服务订阅计划，或通过 https://calendly.com/vrsen/ai-readiness-call 预约与我进行咨询。

Agency Swarm 快速上手指南

Agency Swarm 是一个基于 OpenAI Agents SDK 构建的多智能体（Multi-Agent）应用框架。它允许你通过定义真实的组织架构（如 CEO、开发者、助理等角色）来编排和协作 AI 智能体群。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS, Linux, 或 Windows
• Python 版本：3.12 或更高版本（必须）
• API Key：你需要一个有效的 OpenAI API Key。
  • 注：该框架原生支持 OpenAI 模型。若需使用 Anthropic (Claude)、Google (Gemini) 或国内大模型，可通过 LiteLLM 路由进行配置。

2. 安装步骤

使用 pip 安装最新版本的 agency-swarm：

pip install -U agency-swarm

提示：如果你在中国大陆地区遇到下载速度慢的问题，建议使用国内镜像源加速安装：

pip install -U agency-swarm -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

以下是构建一个简单双智能体协作系统的最小化流程。

第一步：配置 API Key

在项目根目录创建 .env 文件，或在终端中导出环境变量：

export OPENAI_API_KEY="YOUR_API_KEY"

第二步：定义工具 (Tools)

智能体通过工具执行具体任务。你可以使用 @function_tool 装饰器快速定义：

from agency_swarm import function_tool

@function_tool
def get_weather(city: str) -> str:
    """获取指定城市的天气信息。"""
    return f"The weather in {city} is sunny."

或者使用更复杂的 Pydantic 类定义（适用于需要严格参数校验的场景）：

from agency_swarm.tools import BaseTool
from pydantic import Field

class SearchDatabase(BaseTool):
    """在内部数据库中搜索相关信息。"""
    query: str = Field(..., description="搜索关键词")

    def run(self):
        # 在此处编写具体的搜索逻辑
        return f"Search results for: {self.query}"

第三步：定义智能体角色 (Agents)

创建具体的智能体实例，赋予其指令、工具和模型配置：

from agency_swarm import Agent, ModelSettings

# 定义一个 CEO 智能体
ceo = Agent(
    name="CEO",
    description="负责与客户沟通并规划任务。",
    instructions="你必须与其他智能体协作以确保任务完成。",
    tools=[get_weather],  # 挂载之前定义的工具
    model="gpt-4o",       # 指定模型
    model_settings=ModelSettings(max_tokens=25000),
)

# 定义一个开发者智能体
developer = Agent(
    name="Developer",
    description="负责执行具体的代码开发任务。",
    instructions="你负责编写代码和解决技术问题。",
    tools=[],             # 可以挂载不同的工具集
    model="gpt-4o",
)

第四步：组建机构并定义通信流 (Agency & Flows)

将智能体组合成 Agency，并使用 > 操作符定义谁可以主动发起对话（通信流向）：

from agency_swarm import Agency

agency = Agency(
    ceo,  # CEO 作为用户交互的入口
    communication_flows=[
        ceo > developer,  # CEO 可以指派任务给开发者
        # developer > ceo, # 如果需要开发者主动汇报，可取消注释此行
    ],
    shared_instructions='agency_manifesto.md', # 可选：所有智能体共享的指令文件
)

第五步：运行与交互

你可以选择三种方式运行你的智能体机构：

方式 A：终端交互界面 (推荐) 自动启动一个交互式终端 UI：

agency.tui()

方式 B：Web 演示界面 启动一个简单的 Web Copilot 界面：

agency.copilot_demo()

方式 C：代码编程调用 (异步) 在你的应用中直接获取响应：

import asyncio

async def main():
    # 发送指令并获取最终结果
    resp = await agency.get_response("查询北京天气并制定开发计划。")
    print(resp.final_output)

asyncio.run(main())

---

更多高级功能（如持久化存储、OpenAPI 工具导入、多智能体复杂编排）请参考官方文档。