Related Pages

Related topics: Installation and Setup, Getting Started Guide, Core Architecture

Introduction to Agency Swarm

Agency Swarm is a multi-agent orchestration framework designed for building autonomous AI agent systems that can collaborate, communicate, and delegate tasks between specialized agents. The framework enables developers to create complex workflows where multiple AI agents work together to accomplish tasks that require diverse capabilities.

Overview

Agency Swarm provides a structured approach to building multi-agent systems with the following core capabilities:

• Agent Definition: Create specialized agents with specific roles, instructions, and tools
• Inter-Agent Communication: Enable agents to communicate and transfer control via handoffs
• Tool Integration: Support for custom tools, OpenAPI schema conversion, and built-in capabilities
• Agency Management: Orchestrate multiple agents within an agency context
• User Interfaces: Multiple UI options including Terminal UI (TUI), Copilot UI, and visualization

Sources: README.md

Architecture Overview

The framework is built around two primary concepts: Agents and Agencies. Agents represent individual AI workers with specific responsibilities, while Agencies coordinate multiple agents to accomplish complex tasks.

graph TD
    A[User] --> B[Agency]
    B --> C[CEO Agent]
    C --> D[Developer Agent]
    C --> E[Support Agent]
    D --> F[Custom Tools]
    E --> G[WebSearch Tool]
    D --> H[File Management]
    E --> D

Sources: README.md

Core Components

Creating Agents

Agents are the fundamental building blocks of Agency Swarm. Each agent has a name, description, instructions, tools, and model configuration.

Agent Folder Structure

AgentName/
├── files/                  # Files to upload to OpenAI
├── schemas/                # OpenAPI schemas for tool generation
├── tools/                  # Agent-specific tools
├── AgentName.py            # Main agent class
├── __init__.py             # Package initialization
└── instructions.md         # Agent instruction document

Sources: CONTRIBUTING.md

Agent Implementation Example

from agency_swarm import Agent, ModelSettings
from agency_swarm.tools.example import ExampleTool

class SupportAgent(Agent):
    def __init__(self):
        super().__init__(
            name="SupportAgent",
            description="Handles customer support requests",
            instructions="./instructions.md",
            files_folder="./files",
            tools=[ExampleTool],
            model="gpt-5.4-mini",
            model_settings=ModelSettings(
                temperature=0.3,
                max_tokens=25000,
            ),
        )

Sources: README.md

Agent Core Methods

The Agent class provides several core execution methods for handling interactions:

Sources: src/agency_swarm/agent/core.py

Tools System

Agency Swarm supports multiple tool definition patterns to give agents capabilities beyond plain text generation.

Tool Definition Patterns

BaseTool Implementation

from agency_swarm.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    example_field: str = Field(
        ..., description="Description of the example field"
    )

    def run(self):
        return f"Result: {self.example_field}"

Sources: README.md

OpenAPI Schema Conversion

from agency_swarm.tools import ToolFactory

with open("schemas/your_schema.json") as f:
    tools = ToolFactory.from_openapi_schema(f.read())

Sources: README.md

Agency Structure

The Agency class orchestrates multiple agents and defines how they communicate with each other.

Defining an Agency

from agency_swarm import Agency, Agent

ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)
support = Agent(name="Support", ...)

agency = Agency(
    ceo,
    developer,
    support,
    communication_flows=[
        (ceo, developer),      # CEO can delegate to Developer
        (ceo, support),        # CEO can delegate to Support
        (support, developer),  # Support can handoff to Developer
    ],
    shared_instructions="Agency-wide guidelines",
)

Communication Flows

Communication flows define the allowed message paths between agents. The framework supports two primary communication patterns:

Sources: examples/README.md

User Interfaces

Agency Swarm provides multiple UI options for interacting with agencies.

Available UIs

Terminal UI Example

if __name__ == "__main__":
    create_demo_agency().tui(show_reasoning=True)

Sources: examples/interactive/tui.py

Running the Agency

Synchronous Execution

agency = Agency(ceo, developer, support)
response = agency.get_response_sync("Create a project skeleton")

Asynchronous Execution

import asyncio

async def main():
    resp = await agency.get_response("Create a project skeleton")
    print(resp.final_output)

asyncio.run(main())

Sources: README.md

Model Configuration

Agents can be configured with specific model settings for fine-tuned control over generation behavior.

ModelSettings Parameters

Reasoning Models

For reasoning models (like o1 series), the framework automatically handles compatibility:

• Temperature parameter is disabled for reasoning models
• Reasoning effort can be configured via ModelSettings(reasoning=Reasoning(effort="low"))

Sources: src/agency_swarm/utils/create_agent_template.py

Integration with External Services

Agency Swarm supports integration with external frameworks like FastAPI and OpenClaw.

FastAPI Integration

from agency_swarm.integrations.fastapi import run_fastapi

app = run_fastapi(
    agencies={"my_agency": create_agency},
    app_token_env="APP_TOKEN",
    return_app=True,
)

Sources: src/agency_swarm/integrations/README.md

Example Workflow

sequenceDiagram
    participant User
    participant Agency
    participant CEO
    participant Developer
    participant Support

    User->>Agency: Initial Request
    Agency->>CEO: Process Request
    CEO->>Support: Route to Support
    Support->>CEO: Needs Development
    CEO->>Developer: Delegate Task
    Developer-->>CEO: Task Complete
    CEO-->>Agency: Final Response
    Agency-->>User: Response

Key Features Summary

Sources: examples/README.md

Getting Started

1. Install Agency Swarm: pip install agency-swarm
2. Create your first agent with the CLI: agency-swarm create-agent
3. Define tools and instructions
4. Compose agents into an agency
5. Run the agency with get_response_sync() or async get_response()

Related Pages

Related topics: Introduction to Agency Swarm, Getting Started Guide

Installation and Setup

This guide covers how to install Agency Swarm, configure your development environment, and set up your first multi-agent project.

Prerequisites

Before installing Agency Swarm, ensure you have the following:

Installation Methods

From PyPI (Recommended)

pip install agency-swarm

From Source

git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm
pip install -e .

Development Installation

For contributors working on Agency Swarm itself:

git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm
pip install -e ".[dev]"

Sources: CONTRIBUTING.md:1-20

Environment Configuration

Required Environment Variables

export OPENAI_API_KEY="sk-your-key-here"

For persistent configuration, add this to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Optional Configuration

CLI Installation and Setup

Agency Swarm provides a command-line interface for agent creation and management.

Verify CLI Installation

agency-swarm --version

CLI Command Reference

Sources: src/agency_swarm/cli/main.py:1-50

#### Create Agent Command Options

agency-swarm create-agent [AGENT_NAME] [options]

Sources: src/agency_swarm/utils/create_agent_template.py:1-40

#### Migrate Agent Command

agency-swarm migrate-agent path_to_settings.json [--output-dir DIR]

This converts an OpenAI Assistant configuration into an Agency Swarm agent definition.

Sources: src/agency_swarm/cli/main.py:80-95

Project Structure Setup

When creating a new agent using the CLI, the following structure is generated:

agency_swarm/agents/AgentName/
├── AgentName/
│   ├── files/                  # Files uploaded to OpenAI
│   ├── tools/                  # Agent-specific tools
│   ├── schemas/                # OpenAPI schemas
│   ├── AgentName.py            # Main agent class
│   ├── __init__.py             # Package initialization
│   └── instructions.md         # Agent instructions

Sources: CONTRIBUTING.md:60-75

Agent Template Example

from agency_swarm import Agent
from agency_swarm.tools.example import ExampleTool

class AgentName(Agent):
    def __init__(self):
        super().__init__(
            name="AgentName",
            description="Description of the agent",
            instructions="instructions.md",
            tools=[ExampleTool],
        )

Sources: CONTRIBUTING.md:1-15

Tool Installation

Agency Swarm provides pre-built tools that can be imported into your project.

List Available Tools

agency-swarm import-tool --list

Import a Tool

agency-swarm import-tool ToolName [--directory ./tools]

Tools are organized by category in the agency_swarm/tools/ directory:

agency_swarm/tools/{category}/
├── YourNewTool.py
└── __init__.py

Sources: CONTRIBUTING.md:40-55

Development Dependencies

Install Dev Dependencies

