agency-swarm: routing agent messages with a directional permission list
Reliable Multi-Agent Orchestration Framework
At a glance
- What is it?
- A Python layer over the OpenAI Agents SDK that adds named organizational roles, a directional list of who may start a chat, and tool factories, while leaving thread storage to callbacks you write.
- Who is it for?
- agency-swarm fits teams already running the OpenAI Agents SDK who want agent roles governed by an explicit directional permission list instead of a free-form group chat. Read the migration guide first if your code targets v0.x, since this version targets the SDK and the Responses API.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- VRSEN/agency-swarm4,639 ★ · +64
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| VRSEN/agency-swarm | 4.6k | 4.6k |
64 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Directional communication_flows decide who may start a chat
agency-swarm routes agent chatter through an explicit permission list rather than a shared room. The Agency takes a communication_flows argument, and each entry is written with the `>` operator: `ceo > dev` means the CEO may open a chat with the developer, not the reverse. The first agent passed positionally is the entry point the user talks to. Agents never reach each other directly, they call a dedicated `send_message` tool, and the flow list decides whether that call is allowed at all. This is what keeps a wide swarm from collapsing into a mutual broadcast. In the three agent example, the CEO reaches the developer and the virtual assistant, and the developer reaches the virtual assistant, but no backward path exists unless you write one. Replacing that tool is a supported scenario too, since examples/custom_send_message.py sits in the examples tree next to examples/handoffs.py.
Three doors into a tool: function_tool, BaseTool, and OpenAPI schemas
The decorated function is the route the project points at. A type annotation plus a one line docstring becomes a typed tool, and that annotation is what hands the model its argument schema:
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}"The class route stays available for code written against the earlier style: subclass BaseTool, declare each field with a Pydantic Field description, and those descriptions are what the model reads when deciding whether to call the tool. The third door takes a spec you already own. `ToolFactory.from_openapi_schema` accepts a JSON document from disk or straight off the network, so an internal REST service becomes callable without a hand written wrapper per endpoint. The Agent constructor also accepts a `schemas_folder="./schemas"` directory, so schemas sitting next to your code are converted at construction time.
Thread state is two callbacks you write
Conversation history is not stored for you. The Agency accepts `load_threads_callback` and `save_threads_callback`, and persistence across sessions happens only as far as those two functions reach, whether the target is a database or a file on disk. Everything above them belongs to the underlying SDK, so agency-swarm owns the swarm shape and not the storage layer. The examples tree makes the extension points plain: examples/custom_persistence.py and examples/agent_file_storage.py sit beside examples/message_attachments.py and examples/system_reminders.py, which means a real setup assembles storage, attachments and reminders itself.
Install, key, first run: pip, an env file, then copilot_demo()
Python 3.12 or newer is the floor, and the package drops into an existing environment with one command. The key lives in a `.env` file as `OPENAI_API_KEY=your_key`, which is loaded for you through python-dotenv, or in your shell:
pip install -U agency-swarmexport OPENAI_API_KEY="YOUR_API_KEY"OpenAI is the native backend, with the GPT-5 family and GPT-4o named first. Anthropic Claude, Gemini, Grok from xAI, Azure OpenAI and OpenRouter arrive through LiteLLM acting as a router. Running the swarm is a method call on the Agency object, `copilot_demo()` opens the web UI and `tui()` opens the terminal app, which installs itself on first run, prints a short setup message, then reuses that app on later runs. Both front ends are meant for looking at a swarm rather than serving one. The only console entry point in the package metadata is `agency-swarm`, mapped to `agency_swarm.cli.main:main`.
The SDK pin is exact, and the comment names the patched seams
The dependency list holds openai-agents at exactly 0.22.3 and openai in the 3 series, and the reasoning sits in a comment inside pyproject.toml rather than in a changelog. The seams named there are `shared_http_client`, `RunContextWrapper._copy_for_run_state` and `agents._debug`, described as private SDK internals that agency-swarm patches. The comment also states the rule: any upstream release must be reviewed before the pin moves. For a reader this is the most consequential line in the project, because it means you cannot pick up an upstream bug fix or security patch by upgrading on your own, pip holds the older copy, and you inherit patches written against private attributes that the upstream maintainers are free to rename. A framework release is the supported path through that gate. Development work runs through uv:
uv sync --all-extras --no-extra litellm --devA bare install skips litellm, and a voice import can crash it
The Makefile draws the line between what the published wheel contains and what a checkout adds. `make sync` pulls every extra except litellm plus the dev dependencies, and `test-base-install` then imports the package in an isolated environment with no dev packages at all:
uv run --isolated --no-dev python -c "import agency_swarm"The comment attached to that target names the failure it guards. `agents.voice` pulls numpy and websockets from the voice extra, so a top level voice import inside the package crashes a plain `pip install agency-swarm`. The published install and the developer environment are deliberately not the same thing, and the repository keeps a target whose only job is to prove the plain one still imports. LiteLLM is left out of the dev sync as well.
Nothing in the tree schedules a run or meters the tokens
This is the gap to weigh before adopting the framework. Neither the dependency list nor the top level tree names a queue, a scheduler, a retry policy or a token counter. The examples nearest to production duty are examples/observability.py and examples/streaming.py, which show that plumbing exists without saying anything about limits.
pyproject.toml says 1.12.0 while the newest tag is v1.11.0
pyproject.toml carries `version = "2.0.0-beta.1"`, matching the newest published release, v2.0.0-beta.1 from 2026-10-30, which follows v1.11.0 from 2026-08-03 and v1.10.5 from 2026-07-17. The activity record looks current: the last push was on 2026-10-30 and the repository is not archived. The license is MIT and the author field names Vrsen AI Solutions, while the homepage sits at agency-swarm.ai with a separate migration guide for v0.x users. Python support is declared for 3.12, 3.13 and 3.14, and the classifiers call the package OS Independent, matching the macOS, Linux and Windows claim.
Editorial conclusion
agency-swarm fits teams already running the OpenAI Agents SDK who want agent roles governed by an explicit directional permission list instead of a free-form group chat. Read the migration guide first if your code targets v0.x, since this version targets the SDK and the Responses API. Before committing, check what the exact openai-agents pin is holding back, write the two thread callbacks yourself.
Frequently asked questions
What is agency-swarm and what does it add to the OpenAI Agents SDK?
It is a Python framework for multi-agent applications that extends the OpenAI Agents SDK with named agent roles, a directional communication_flows list, Pydantic typed tools, and OpenAPI schema conversion. Python 3.12 or newer is required and the license is MIT.
What is an agent swarm and how does agency-swarm model one?
A group of AI agents that hand work to each other. agency-swarm models it as an Agency whose agents talk through a send_message tool, with communication_flows entries written as ceo > dev to mark which side may initiate a chat.
How do you build an agent swarm with agency-swarm?
Install with pip install -U agency-swarm, set OPENAI_API_KEY in a .env file or your shell, define tools with the @function_tool decorator, create Agent objects, then pass them to Agency with communication_flows. Run agency.copilot_demo() for the web UI or agency.tui() for the terminal.
What is an agent swarm used for in an agency-swarm setup?
The repository ships examples for streaming, multimodal outputs, guardrails on input and output, observability, web search, MCP servers, handoffs, FastAPI integration and file storage. The framework itself routes messages between agents.
What does swarm mean in AI, and where does agency-swarm sit?
It means many agents working as one unit. agency-swarm takes the organizational view: named roles such as CEO or Developer, instructions you control per agent, and a communication graph that decides which role may start a conversation with which.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vrsen-agency-swarm)Star history chart for your README
[](https://hysenlabs.com/projects/vrsen-agency-swarm)Was this useful?