Agency Swarm: A Multi-Agent Framework Built on the OpenAI Agents SDK

What Agency Swarm Actually Solves

Most multi-agent demos let agents talk to whoever they want. That produces transcripts nobody can audit and loops nobody can bound. Agency Swarm takes the opposite position: the agency is a graph. Each Agent is a named role with its own instructions, tools and files. Communication is not ambient. It happens through a dedicated send_message tool, and only along the directional communication_flows declared on the Agency object. If the CEO cannot message the developer, that edge simply does not exist, and the model cannot invent it.

The intended audience is developers building what the README calls an AI agency, meaning a small set of specialized roles that hand work to each other. The README frames the design as thinking about automation in terms of real-world organizational structures. That framing is the product: an org chart you can read in code, with the edges written down. If your problem is one prompt with a few tools, this framework is overhead. If your problem is five roles and a routing question you keep getting wrong, the explicit graph is the point.

The Mechanism: Agents, Flows and a Pinned SDK

The framework extends the OpenAI Agents SDK rather than replacing it. Agents are constructed from the agency_swarm package and carry name, description, instructions, files_folder, schemas_folder, tools, model and model_settings. Tools come in three shapes: the @function_tool decorator, a BaseTool subclass whose Pydantic fields become the argument schema, or tools generated from an OpenAPI schema through ToolFactory.from_openapi_schema, which accepts either a local JSON file or a fetched schema object.

State is not held inside the framework. The README states that you pass load_threads_callback and save_threads_callback to the Agency, which lets conversation history live in a database or on disk across sessions. That is a deliberate inversion: the framework defines when to load and save, and you define where. The examples directory includes custom_persistence.py and agent_file_storage.py, so the intended extension point is a callback you write, not a storage backend you configure.

The dependency layout is where the design shows its cost. pyproject.toml pins openai-agents to an exact version, 0.22.3, with a comment stating that the project patches private SDK seams including shared_http_client, RunContextWrapper._copy_for_run_state and agents._debug, so any upstream release must be reviewed before the pin moves. That is an honest disclosure and a real constraint. You get a framework that tracks the SDK closely, and you inherit a pin you should not casually override.

Installing Agency Swarm and Defining a First Agency

The README gives one install command and requires Python 3.12 or newer. The package ships a console entry point, agency-swarm, declared in pyproject.toml.

pip install -U agency-swarm

Authentication is an environment variable. The README says a .env file containing OPENAI_API_KEY is auto-loaded, or you can export it in your shell.

export OPENAI_API_KEY="YOUR_API_KEY"

Tools are the first thing you define. The README recommends the @function_tool decorator, imported from agency_swarm, and the docstring is what the agent reads to decide when to call it.

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

Roles come next. The README's example builds a CEO agent with instructions, a files folder, a schemas folder, a tool list and a model setting. Note that instructions can point at a file such as ./instructions.md rather than living inline.

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.6-luna",
    model_settings=ModelSettings(
        max_tokens=25000,
    ),
)

The README then moves to defining the agency's communication flows, and this is where the graph is declared. Two practical pointers from the README: it recommends starting from the Agency Starter Template before customizing anything, and it points at ./examples for runnable demos. The repository also ships a .cursorrules file at the root and a Cursor IDE guide, so the intended workflow includes an AI coding agent reading those conventions. What you should see after the install step is a clean import of agency_swarm under Python 3.12 or newer, and after the agent definition, a constructed Agent object you can hand to an Agency.

Where the Framework Pushes Back

The exact pin on openai-agents is the most consequential limitation, and it is self-declared. Because the framework patches private SDK internals, an upstream release is not a drop-in. The comment in pyproject.toml says any upstream release must be reviewed before the pin moves. If your organization requires prompt security patching of transitive dependencies, this is friction you will feel, and it is not a bug you can file away.