make sync

Run Test Suite

make coverage

The make coverage command runs the test suite with coverage reporting.

Sources: CONTRIBUTING.md:25-35

Quick Start: Your First Agency

graph TD
    A[Install agency-swarm] --> B[Set OPENAI_API_KEY]
    B --> C[Create Agent Templates]
    C --> D[Define Communication Flows]
    D --> E[Initialize Agency]
    E --> F[Run get_response]

Complete Example

from agency_swarm import Agency, Agent
from agency_swarm.tools import WebSearchTool

# Create agents
support = Agent(
    name="SupportAgent",
    description="Handles user inquiries",
    instructions="You are a helpful support agent.",
    tools=[WebSearchTool()],
    model="gpt-5.4-mini",
)

# Initialize agency
agency = Agency(support)

# Run
result = agency.get_response_sync("Hello!")

Sources: examples/README.md:1-20

Troubleshooting

Common Installation Issues

Verify Installation

import agency_swarm
print(agency_swarm.__version__)

Running Examples

Examples are located in the examples/ directory. Each can be run directly:

cd examples
python multi_agent_workflow.py

Sources: examples/README.md:1-30

Next Steps

After installation, explore:

• Getting Started Guide - Build your first agency
• Agent Communication - Configure agent-to-agent messaging
• Tool Development - Create custom tools
• FastAPI Integration - Deploy as API service

Related Pages

Related topics: Introduction to Agency Swarm, Installation and Setup, Core Architecture, Tools System

Getting Started Guide

Welcome to the Agency Swarm Getting Started Guide. This guide provides comprehensive instructions for setting up your development environment, understanding the project structure, and building your first multi-agent application using the Agency Swarm framework.

Overview

Agency Swarm is a framework for building multi-agent systems that enables multiple AI agents to collaborate through defined communication flows. The framework provides tools for creating agents, defining their capabilities through tools, establishing communication patterns between agents, and visualizing agent hierarchies.

This guide covers the essential steps from initial environment setup to running your first multi-agent workflow, with practical examples drawn from the repository's example implementations.

Prerequisites

Before beginning with Agency Swarm, ensure your development environment meets the following requirements:

Environment Setup

Cloning the Repository

Begin by cloning the Agency Swarm repository to your local machine:

git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm

Sources: CONTRIBUTING.md

Creating a Virtual Environment

Creating an isolated Python environment is recommended to avoid dependency conflicts:

python3 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

Sources: CONTRIBUTING.md

Installing Dependencies

Agency Swarm uses a Makefile for dependency management. Install all required packages with the sync command:

make sync

This command installs both runtime and development dependencies, including pre-commit hooks for code quality checks. To also install pre-commit hooks manually:

pip install pre-commit
pre-commit install

Sources: CONTRIBUTING.md

Project Structure

Understanding the Agency Swarm directory structure is essential for effective development:

graph TD
    A[agency-swarm Root] --> B[examples/]
    A --> C[src/agency_swarm/]
    A --> D[agency_swarm/]
    
    B --> B1[Core Examples]
    B --> B2[interactive/]
    B --> B3[fastapi_integration/]
    
    C --> C1[agent/]
    C --> C2[tools/]
    C --> C3[cli/]
    C --> C4[ui/]
    
    D --> D1[agents/]
    D --> D2[tools/]

Key Directories

Recommended Agent Folder Structure

Each agent should follow a consistent folder structure:

AgentName/
├── files/                  # Files to be uploaded to OpenAI
├── schemas/                # OpenAPI schemas for tool generation
├── tools/                  # Agent-specific tool definitions
├── AgentName.py            # Main agent class
├── __init__.py             # Package initialization
└── instructions.md         # Agent instruction document

Sources: README.md

Creating Your First Agent

Using the CLI Template Generator

Agency Swarm provides a CLI command to scaffold agent templates automatically:

agency-swarm create-agent AgentName --model gpt-5.4-mini

The CLI supports the following parameters:

Sources: src/agency_swarm/cli/main.py

Manual Agent Definition

Alternatively, define agents programmatically using the Agent class:

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.",
    files_folder="./files",
    schemas_folder="./schemas",
    tools=[my_custom_tool],
    model="gpt-5.4-mini",
    model_settings=ModelSettings(
        max_tokens=25000,
    ),
)

Sources: README.md

Defining Tools

Agency Swarm supports multiple tool definition patterns.

Function Tool with Decorator

The simplest approach uses the @function_tool decorator:

from agency_swarm import function_tool

@function_tool
def calculate(a: int, b: int) -> int:
    """A brief description of what the custom tool does."""
    return a + b

Sources: examples/tools.py

BaseTool Class

For more complex tools with validation, use the BaseTool class:

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

    example_field: str = Field(
        ..., description="Description of the example field"
    )

    def run(self):
        return "Result of MyCustomTool operation"

Sources: README.md

OpenAPI Schema to Tools

Convert existing OpenAPI schemas into Agency Swarm tools:

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 remote URL
import requests
tools = ToolFactory.from_openapi_schema(
    requests.get("https://api.example.com/openapi.json").json()
)

Sources: README.md

Building Multi-Agent Workflows

Defining Communication Flows

Agents communicate through defined flows using SendMessage and Handoff:

from agency_swarm import Agency, Agent, SendMessage, Handoff

ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)
manager = Agent(name="Manager", ...)

agency = Agency(
    ceo,  # Entry point agent
    communication_flows=[
        (ceo > developer, SendMessage),  # CEO sends to Developer
        (developer < manager),           # Bidirectional with handoff
        (developer > ceo, Handoff),      # Developer hands off to CEO
    ]
)

Sources: examples/multi_agent_workflow.py

Communication Flow Syntax

Running the Agency

Execute the agency asynchronously:

import asyncio

async def main():
    resp = await agency.get_response("Create a project skeleton.")
    print(resp.final_output)

asyncio.run(main())

For synchronous execution:

resp = agency.get_response_sync("Create a project skeleton.")

Sources: README.md

Running Examples

The repository includes numerous runnable examples demonstrating key features:

Available Example Scripts

Sources: examples/README.md

Running an Example

Navigate to the examples directory and run any example script:

cd examples
python multi_agent_workflow.py

Interactive Interfaces

Agency Swarm provides multiple interactive UI options.

Terminal UI

The terminal UI provides a chat interface in the terminal:

from agency_swarm import Agency

agency = create_demo_agency()
agency.tui(show_reasoning=True)

Sources: examples/interactive/tui.py

Agency Visualization

Generate interactive HTML visualizations of your agency structure:

from agency_swarm import Agency

agency = create_demo_agency()
html_file = agency.visualize(
    output_file="agency.html",
    include_tools=True,
    open_browser=True,
)

Sources: examples/agency_visualization.py

Testing

Run the test suite to ensure your implementation works correctly:

make coverage

The coverage command runs pytest with coverage reporting. Review the output to ensure adequate test coverage for your changes.

Sources: CONTRIBUTING.md

Additional Resources

Cursor IDE Integration

For enhanced development with AI coding assistants, use the .cursorrules file at the repository root. See the Cursor IDE guide at https://agency-swarm.ai/welcome/getting-started/cursor-ide for detailed setup instructions.

FastAPI Integration

Agency Swarm supports FastAPI integration for serving agents as REST endpoints:

cd examples/fastapi_integration
python server.py

This exposes endpoints for streaming responses and agency metadata. See the examples/fastapi_integration/README.md for complete documentation.

CLI Commands Reference

Sources: src/agency_swarm/cli/main.py

Next Steps

After completing this guide, consider exploring:

1. Advanced Communication Patterns - Study examples/interactive/hybrid_communication_flows.py for complex agent interaction patterns
2. Custom Tool Development - Create domain-specific tools following the patterns in examples/tools.py
3. Persistence - Implement chat history persistence using examples/custom_persistence.py
4. Guardrails - Add input/output validation as demonstrated in examples/guardrails.py

For comprehensive documentation, visit https://agency-swarm.ai/welcome/getting-started/from-scratch for the full tutorial.

Related Pages

Related topics: Introduction to Agency Swarm, Agent Internals, Communication Flows

Core Architecture

