Overview

Agency Swarm is a reliable multi-agent orchestration framework for building multi-agent applications. It leverages and extends the OpenAI Agents SDK, providing specialized functionality for creating, orchestrating, and managing collaborative AI agent swarms. The framework continues the original vision of Arsenii Shatokhin (also known as VRSEN): thinking about automation in terms of real-world organizational structures, thereby simplifying the creation of AI agencies and making them intuitive for both agents and users.

Key Capabilities

Customizable agent roles: Different agent roles can be defined within the framework (such as CEO, virtual assistant, developer), each configured with dedicated instructions, tools, and capabilities, powered underneath by the OpenAI Agents SDK.
Full control over prompts/instructions: Maintain complete control over each agent's guiding prompts (instructions) to precisely customize behavior.
Type-safe tools: Develop tools using Pydantic models to achieve automatic parameter validation, and remain compatible with the OpenAI Agents SDK's FunctionTool format.
Orchestrated agent communication: Agents communicate through a dedicated send_message tool, with interactions constrained by explicit, directed communication_flows on the Agency.
Flexible state persistence: Manage session history by providing load_threads_callback and save_threads_callback to the Agency, thereby supporting persistence across sessions (for example, database/file storage).
Multi-agent orchestration: Build agent workflows on top of the OpenAI Agents SDK, enhanced by Agency Swarm's structured orchestration layer.
Production-oriented: Built with reliability as a goal and designed for deployment in real-world environments.

Model Backends

OpenAI (native): GPT-5 series, GPT-4o, etc.
Via LiteLLM (router): Anthropic (Claude), Google (Gemini), Grok (xAI), Azure OpenAI, OpenRouter (gateway), etc.

Usage

Prerequisites: Supported operating systems are macOS, Linux, and Windows. If you encounter environment issues, please refer to the installationinstallation guide (https://agency-swarm.ai/welcome/installation）。

Set the OpenAI key: Create a .env file and write OPENAI_API_KEY=your_key (it will be loaded automatically), or export it in the shell: export OPENAI_API_KEY="YOUR_API_KEY".
Create tools: It is recommended to define tools using the modern @function_tool decorator, or inherit from BaseTool (compatible). Example:

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}"

Or use 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"

You can also convert from an 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(),
)

Define agent roles: For example, define a CEO agent responsible for management and tasks, and a developer agent responsible for executing tasks.

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,
    ),
)

Define Agency communication flows: establish how agents communicate with each other.

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
)

In Agency Swarm, communication flows are directional. The > operator defines the allowed initiation relationships (the left side can initiate a chat with the right side).

Run: On the first run, Agency Swarm automatically sets up the terminal app, displays brief setup information, and reuses it on subsequent runs. See the terminal workflow guide:https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli。以编程方式（异步）运行亦可；如需同步，agency.get_response_sync(...) is available, but async is recommended.

Use cases

Scenarios that require multiple AI agents to collaborate on complex tasks in organized roles.
Scenarios that require explicit directed communication flows to control interaction relationships between agents.
Multi-agent applications that require conversation state to persist across sessions.
Projects that want a structured orchestration layer on top of the OpenAI Agents SDK.
Multi-agent workflows that require reliable deployment for production environments.

Limitations and notes

The v1.x version targets the OpenAI Agents SDK + Responses API; for migration from v0.x, see the migration guide.
If a synchronous API is needed, although get_response_sync(...) exists, the official recommendation is to use async.
An OpenAI key must be set before use; if using another model backend, it must be routed through LiteLLM.
For environment issues, see the installation guide.
The project is open source and uses the MIT license. Custom business agent clusters can be obtained through the Agents-as-a-Service subscription or by booking a consultation (https://calendly.com/vrsen/ai-readiness-call）。

agency-swarm

About this tool

Overview

Key Capabilities

Model Backends

Usage

Use cases

Limitations and notes

Recommended resources and documentation

agency-swarm

About this tool

Overview

Key Capabilities

Model Backends

Usage

Use cases

Limitations and notes

Recommended resources and documentation

Related tools

SuperAPI Relay

LangChain

HuggingFace