Base installs are another sharp edge. The Makefile carries a test-base-install target with a comment explaining that the base install ships neither extras nor dev dependencies, that agents.voice pulls numpy and websockets from the voice extra, and that a top-level voice import in the package crashes a plain pip install agency-swarm. The project keeps that check in CI rather than assuming it. Read it as a signal: the package has optional surfaces, and a minimal install is a configuration the maintainers test deliberately.

Model support is broader than OpenAI-only, but the route matters. The README lists OpenAI natively and Anthropic, Google, Gemini, Grok, Azure OpenAI and OpenRouter via a LiteLLM router. The Makefile's sync target explicitly uses --no-extra litellm, so the LiteLLM path is an extra you opt into, not something the default development environment carries. If your plan is to run this entirely on a non-OpenAI backend, verify that path early rather than after you have written your agency.

Finally, the v1 line is a rewrite. The README directs anyone migrating from v0.x to a migration guide, and the framework now targets the OpenAI Agents SDK plus the Responses API. Code and tutorials written against v0.x will not map cleanly.

Agency Swarm vs LangGraph

People search for this comparison, and the difference is architectural rather than cosmetic. LangGraph models a workflow as a stateful graph of nodes and edges that you execute, with state threaded through the graph and control flow expressed as graph transitions. Agency Swarm models an organization: the primary objects are agents with roles and instructions, and the graph that matters is the communication graph between them.

The practical consequence is where you spend your effort. In a node-and-edge workflow, you write the routing logic and the state schema, and the model's freedom is bounded by the nodes you defined. In Agency Swarm, the model decides what to say and when to hand off, and the communication_flows restrict who it can reach. That is a different bet. It gives the model more latitude inside each role and less latitude in the topology. If your task decomposes into deterministic steps, the workflow-graph approach is a closer fit. If your task is genuinely conversational delegation between specialists, the role-and-flow model reads more naturally, and the send_message tool becomes the single auditable channel.

The second difference is dependency posture. Agency Swarm is built on the OpenAI Agents SDK and pins it exactly because it patches internals. That buys tight integration with the Responses API and a smaller surface to maintain. It also means the framework's release cadence is coupled to an upstream project it does not control.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-22. Releases are frequent: v1.11.0 on 2026-08-03, v1.10.5 on 2026-07-17 and v1.10.4 the same day, while pyproject.toml already declares version 1.12.0. The project ships a Makefile with sync, format, lint, mypy, tests and tests-fast targets, a pre-commit configuration, and a CI workflow that the README's coverage badge points at. The README states 92 percent coverage. Treat that as the project's own reported figure, not an independent measurement.

Upgrade cost concentrates in two places. First, the openai-agents pin: moving it means reviewing the private seams the project patches, which is maintainer work you inherit the consequences of. Second, the v0.x to v1.x migration, which the README treats as significant enough to warrant a dedicated guide. Within the v1 line, the dependency ranges in pyproject.toml are otherwise bounded but not exact, so ordinary minor upgrades should be routine.

The licence is MIT, declared both in the repository and in the pyproject.toml classifier list. MIT is permissive: it allows commercial use, modification and redistribution with the licence text retained. That is a statement about the licence terms, not legal advice, and if you are embedding the framework in a product, your own counsel should confirm how the MIT notice and your distribution model interact. Note that the licence covers this framework, not the model providers you call through it.

Editorial conclusion

Adopt Agency Swarm if you are on Python 3.12 or newer, you already accept the OpenAI Agents SDK and the Responses API as your execution model, and you want agent communication to be an explicit, reviewable graph rather than emergent. Do not adopt it if you need a model-agnostic core with no OpenAI dependency, or if you cannot tolerate an exact pin on openai-agents, because pyproject.toml states that the project patches private SDK seams and must review each upstream release before moving that pin. Before you commit, verify three things yourself: that your model backend is reachable through the LiteLLM router path, that your persistence callbacks match the load_threads_callback and save_threads_callback signatures the Agency expects, and that a plain pip install of the version you pin imports cleanly under your Python, since the Makefile keeps a separate test-base-install target precisely because a top-level voice import breaks the base install.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. VRSEN/agency-swarm on GitHub