Agency Swarm is a multi-agent framework built on OpenAI's Agents SDK that enables the creation of collaborative AI agent systems. The core architecture comprises three fundamental layers: the Agency Layer, the Agent Layer, and the Communication Layer. This document provides an in-depth analysis of how these components interact to form a cohesive multi-agent system.

Architecture Overview

The framework follows a hierarchical design where the Agency serves as the top-level orchestrator, managing multiple Agents that collaborate through well-defined communication channels.

graph TB
    subgraph Agency["Agency Layer"]
        A[Agency]
        AC[AgencyContext]
        AF[Communication Flows]
    end
    
    subgraph Agent["Agent Layer"]
        AG1[Agent Instance]
        AG2[Agent Instance]
        AGn[Agent Instance]
    end
    
    subgraph Tools["Tool Layer"]
        BT[BaseTool]
        FT[FunctionTool]
        TF[ToolFactory]
    end
    
    subgraph Model["Model Layer"]
        MS[ModelSettings]
        RM[Reasoning Models]
    end
    
    A --> AG1
    A --> AG2
    A --> AGn
    A --> AC
    A --> AF
    
    AG1 --> BT
    AG2 --> FT
    AGn --> TF
    
    AG1 --> MS
    AG2 --> RM

The Agency Layer

Purpose and Role

The Agency acts as the central coordinator for all agents within the system. It manages agent initialization, communication routing, shared context distribution, and the overall execution flow.

Sources: examples/README.md:1-30

Agency Initialization

The Agency is initialized with a collection of agents and optional communication flows:

from agency_swarm import Agency, Agent

support = Agent(name="SupportAgent", ...)
math = Agent(name="MathAgent", ...)

agency = Agency(
    support,
    math,
    communication_flows=[(support, math, Handoff)],
    shared_instructions="Demonstrate reasoning, web search, file search, and handoffs.",
    name="DemoAgency"
)

Sources: examples/interactive/tui.py:40-68

Key Agency Components

The Agent Layer

Agent Class Structure

The Agent class is the fundamental building block of Agency Swarm. Each agent encapsulates a specific role, set of tools, instructions, and model configuration.

Sources: src/agency_swarm/agent/core.py:1-100

Agent Initialization Parameters

Sources: src/agency_swarm/agent/core.py:50-150

Tool Loading Mechanism

Agents support three distinct tool loading mechanisms:

def _load_tools_from_folder(self) -> None:
    """Load tools defined in ``tools_folder`` and add them to the agent.

    Supports both ``BaseTool`` subclasses and ``FunctionTool``
    instances created via the ``@function_tool`` decorator.
    """
    load_tools_from_folder(self)

Sources: src/agency_swarm/agent/core.py:120-130

OpenAPI Schema Parsing

Agents can automatically convert OpenAPI schemas into usable tools:

def _parse_schemas(self):
    """Parse OpenAPI schemas from the schemas folder and create tools."""
    parse_schemas(self)

Sources: src/agency_swarm/agent/core.py:135-140

Communication Architecture

Agent-to-Agent Communication

Agents communicate through two primary mechanisms:

1. Direct Messaging (SendMessage)
2. Handoffs - Transfer of control between agents

from agency_swarm import Handoff

agency = Agency(
    support,
    math,
    communication_flows=[(support, math, Handoff)],
)

Sources: examples/interactive/tui.py:55-57

Communication Flow Definition

Communication flows are defined as a list of tuples specifying source agent, target agent, and the communication type:

communication_flows=[
    (agent_a, agent_b, Handoff),
    (agent_b, agent_c, SendMessage),
]

Execution Flow

The get_response Method

The primary method for agent execution is get_response, which handles both user and agent-to-agent interactions:

async def get_response(
    self,
    message: str | list[TResponseInputItem],
    sender_name: str | None = None,
    context_override: dict[str, Any] | None = None,
    hooks_override: RunHooks | None = None,
    run_config_override: RunConfig | None = None,
    file_ids: list[str] | None = None,
    additional_instructions: str | None = None,
    agency_context: AgencyContext | None = None,
    **kwargs: Any,
) -> RunResult:

Sources: src/agency_swarm/agent/core.py:150-200

Synchronous Execution

For synchronous use cases, get_response_sync provides a blocking interface:

resp = agency.get_response_sync("What's your name?")

Streaming Responses

The framework supports real-time streaming for interactive applications:

# See streaming.py in examples

Sources: examples/README.md:8

Model Configuration

ModelSettings

Model configuration is handled through the ModelSettings class:

from agency_swarm import ModelSettings, Reasoning

model_settings=ModelSettings(
    temperature=0.3,
    top_p=0.9,
    max_tokens=25000,
    reasoning=Reasoning(effort="high", summary="auto")
)

Sources: src/agency_swarm/cli/utils/generate-agent-from-settings.ts:50-80

Reasoning Models

The framework supports OpenAI's reasoning models with special configuration:

def is_reasoning_model(model: str) -> bool:
    """Check if the model is a reasoning model."""
    # Reasoning models do not support temperature parameter

Sources: src/agency_swarm/utils/create_agent_template.py:10-25

ModelSettings Parameters

File Management

Vector Store Integration

Agents can upload files to OpenAI's vector stores for semantic search:

def upload_file(self, file_path: str, include_in_vector_store: bool = True) -> str:
    """Upload a file using the agent's file manager."""
    if self.file_manager:
        return self.file_manager.upload_file(file_path, include_in_vector_store)
    raise RuntimeError(f"Agent {self.name} has no file manager configured")

Sources: src/agency_swarm/agent/core.py:145-152

File Search Tool Configuration

The FileSearchTool can be configured with vector store IDs:

toolImports.push("FileSearchTool");
configParts.push(`vector_store_ids=[${vectorStoreIds}]`);

Sources: src/agency_swarm/cli/utils/generate-agent-from-settings.ts:100-120

Tool System Architecture

Tool Types

BaseTool Implementation

from agency_swarm.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    example_field: str = Field(
        ..., description="Description of the example field"
    )

    def run(self):
        return f"Result: {self.example_field}"

Sources: README.md:100-130

ToolFactory for OpenAPI Schemas

from agency_swarm.tools import ToolFactory

tools = ToolFactory.from_openapi_schema(
    openapi_schema_json  # Can be dict or loaded from file
)

Agent Flow State Machine

The agent_flow.py module manages the state transitions within an agent's execution cycle:

graph LR
    A[Init] --> B[Process Input]
    B --> C{Tool Call?}
    C -->|Yes| D[Execute Tool]
    D --> B
    C -->|No| E[Generate Response]
    E --> F[Check Handoff]
    F -->|Yes| G[Transfer Control]
    G --> H[End]
    F -->|No| I[Final Output]
    I --> H

Sources: src/agency_swarm/agent/agent_flow.py:1-50

CLI and Template Generation

Agent Template Creation

The CLI provides utilities for generating agent templates with validation:

def create_agent_template(
    agent_name=None,
    agent_description=None,
    model="gpt-5.4",
    reasoning=None,
    max_tokens=None,
    temperature=None,
    path="./",
    instructions=None,
    use_txt=False,
    include_example_tool=True,
) -> bool:

Sources: src/agency_swarm/utils/create_agent_template.py:15-40

Input Validation

The framework validates agent names and parameters:

def _validate_agent_name(agent_name):
    """Validate agent name follows CamelCase convention."""

def _validate_temperature(temperature):
    """Validate temperature is within valid range (0-2)."""

Sources: src/agency_swarm/utils/create_agent_template.py:40-70

Recommended Folder Structure

agency_project/
├── agency_manifesto.md        # Agency's guiding principles
└── AgentName/
    ├── files/                  # Files for vector store upload
    ├── schemas/                # OpenAPI schemas for tools
    ├── tools/                  # Custom tool modules
    ├── AgentName.py            # Agent class definition
    ├── __init__.py             # Package initialization
    └── instructions.md         # Agent instructions

Sources: README.md:60-80

Programmatic Usage Patterns

Async Execution

import asyncio

async def main():
    resp = await agency.get_response("Create a project skeleton.")
    print(resp.final_output)

asyncio.run(main())

Sync Execution

resp = agency.get_response_sync("What's your name?")

Summary

The Agency Swarm core architecture consists of three interdependent layers:

1. Agency Layer: Orchestrates multiple agents, manages communication flows, and maintains shared context
2. Agent Layer: Encapsulates individual agent capabilities including tools, instructions, and model configurations
3. Communication Layer: Enables agent-to-agent messaging and handoff mechanisms

The architecture follows a modular design pattern where tools, models, and communication mechanisms can be independently configured and composed to create complex multi-agent workflows.

Related Pages

Related topics: Core Architecture, Tools System

Agent Internals

Overview

The Agent is the fundamental execution unit in Agency Swarm. It represents an autonomous entity capable of processing messages, executing tools, and communicating with other agents within an agency. Agents are built on OpenAI's Responses API and encapsulate configuration for model selection, tool definitions, file management, and communication protocols.

Agents serve as the building blocks for multi-agent systems, enabling complex workflows where specialized agents collaborate through defined communication flows. Each agent maintains its own state, toolset, and instruction set while participating in the broader agency ecosystem.

Sources: src/agency_swarm/agent/core.py:1-50

Architecture Overview

The Agent module is organized into several interconnected components that handle different aspects of agent behavior:

graph TD
    A[Agent] --> B[Initialization]
    A --> C[Core Execution]
    A --> D[Tools Management]
    A --> E[Guardrails]
    
    B --> B1[__init__]
    B --> B2[_init_files]
    B --> B3[_load_tools_from_folder]
    B --> B4[_parse_schemas]
    
    C --> C1[get_response]
    C --> C2[Run Hooks]
    C --> C3[Run Config]
    
    D --> D1[BaseTool]
    D --> D2[FunctionTool]
    D --> D3[ToolFactory]
    
    E --> E1[Input Guardrails]
    E --> E2[Output Guardrails]

Core Components

Sources: src/agency_swarm/agent/core.py:1-30

Agent Initialization

Constructor Parameters

The Agent class accepts the following core parameters during initialization:

Sources: src/agency_swarm/agent/core.py:50-120

Initialization Flow

sequenceDiagram
    participant User
    participant Agent
    participant FileManager
    participant ToolLoader
    participant SchemaParser
    
    User->>Agent: __init__(params)
    Agent->>Agent: _validate_params()
    Agent->>FileManager: _init_files()
    Agent->>ToolLoader: _load_tools_from_folder()
    Agent->>SchemaParser: _parse_schemas()
    Agent-->>User: Agent instance

The initialization process follows these steps:

1. Parameter Validation: All required parameters are validated
2. File Manager Setup: Files in files_folder are prepared for upload
3. Tool Loading: Tools are loaded from both the tools parameter and tools_folder
4. Schema Parsing: OpenAPI schemas in schemas_folder are converted to tools

Sources: src/agency_swarm/agent/initialization.py:1-80

Model Configuration

Agents support various OpenAI models with appropriate default settings:

# Reasoning models (e.g., o3, o4-mini) - no temperature
model="gpt-5.4"
model_settings=ModelSettings(
    reasoning=Reasoning(effort="medium")
)

# Non-reasoning models - temperature defaults to 0.3
model="gpt-4o"
model_settings=ModelSettings(
    temperature=0.3,
    max_tokens=25000
)

Sources: src/agency_swarm/utils/create_agent_template.py:40-70

Tools Management

Tool Types

The framework supports two primary tool paradigms:

BaseTool Implementation

BaseTool subclasses must implement the following interface:

from agency_swarm.tools import BaseTool

class MyTool(BaseTool):
    name: str = "my_tool"
    description: str = "Description of what the tool does"
    
    def run(self) -> str:
        """Execute the tool's primary function."""
        return "result"

Sources: src/agency_swarm/agent/tools.py:1-50

FunctionTool Decorator

For simpler use cases, the @function_tool decorator wraps regular Python functions:

from agency_swarm import function_tool

@function_tool
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))

Tool Loading from Folder

The _load_tools_from_folder() method dynamically imports tools from a directory structure:

AgentName/tools/
├── __init__.py
├── MyTool.py
└── AnotherTool.py

The loader:

• Scans the folder for Python files
• Imports classes inheriting from BaseTool
• Includes FunctionTool instances defined in __init__.py
• Adds all discovered tools to the agent's toolset

Sources: src/agency_swarm/agent/core.py:100-120

OpenAPI Schema Parsing

Agents can automatically convert OpenAPI schemas into callable tools:

from agency_swarm.tools import ToolFactory

# From file
tools = ToolFactory.from_openapi_schema(
    openapi_schema=json.load(open("schema.json"))
)

# From URL
tools = ToolFactory.from_openapi_schema(
    requests.get("https://api.example.com/openapi.json").json()
)

The _parse_schemas() method processes schemas from schemas_folder and creates corresponding tools.

Sources: README.md:50-80

Execution Flow

Core Execution Method

The get_response() method is the primary interface for agent execution:

graph LR
    A[Message Input] --> B[Context Override]
    B --> C[Run Hooks]
    C --> D[OpenAI API Call]
    D --> E[Tool Execution]
    E --> D
    D --> F[Output Processing]
    F --> G[Response Format]
    G --> H[RunResult]

Method Signature

async def get_response(
    self,
    message: str | list[TResponseInputItem],
    sender_name: str | None = None,
    context_override: dict[str, Any] | None = None,
    hooks_override: RunHooks | None = None,
    run_config_override: RunConfig | None = None,
    file_ids: list[str] | None = None,
    additional_instructions: str | None = None,
    agency_context: AgencyContext | None = None,
    **kwargs: Any,
) -> RunResult

Parameters

Sources: src/agency_swarm/agent/core.py:150-200

Run Result

The execution returns a RunResult object containing:

• messages: Conversation history
• final_output: Text response from the model
• tool_calls: List of tool invocations made
• usage: Token and cost information

Execution Guardrails

Guardrails provide validation hooks at the input and output boundaries of agent execution.

Guardrail Interface

class BaseExecutionGuardrail(ABC):
    @abstractmethod
    async def validate(
        self,
        agent: Agent,
        messages: list[Message],
    ) -> tuple[bool, str | None]:
        """Validate input or output. Returns (passed, error_message)."""
        pass

Guardrail Pipeline

graph TD
    A[Input Messages] --> B[Input Guardrails]
    B -->|pass| C[Execute Agent]
    B -->|fail| D[Return Error]
    C --> E[Output Processing]
    E --> F[Output Guardrails]
    F -->|pass| G[Return Result]
    F -->|fail| D
    
    style D fill:#ff6b6b
    style G fill:#51cf66

Configuration

Guardrails are configured per-agent:

from agency_swarm.agent import Agent, InputGuardrail, OutputGuardrail

agent = Agent(
    name="SecureAgent",
    instructions="...",
    input_guardrails=[MyInputGuardrail()],
    output_guardrails=[MyOutputGuardrail()],
)

Sources: src/agency_swarm/agent/execution_guardrails.py:1-60

File Handling

File Manager Integration

Agents can manage files for upload to OpenAI's vector stores:

agent = Agent(
    name="Researcher",
    instructions="...",
    files_folder="./files",
)

Upload Method

def upload_file(
    self,
    file_path: str,
    include_in_vector_store: bool = True
) -> str:
    """Upload a file using the agent's file manager.
    
    Returns:
        str: The uploaded file ID
    """
    if self.file_manager:
        return self.file_manager.upload_file(
            file_path,
            include_in_vector_store
        )
    raise RuntimeError(f"Agent {self.name} has no file manager configured")

Sources: src/agency_swarm/agent/core.py:130-145

Communication Patterns

Agent-to-Agent Messaging

Agents communicate through defined flows using specialized message tools:

from agency_swarm import Agency, Agent, SendMessage, Handoff

ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)

agency = Agency(
    ceo,
    developer,
    communication_flows=[
        (ceo > developer, SendMessage),  # CEO sends to Developer
        (developer > ceo, Handoff),       # Developer returns to CEO
    ]
)

Message Types

Model Settings

The ModelSettings class configures LLM behavior:

from agency_swarm import Agent, ModelSettings, Reasoning

agent = Agent(
    name="Analyzer",
    model="gpt-5.4-mini",
    model_settings=ModelSettings(
        temperature=0.3,
        max_tokens=25000,
        reasoning=Reasoning(effort="high", summary="auto"),
        top_p=0.9,
    ),
)

