概述

Agency Swarm 是一个可靠的多智能体编排框架，用于构建多智能体应用。它在 OpenAI Agents SDK 的基础上进行利用与扩展，提供创建、编排和管理协作式 AI 智能体集群的专门功能。该框架延续了 Arsenii Shatokhin（又名 VRSEN）的原始构想：按现实世界的组织结构来思考自动化，从而简化 AI agency 的创建，使智能体与用户都能直观上手。

主要能力

可定制的智能体角色：可在框架内定义不同的智能体角色（如 CEO、虚拟助理、开发者），为其配置专属指令、工具与能力，底层依托 OpenAI Agents SDK。
对提示/指令的完全控制：对每个智能体的引导性提示（instructions）保持完全控制，以便精确定制行为。
类型安全的工具：使用 Pydantic 模型开发工具，实现参数自动校验，并与 OpenAI Agents SDK 的 FunctionTool 格式兼容。
受编排的智能体通信：智能体通过专用的 send_message 工具进行通信，交互由 Agency 上显式、定向的 communication_flows 约束。
灵活的状态持久化：通过向 Agency 提供 load_threads_callback 和 save_threads_callback 来管理会话历史，从而支持跨会话持久化（例如数据库/文件存储）。
多智能体编排：在 OpenAI Agents SDK 基础上构建智能体工作流，并由 Agency Swarm 的结构化编排层增强。
面向生产：以可靠性为目标构建，并针对真实环境中的部署进行设计。

模型后端

OpenAI（原生）：GPT-5 系列、GPT-4o 等。
通过 LiteLLM（路由器）：Anthropic（Claude）、Google（Gemini）、Grok（xAI）、Azure OpenAI、OpenRouter（网关）等。

使用方式

先决条件：操作系统支持 macOS、Linux、Windows。若遇到环境问题，请参阅安装指南（https://agency-swarm.ai/welcome/installation）。

设置 OpenAI 密钥：创建 .env 文件并写入 OPENAI_API_KEY=your_key（会自动加载），或在 shell 中导出：export OPENAI_API_KEY="YOUR_API_KEY"。
创建工具：推荐使用现代 @function_tool 装饰器定义工具，或继承 BaseTool（兼容）。示例：

from agency_swarm import function_tool

@function_tool
def my_custom_tool(example_field: str) -> str:
    """A brief description of what the custom tool does."""
    return f"Result: {example_field}"

或使用 BaseTool：

from agency_swarm.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    """
    A brief description of what the custom tool does.
    The docstring should clearly explain the tool's purpose and functionality.
    It will be used by the agent to determine when to use this tool.
    """
    # Define the fields with descriptions using Pydantic Field
    example_field: str = Field(
        ..., description="Description of the example field, explaining its purpose and usage for the Agent."
    )

    def run(self):
        """
        The implementation of the run method, where the tool's main functionality is executed.
        """
        # Your custom tool logic goes here
        # do_something(self.example_field)

        # Return the result of the tool's operation
        return "Result of MyCustomTool operation"

也可以从 OpenAPI schema 转换：

from agency_swarm.tools import ToolFactory

# using local file
with open("schemas/your_schema.json") as f:
    tools = ToolFactory.from_openapi_schema(
        f.read(),
    )

# using requests
import requests
tools = ToolFactory.from_openapi_schema(
    requests.get("https://api.example.com/openapi.json").json(),
)

定义智能体角色：例如定义一个负责管理与任务的 CEO 智能体，以及一个负责执行任务的开发者智能体。

from agency_swarm import Agent, ModelSettings

ceo = Agent(
    name="CEO",
    description="Responsible for client communication, task planning and management.",
    instructions="You must converse with other agents to ensure complete task execution.",  # can be a file like ./instructions.md
    files_folder="./files",  # files to be uploaded to OpenAI
    schemas_folder="./schemas",  # OpenAPI schemas to be converted into tools
    tools=[my_custom_tool],  # FunctionTool returned by @function_tool (or adapt BaseTool via ToolFactory)
    model="gpt-6-luna",
    model_settings=ModelSettings(
        max_tokens=25000,
    ),
)

定义 Agency 通信流：建立智能体之间的通信方式。

from agency_swarm import Agency

# if importing from local files
from Developer import Developer
from VirtualAssistant import VirtualAssistant

dev = Developer()
va = VirtualAssistant()

agency = Agency(
    ceo,  # CEO will be the entry point for communication with the user
    communication_flows=[
        ceo > dev,  # CEO can initiate communication with Developer
        ceo > va,  # CEO can initiate communication with Virtual Assistant
        dev > va,  # Developer can initiate communication with Virtual Assistant
    ],
    shared_instructions="agency_manifesto.md",  # shared instructions for all agents
)

在 Agency Swarm 中，通信流是有方向的。> 运算符定义允许的发起关系（左侧可向右侧发起聊天）。

运行：首次运行时，Agency Swarm 会自动设置终端应用，显示简短设置信息，并在后续运行中复用。参见终端工作流指南：https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli。以编程方式（异步）运行亦可；如需同步，agency.get_response_sync(...) 可用，但推荐使用异步。

适用场景

需要将多个 AI 智能体按组织化角色协同完成复杂任务的场景。
需要通过显式定向通信流控制智能体之间交互关系的场景。
需要会话状态跨会话持久化的多智能体应用。
希望在 OpenAI Agents SDK 基础上获得结构化编排层的项目。
需要面向生产环境可靠部署的多智能体工作流。

限制与说明

v1.x 版本面向 OpenAI Agents SDK + Responses API；从 v0.x 迁移请参阅迁移指南。
若需同步 API，虽然存在 get_response_sync(...)，但官方推荐使用异步。
使用前需设置 OpenAI 密钥；若使用其他模型后端需通过 LiteLLM 路由。
遇到环境问题请参阅安装指南。
项目开源，采用 MIT 许可证。商务定制智能体集群可通过 Agents-as-a-Service 订阅或预约咨询（https://calendly.com/vrsen/ai-readiness-call）。

agency-swarm

工具介绍

概述

主要能力

模型后端

使用方式

适用场景

限制与说明

推荐资源与文档

agency-swarm

工具介绍

概述

主要能力

模型后端

使用方式

适用场景

限制与说明

推荐资源与文档

同类工具

SuperAPI 中转站

LangChain

HuggingFace