Settings Parameters

Sources: src/agency_swarm/cli/utils/generate-agent-from-settings.ts:60-100

State Management

Agency Context

Agents can share state through the AgencyContext:

async def get_response(
    self,
    message: str,
    context_override: dict[str, Any] | None = None,
    agency_context: AgencyContext | None = None,
    ...
) -> RunResult:
    # Access shared context
    if agency_context:
        shared_data = agency_context.get("key")

Message History

Agents maintain conversation history through RunResult:

result = await agent.get_response("Hello")
for message in result.messages:
    print(f"{message.role}: {message.content}")

CLI Integration

Agent Template Creation

The CLI provides utilities for generating agent templates:

agency-swarm create-agent-template "Data Analyst" \
    --description "Performs data analysis" \
    --model "gpt-5.4-mini" \
    --reasoning "medium" \
    --temperature 0.3

This generates the standard folder structure:

DataAnalyst/
├── DataAnalyst.py
├── __init__.py
├── instructions.md
├── files/
├── schemas/
└── tools/

Sources: src/agency_swarm/cli/main.py:30-80

Summary

The Agent Internals architecture demonstrates a modular design where:

1. Initialization handles setup of files, tools, and schemas
2. Tools Management provides flexible tool creation and loading
3. Execution manages the runtime loop with hooks and guardrails
4. Communication enables multi-agent collaboration through defined flows
5. Configuration supports various models with appropriate defaults

This architecture allows agents to serve as self-contained, configurable units that can participate in complex multi-agent workflows while maintaining clear separation of concerns.

Related Pages

Related topics: Getting Started Guide, Agent Internals, Communication Flows

Tools System

Overview

The Tools System in Agency Swarm provides a flexible mechanism for extending agent capabilities through custom tool implementations. Agents can use tools to interact with external services, execute code, run shell commands, search the web, and perform various other tasks that extend beyond natural language processing.

Tools in Agency Swarm serve as the primary interface between agents and external functionality. They enable agents to:

• Execute Python code in isolated environments
• Run persistent shell commands
• Search the web for information
• Process and analyze files
• Interact with external APIs via OpenAPI schemas

The system supports two primary tool creation patterns: inheriting from BaseTool class and using the @function_tool decorator. Additionally, tools can be auto-generated from OpenAPI schemas using ToolFactory.

Architecture

graph TD
    A[Agent] --> B[Tools System]
    B --> C[BaseTool Subclass]
    B --> D[@function_tool Decorator]
    B --> E[ToolFactory]
    C --> F[IPythonInterpreter]
    C --> G[PersistentShellTool]
    C --> H[Custom Tool]
    E --> I[OpenAPI Schema]
    F --> J[Code Execution Environment]
    G --> K[Shell Session]

Core Components

BaseTool Class

The BaseTool class is the foundation for all tools in Agency Swarm. It provides a standardized interface for tool definition and execution.

File: src/agency_swarm/tools/base_tool.py

Key Responsibilities:

• Define tool schema for OpenAI API compatibility
• Validate input parameters using Pydantic
• Execute the tool's core functionality via run() method
• Support async execution when needed

Structure:

ToolFactory

The ToolFactory class enables automatic generation of tools from OpenAPI schemas. This allows integration with existing REST APIs without manual tool implementation.

File: src/agency_swarm/tools/tool_factory.py

Usage Pattern:

from agency_swarm.tools import ToolFactory

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

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

Built-in Tools

Agency Swarm includes several pre-built tools for common use cases.

#### IPythonInterpreter

File: src/agency_swarm/tools/built_in/IPythonInterpreter.py

Provides Python code execution capabilities within an agency. Key features:

• Executes Python code in a persistent environment
• Maintains state between executions
• Supports file operations and data processing
• Integrates with agent workflows for data analysis tasks

Configuration Parameters:

#### PersistentShellTool

File: src/agency_swarm/tools/built_in/PersistentShellTool.py

Provides persistent shell command execution. Unlike one-off command runners, this tool maintains an active shell session across multiple tool calls.

Features:

• Persistent shell state between commands
• Environment variable preservation
• Working directory consistency
• Command history tracking

Function Tool Decorator

The @function_tool decorator provides a lightweight alternative to BaseTool subclassing. It's ideal for simpler tools that don't require extensive configuration.

Pattern:

from agency_swarm.tools import function_tool
from pydantic import Field

@function_tool
def calculate(a: float, b: float, operation: str = Field(
    description="Operation to perform: add, subtract, multiply, divide"
)) -> str:
    """Perform basic arithmetic operations."""
    if operation == "add":
        return str(a + b)
    elif operation == "subtract":
        return str(a - b)
    elif operation == "multiply":
        return str(a * b)
    elif operation == "divide":
        if b == 0:
            return "Error: Division by zero"
        return str(a / b)
    return "Unknown operation"

Creating Custom Tools

Method 1: Using BaseTool Class

For complex tools requiring detailed configuration:

from agency_swarm.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    """
    A brief description of what the custom tool does.
    The docstring is used by the agent to determine when to use this tool.
    """
    
    # Define fields with descriptions using Pydantic Field
    example_field: str = Field(
        ..., description="Description of the example field explaining its purpose"
    )
    
    def run(self):
        """
        The implementation of the run method.
        """
        # Tool logic here
        return f"Result: {self.example_field}"

Method 2: Using @function_tool Decorator

For simpler tools:

from agency_swarm.tools import function_tool

@function_tool
def my_simple_tool(input_text: str) -> str:
    """Process input text and return result."""
    return input_text.upper()

Method 3: From OpenAPI Schema

For API integration:

from agency_swarm.tools import ToolFactory

# Generate tools from OpenAPI specification
tools = ToolFactory.from_openapi_schema(openapi_schema_dict)

# tools is a list of BaseTool instances
for tool in tools:
    print(tool.name, tool.description)

Tool Integration with Agents

Adding Tools to Agents

Tools are passed to agents via the tools parameter during initialization:

from agency_swarm import Agent
from agency_swarm.tools import BaseTool, function_tool

# Custom tool class
class DataProcessor(BaseTool):
    name: str = "DataProcessor"
    description: str = "Processes data according to specified rules"
    
    data: str = Field(description="Data to process")
    rule: str = Field(description="Processing rule to apply")
    
    def run(self):
        return f"Processed {self.data} with rule {self.rule}"

# Function tool
@function_tool
def calculator(a: float, b: float) -> float:
    return a + b

# Create agent with tools
agent = Agent(
    name="DataAgent",
    description="Handles data processing tasks",
    tools=[DataProcessor, calculator]
)

Tool Discovery from Folders

Agents can automatically discover and load tools from a specified directory:

agent = Agent(
    name="FileAgent",
    description="Handles file operations",
    tools_folder="./tools"  # Auto-loads all tools from this directory
)

This approach scans the specified folder for tool definitions and makes them available to the agent without explicit listing.

Tool Schema Generation

Each tool automatically generates an OpenAI-compatible schema used for function calling:

graph LR
    A[Tool Definition] --> B[Schema Generator]
    B --> C[OpenAI Tool Schema]
    C --> D[Agent System Prompt]
    D --> E[Model Function Calling]

Schema Structure:

{
  "type": "function",
  "function": {
    "name": "tool_name",
    "description": "Tool description",
    "parameters": {
      "type": "object",
      "properties": {...},
      "required": [...]
    }
  }
}

Tool Execution Flow

sequenceDiagram
    participant Agent
    participant Tool as Tool Instance
    participant Runtime as Tool Runtime
    
    Agent->>Tool: Calls tool with parameters
    Tool->>Tool: Validate parameters (Pydantic)
    Tool->>Runtime: Execute run() method
    Runtime-->>Tool: Return result
    Tool-->>Agent: Return tool result
    
    Note over Agent,Tool: Tool can be sync or async

Testing Tools

Tools should include comprehensive test coverage. Tests are located in agency_swarm/tests/test_tools.py.

Test Template:

def test_my_tool_example():
    tool = MyCustomTool(example_field="test value")
    result = tool.run()
    assert "expected output" in result

Running Tool Tests:

make coverage

CLI Tool Import

Agency Swarm CLI provides built-in tool import functionality:

# List available built-in tools
agency-swarm import-tool --list

# Import a specific tool
agency-swarm import-tool IPythonInterpreter --directory ./my_tools

This command copies the selected tool's source files into the specified directory, allowing for customization.

Best Practices

1. Clear Descriptions: Use descriptive docstrings that explain when and why the agent should use the tool
2. Field Documentation: Every parameter field should have a clear description for agent understanding
3. Error Handling: Implement proper error handling in the run() method
4. Type Safety: Use Pydantic models for all parameters to ensure validation
5. Idempotency: Design tools to be safely re-executable when possible
6. Resource Management: Clean up resources (files, connections) after execution

File Structure

agency_swarm/tools/
├── __init__.py           # Public exports
├── base_tool.py          # BaseTool class definition
├── tool_factory.py       # ToolFactory for OpenAPI schemas
├── function_tool.py      # @function_tool decorator
└── built_in/             # Pre-built tool implementations
    ├── IPythonInterpreter.py
    ├── PersistentShellTool.py
    └── ...

Summary

The Tools System provides a comprehensive framework for extending agent capabilities in Agency Swarm. With support for custom tool creation, OpenAPI schema integration, and built-in tools for common tasks, developers can flexibly enhance their agents' functionality. The system leverages Pydantic for robust parameter validation and follows consistent patterns that make tool development straightforward and maintainable.

Related Pages

Related topics: Core Architecture, Tools System, Messaging System

Communication Flows

Overview

Communication Flows define how agents interact with each other within an Agency. They establish the rules and pathways for agent-to-agent messaging, control transfers, and collaborative workflows. This system enables multi-agent collaboration by specifying which agents can communicate, through what mechanisms, and in what directions.

Communication Flows are a core architectural component of agency-swarm that transforms a collection of individual agents into a coordinated multi-agent system. Without explicit communication flows, agents cannot interact with each other—they can only respond to direct user input.

Core Concepts

Agent Communication Patterns

Agency-swarm supports two primary communication mechanisms:

Flow Directionality

Communication flows are directional, meaning you can specify asymmetric communication patterns:

• Unidirectional: Agent A can send messages to Agent B, but not vice versa
• Bidirectional: Agents can communicate in both directions
• Broadcast-capable: Certain patterns allow multi-recipient messaging

Architecture

Flow Processing Pipeline

graph TD
    A[User Input] --> B[Entry Point Agent]
    B --> C{Communication Flow Check}
    C -->|SendMessage| D[SendMessage Tool Execution]
    C -->|Handoff| E[Handoff Tool Execution]
    D --> F[Recipient Agent Processing]
    E --> G[Control Transfer to Recipient]
    F --> H{More Flows?}
    G --> H
    H -->|Yes| C
    H -->|No| I[Final Response]

Flow Definition in Agency Class

The Agency class in src/agency_swarm/agency/core.py manages communication flows through the communication_flows parameter:

Agency(
    agents,
    communication_flows=[...],
    shared_instructions="...",
    send_message_tool_class=SendMessage
)

Sources: examples/agency_visualization.py:25-35

Flow Tuple Structure

Communication flows are defined as tuples with the following structure:

communication_flows=[
    (agent_a > agent_b),           # Simple unidirectional
    (agent_c < agent_d),           # Reverse direction
    (agent_e > agent_f, Handoff),  # With specific tool class
    (agent_g < agent_h > agent_i), # Multi-agent chain
]

Configuration Options

Basic Flow Definition

Simple directional flows use the default SendMessage tool:

from agency_swarm import Agent, Agency

ceo = Agent(name="CEO", instructions="Manage the workflow")
developer = Agent(name="Developer", instructions="Write code")

agency = Agency(
    ceo,
    developer,
    communication_flows=[
        (ceo > developer),  # CEO can delegate to Developer
        (developer > ceo),  # Developer can report back to CEO
    ]
)

Handoff-Based Flows

Handoffs transfer conversational control to another agent:

from agency_swarm.tools import Handoff

support = Agent(name="Support", instructions="Handle basic queries")
specialist = Agent(name="Specialist", instructions="Handle complex issues")

agency = Agency(
    support,
    specialist,
    communication_flows=[
        (support > specialist, Handoff),  # Support escalates to Specialist
    ]
)

Sources: examples/interactive/tui.py:48-52

Custom SendMessage Classes

For flows requiring additional context passing, use custom SendMessage classes:

from agency_swarm.tools import SendMessage
from agency_swarm import Agent, Agency

class SendMessageWithContext(SendMessage):
    """Custom SendMessage that includes context about key decisions."""
    pass

coordinator = Agent(name="Coordinator", instructions="Coordinate tasks")
specialist = Agent(name="Specialist", instructions="Execute specialized tasks")

agency = Agency(
    coordinator,
    specialist,
    communication_flows=[
        (coordinator > specialist, SendMessageWithContext),
        (specialist > coordinator, Handoff),
    ],
    shared_instructions="Use key decisions to guide analysis tool selection.",
    send_message_tool_class=SendMessageWithContext,
)

Sources: examples/custom_send_message.py:20-32

Multi-Agent Communication Chains

Complex workflows can involve multiple agents in a single flow definition:

dev = Agent(name="Developer", instructions="Write code")
qa = Agent(name="QA", instructions="Test code")
pm = Agent(name="PM", instructions="Manage project")

agency = Agency(
    dev,
    qa,
    pm,
    communication_flows=[
        (dev < ceo > pm > dev),  # Multi-agent chain with CEO
        (dev > qa, Handoff),     # Developer can hand off to QA
    ]
)

Sources: examples/agency_visualization.py:25-35

Flow Visualization

The Agency class provides visualization capabilities for communication flows:

html_file = agency.visualize(
    output_file="agency_interactive_demo.html",
    include_tools=True,
    open_browser=True,
)

This generates an interactive HTML visualization showing:

• Agent nodes and their connections
• Communication flow directions
• Tool availability per agent
• Entry point indicators

SendMessage Tool Reference

Parameters

Configuration via Agency

Set default behavior for all flows:

agency = Agency(
    agent_a,
    agent_b,
    communication_flows=[agent_a > agent_b],
    send_message_tool_class=CustomSendMessage,  # Default for all flows
)

Sources: src/agency_swarm/tools/send_message.py

Handoff Tool Reference

Behavior

When an agent executes a Handoff:

1. Current agent's response is terminated
2. Control transfers to the target agent
3. Original message context is preserved
4. Target agent receives the conversation state

Use Cases

Shared Instructions

Communication flows can leverage shared instructions for consistent behavior:

agency = Agency(
    coordinator,
    specialist,
    communication_flows=[coordinator > specialist],
    shared_instructions="All agents should use key decisions to guide their actions.",
)

Shared instructions are available to all agents in the agency and provide context for communication decisions.

Best Practices

Flow Design Principles

1. Explicit Over Implicit: Always define flows explicitly rather than relying on defaults
2. Minimal Paths: Only create necessary communication pathways
3. Directional Clarity: Design flows with clear escalation paths
4. Context Preservation: Use custom SendMessage classes when context matters

Security Considerations

• Limit communication flows to only necessary agent pairs
• Use shared instructions to establish boundaries
• Review flow visualizations for unintended pathways

Performance

• Avoid circular flows without exit conditions
• Limit the depth of multi-agent chains
• Consider async patterns for long-running workflows

Example: Complete Multi-Agent Workflow

from agency_swarm import Agent, Agency
from agency_swarm.tools import SendMessage, Handoff

# Define agents
ceo = Agent(
    name="CEO",
    instructions="You manage the overall workflow and delegate tasks."
)
coordinator = Agent(
    name="Coordinator", 
    instructions="Coordinate between teams and track progress."
)
developer = Agent(
    name="Developer",
    instructions="Implement technical solutions."
)
qa = Agent(
    name="QA",
    instructions="Test and validate deliverables."
)

# Create agency with communication flows
agency = Agency(
    ceo,          # Entry point (positional argument)
    coordinator,
    developer,
    qa,
    communication_flows=[
        (ceo > coordinator),           # CEO delegates to Coordinator
        (coordinator > developer),     # Coordinator assigns to Developer
        (coordinator > qa),           # Coordinator assigns to QA
        (developer > qa, Handoff),     # Developer hands off to QA for testing
        (qa > coordinator),           # QA reports back to Coordinator
        (coordinator > ceo),           # Coordinator reports to CEO
    ],
    shared_instructions="Follow the standard workflow: develop, test, then report."
)

# Execute workflow
async def main():
    result = await agency.get_response("Start the Q4 optimization project.")
    print(result.final_output)

See Also

• Agent Documentation - Individual agent configuration
• Tools Reference - SendMessage and Handoff tools
• Agency Visualization - Interactive flow visualization
• FastAPI Integration - Deploying agencies with communication flows

Related Pages

Related topics: Core Architecture, Agent Internals, Messaging System

Context Management

Overview

Context Management in Agency Swarm refers to the mechanisms by which state, instructions, and runtime data are shared and propagated across agents within an agency. This system enables multi-agent collaboration by allowing agents to access shared information, communicate effectively, and maintain coherent workflows across complex task execution pipelines.

The context management architecture supports multiple layers of data sharing:

1. Agency-level shared instructions that apply to all agents
2. Per-agent instructions for role-specific guidance
3. Runtime context propagation through the AgencyContext type
4. Message context for passing additional data through communication flows

Sources: examples/agency_context.py Sources: examples/interactive/tui.py

Related Pages

Related topics: Communication Flows, Context Management

Messaging System

The Messaging System in Agency Swarm is a foundational layer responsible for handling all communication between agents, users, and external systems. It manages message formatting, filtering, sanitization, streaming, and conversion to ensure reliable and secure inter-agent communication.

Architecture Overview

The messaging system consists of several interconnected modules that process messages at different stages of agent execution.

graph TD
    A[User/Agent Input] --> B[Message Filter]
    B --> C[Response Input Sanitizer]
    C --> D[Message Formatter]
    D --> E[Agent Core]
    E --> F[Execution Streaming]
    F --> G[Output Messages]
    
    H[Tool Calls] --> D
    I[Guardrails] --> D

Core Components

Message Flow Pipeline

Messages traverse a multi-stage pipeline before reaching their destination. Each stage performs specific transformations or validations.

graph LR
    subgraph Input_Processing
        F1[Filter] --> F2[Sanitize] --> F3[Format]
    end
    
    subgraph Core_Processing
        F3 --> F4[Agent Execution]
    end
    
    subgraph Output_Processing
        F4 --> F5[Streaming Output]
    end

Stage 1: Message Filtering

The MessageFilter class provides initial validation and filtering capabilities for incoming messages. It ensures that messages meet basic structural requirements before further processing.

Sources: src/agency_swarm/messages/message_filter.py:1-50

Stage 2: Input Sanitization

The ResponseInputSanitizer module sanitizes user input to prevent injection attacks and ensure compatibility with the OpenAI API response format requirements.

# Sanitization removes or escapes potentially harmful content
sanitized_input = ResponseInputSanitizer.sanitize(raw_message)

Sources: src/agency_swarm/messages/response_input_sanitizer.py:1-30

Stage 3: Message Formatting

The MessageFormatter handles the final transformation of messages, adapting them for different contexts such as agent-to-agent communication, tool execution, or user display.

Sources: src/agency_swarm/messages/message_formatter.py:1-40

Streaming Execution

The streaming system provides real-time message delivery during agent execution, enabling responsive user experiences.

Streaming Architecture

graph TD
    A[get_response_stream] --> B[StreamingRunResponse]
    B --> C[Event Stream]
    C --> D[text/event-stream]
    D --> E[Client Application]
    
    F[RunResult] --> G[new_items]
    G --> H[message_history]
    H --> I[Final Output]

Streaming Methods

Sources: src/agency_swarm/agent/core.py:100-130

Streaming Configuration

The streaming system integrates with the execution layer to provide real-time updates:

def get_response_stream(
    self,
    message: str | list[TResponseInputItem],
    sender_name: str | None = None,
    context_override: dict[str, Any] | None = None,
    hooks_override: RunHooks | None = None,
    run_config_override: RunConfig | None = None,
    file_ids: list[str] | None = None,
    additional_instructions: str | None = None,
    agency_context: AgencyContext | None = None,
    **kwargs: Any,
) -> StreamingRunResponse:

Sources: src/agency_swarm/agent/core.py:130-160

Message Conversion

The system includes utilities for converting between different message formats, particularly between internal RunItem objects and OpenAI-compatible TResponseInputItem format.

RunItem to TResponseInputItem Conversion

graph TD
    A[RunItem] --> B[run_item_to_tresponse_input_item]
    B --> C{TResponseInputItem}
    
    C --> D[message]
    C --> E[image_url]
    C --> F[tool_call]
    C --> E[tool_result]

The conversion function uses the SDK's built-in conversion method:

def run_item_to_tresponse_input_item(item: RunItem) -> TResponseInputItem | None:
    try:
        converted_item = item.to_input_item()
        return converted_item
    except Exception as e:
        logger.warning(f"Failed to convert {type(item).__name__}")
        return None

Sources: src/agency_swarm/agent/execution_helpers.py:80-100

Message Types and Structures

TResponseInputItem Format

The system uses TResponseInputItem for message representation, supporting multiple content types:

RunResult Structure

Sources: src/agency_swarm/agent/execution_helpers.py:50-75

Context Management

AgencyContext

The AgencyContext provides shared context for message processing across agents:

graph TD
    A[AgencyContext] --> B[Shared State]
    A --> C[Agent Registry]
    A --> D[Communication Flows]
    A --> E[Message History]

Context is automatically created for standalone agent usage:

if agency_context is None:
    agency_context = self._create_minimal_context()

Sources: src/agency_swarm/agent/core.py:85-95

Integration with Agent Execution

Execution Flow

sequenceDiagram
    participant User
    participant Agent
    participant MessageSystem
    participant OpenAI_API
    
    User->>Agent: get_response(message)
    Agent->>MessageSystem: Filter & Sanitize
    MessageSystem->>MessageSystem: Format
    Agent->>OpenAI_API: Run Request
    OpenAI_API-->>Agent: Streaming Events
    Agent->>MessageSystem: Convert RunItem
    MessageSystem->>User: Final Output

Method Signatures

Async Response Method:

async def get_response(
    self,
    message: str | list[TResponseInputItem],
    sender_name: str | None = None,
    context_override: dict[str, Any] | None = None,
    hooks_override: RunHooks | None = None,
    run_config_override: RunConfig | None = None,
    file_ids: list[str] | None = None,
    additional_instructions: str | None = None,
    agency_context: AgencyContext | None = None,
    **kwargs: Any,
) -> RunResult:

Streaming Response Method:

def get_response_stream(
    self,
    message: str | list[TResponseInputItem],
    sender_name: str | None = None,
    context_override: dict[str, Any] | None = None,
    hooks_override: RunHooks | None = None,
    run_config_override: RunConfig | None = None,
    file_ids: list[str] | None = None,
    additional_instructions: str | None = None,
    agency_context: AgencyContext | None = None,
    **kwargs: Any,
) -> StreamingRunResponse:

Sources: src/agency_swarm/agent/core.py:95-160

Configuration Options

RunConfig Parameters

Message Filtering Options

Error Handling

The messaging system implements comprehensive error handling:

try:
    converted_item = item.to_input_item()
    logger.debug(f"Converting {type(item).__name__} using SDK to_input_item()")
    return converted_item
except Exception as e:
    logger.warning(f"Failed to convert {type(item).__name__}")
    return None

Sources: src/agency_swarm/agent/execution_helpers.py:85-95

Usage Examples

Basic Message Flow

from agency_swarm import Agent

agent = Agent(name="Assistant")

# Synchronous message
result = await agent.get_response("Hello, how are you?")
print(result.final_output)

# Streaming message
stream = agent.get_response_stream("Tell me a story")
for event in stream:
    print(event, end="", flush=True)

Tool Message Handling

# Tool results are automatically converted to message format
tool_result = {
    "tool_call_id": "call_abc123",
    "output": "File content here"
}
# Converted to TResponseInputItem automatically

Best Practices

1. Always provide agency_context when agents communicate within an agency
2. Use streaming for long-running operations to improve responsiveness
3. Implement guardrails for input/output validation at the message level
4. Monitor message size to prevent token limit issues
5. Handle conversion errors gracefully with fallback mechanisms

Related Pages

Related topics: Agent Internals, Tools System

File Management

Overview

File Management in Agency Swarm provides a comprehensive system for handling file uploads, vector store creation, file search capabilities, and message attachments across multi-agent workflows. The system enables agents to work with persistent file storage, search through uploaded documents, and exchange files as part of their communication protocols.

The file management architecture consists of three primary components that work together to provide seamless file handling: FileManager, FileSync, and AttachmentManager. Each serves a distinct role in the file lifecycle from upload through search and message integration.

Sources: examples/README.md

Core Components

FileManager

The FileManager class handles the core file operations for an agent, including uploading files to OpenAI's vector stores and managing file associations. It provides the primary interface for agents to work with persistent file storage.

Key Responsibilities:

• Upload files to OpenAI vector stores
• Associate files with specific agents
• Enable file search capabilities through vector store integration
• Manage file lifecycle within agent contexts

API Reference:

Sources: src/agency_swarm/agent/core.py:68-73

FileSync

FileSync manages the synchronization of files across agent instances, ensuring that file references remain consistent when agents share context or communicate. It handles the transfer and validation of file metadata between agents in an agency.

AttachmentManager

The AttachmentManager handles file attachments in messages, enabling agents to include files in their communications. This component supports multimodal outputs and file references within the message protocol.

Sources: examples/message_attachments.py

Architecture

graph TD
    subgraph "File Management Architecture"
        FM[FileManager] --> VS[Vector Store]
        FM --> A[Agent Instance]
        FS[FileSync] --> FM
        FS --> A2[Other Agents]
        AM[AttachmentManager] --> M[Messages]
        M --> A
        VS --> FSR[File Search Results]
    end
    
    subgraph "External Services"
        OpenAI[OpenAI API]
        OpenAI --> VS
        OpenAI --> M
    end

File Upload Workflow

Files can be uploaded to an agent's context using the upload_file method. The workflow follows a sequential process:

1. File is validated for existence and accessibility
2. File is uploaded to OpenAI's storage system
3. Optionally, file is indexed in a vector store for search
4. File reference is associated with the agent's session

# From agent instance
agent = Agent(name="DocumentProcessor", ...)

# Upload file and include in vector store for search
file_id = agent.upload_file(
    file_path="documents/report.pdf",
    include_in_vector_store=True
)

Sources: src/agency_swarm/agent/core.py:68-73

Vector Store Integration

Agency Swarm integrates with OpenAI's File Search tool through vector store creation. This enables agents to semantic search through uploaded documents.

from agency_swarm import Agent
from agency_swarm.tools import FileSearchTool

agent = Agent(
    name="ResearchAgent",
    description="Processes and searches through research documents",
    tools=[FileSearchTool],  # Enables semantic file search
    files_folder="./research_papers",
)

Sources: examples/agent_file_storage.py Sources: examples/README.md

File Handling in Messages

The AttachmentManager enables files to be included in agent messages, supporting multimodal interactions where agents can reference, process, and respond to file contents.

Supported File Types:

• Documents (PDF, TXT, MD)
• Images (PNG, JPG, GIF)
• Data files (CSV, JSON)
• Code files

Output Types:

Sources: examples/multimodal_outputs.py

Agent Folder Structure

Agents that handle files should follow a specific folder structure:

AgentName/
├── files/                  # Files uploaded to OpenAI
├── schemas/                # OpenAPI schemas for tool generation
├── tools/                  # Custom tool implementations
├── AgentName.py            # Main agent class
├── __init__.py             # Package initialization
└── instructions.md         # Agent instructions

Sources: CONTRIBUTING.md Sources: README.md

Configuration Options

Agent File Configuration

Model Settings for File Processing

When processing files, consider adjusting model settings for better performance:

from agency_swarm import Agent, ModelSettings
from agency_swarm.util.builtins import Reasoning

agent = Agent(
    name="FileAnalyzer",
    model="gpt-5.4-mini",
    model_settings=ModelSettings(
        reasoning=Reasoning(effort="high", summary="auto")
    ),
)

Sources: examples/interactive/tui.py

Examples

Vector Store Creation and File Search

# Complete example from agent_file_storage.py
from agency_swarm import Agent, Agency

# Create agent with file search capability
document_agent = Agent(
    name="DocumentAgent",
    description="Handles document storage and search",
    tools=[FileSearchTool],  # Built-in tool for semantic search
)

# Agency with document handling
agency = Agency([document_agent])

# Upload documents for search
response = agency.get_response_sync(
    "Please analyze the quarterly_reports folder"
)

Message Attachments

# Example from message_attachments.py
from agency_swarm.tools.utils import (
    tool_output_file_from_url,
    tool_output_image_from_path
)

class GenerateReportTool(BaseTool):
    def run(self) -> ToolOutputFileContent:
        return tool_output_file_from_url(
            "https://example.com/report.pdf"
        )

Sources: examples/agent_file_storage.py Sources: examples/message_attachments.py

Best Practices

1. File Organization: Maintain clean files/ directories per agent to avoid confusion in multi-agent setups

1. Vector Store Management: Only include files that need semantic search in vector stores to optimize costs and performance

1. File Size Limits: Be mindful of OpenAI's file size limits (512 MB maximum per file)

1. Persistent Sessions: Use CustomizableChatHistory for maintaining file context across sessions

1. Tool Output Efficiency: Use tool_output_file_from_url for remote files instead of downloading and re-uploading

Sources: examples/README.md Sources: examples/custom_persistence.py

Related Components

Summary

The File Management system in Agency Swarm provides a robust foundation for handling file operations across multi-agent workflows. By leveraging FileManager for core operations, FileSync for cross-agent synchronization, and AttachmentManager for message integration, developers can build sophisticated agentic systems that process, search, and communicate with files seamlessly.

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Chart Library tool for financial pattern analysis in agent swarms

• Severity: high
• Finding: Installation risk is backed by a source signal: Chart Library tool for financial pattern analysis in agent swarms. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/596

2. Installation risk: Feature request: native advisor/executor consult flow for stronger-model escalation

• Severity: high
• Finding: Installation risk is backed by a source signal: Feature request: native advisor/executor consult flow for stronger-model escalation. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/598

3. Installation risk: Proposal: ClawMem adapter for thread persistence across sessions

• Severity: high
• Finding: Installation risk is backed by a source signal: Proposal: ClawMem adapter for thread persistence across sessions. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/594

4. Installation risk: CI-level governance checks for swarm agent code

• Severity: medium
• Finding: Installation risk is backed by a source signal: CI-level governance checks for swarm agent code. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/593

5. Installation risk: Feature: Runtime governance and compliance audit trails

• Severity: medium
• Finding: Installation risk is backed by a source signal: Feature: Runtime governance and compliance audit trails. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/592

6. Installation risk: v1.9.0 - Agent Swarm TUI and OpenClaw

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.9.0 - Agent Swarm TUI and OpenClaw. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0

7. Configuration risk: v1.8.0 — Present and Accounted For

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v1.8.0 — Present and Accounted For. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0

8. Configuration risk: v1.9.2

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v1.9.2. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2

9. Configuration risk: v1.9.5

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v1.9.5. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5

10. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.

11. Maintenance risk: Research finding: Error detection failure rate in multi-agent chains — empirical data

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Research finding: Error detection failure rate in multi-agent chains — empirical data. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/issues/609

12. Maintenance risk: v1.9.4

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: v1.9.4. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agency-swarm with real data or production workflows.

• Feature request: native advisor/executor consult flow for stronger-model - github / github_issue
• Chart Library tool for financial pattern analysis in agent swarms - github / github_issue
• CI-level governance checks for swarm agent code - github / github_issue
• Feature: Runtime governance and compliance audit trails - github / github_issue
• Enforceable agency chart — cryptographic delegation per agent role in th - github / github_issue
• Feature: Agent trust and discovery via MoltBridge integration - github / github_issue
• Proposal: ClawMem adapter for thread persistence across sessions - github / github_issue
• Research finding: Error detection failure rate in multi-agent chains — e - github / github_issue
• v1.9.8 - github / github_release
• v1.9.7 - github / github_release
• v1.9.6 - github / github_release
• v1.9.5 - github / github_release