Master Agency Swarm with our step-by-step tutorial, detailed feature walkthrough, and expert tips.
Install Agency Swarm via pip install agency
swarm and set up your OpenAI API key in the environment variables Clone the official examples repository from GitHub and run the 'basic_agency' example to understand agent roles and communication Create your first custom agency using the agency.py template, defining 2
3 specialized agents with specific roles and responsibilities Define agent tools using Pydantic models following the provided tool development guide and test agent interactions in the web UI Deploy your agency to production using the deployment guide and monitor agent performance through the built
in observability dashboard
💡 Quick Start: Follow these 4 steps in order to get up and running with Agency Swarm quickly.
Explore the key features that make Agency Swarm powerful for voice agents workflows.
No. Agency Swarm uses directional flows (A > B means A can message B) but does not require a strict hierarchy. You can create bidirectional flows, peer-to-peer patterns, star topologies, or mesh networks depending on your use case. The only constraint is that communication paths must be explicitly declared, which prevents chaotic broadcast patterns. This explicit control is a core design principle of the framework.
CrewAI typically gets you to a working prototype faster thanks to its simpler role-based abstractions and flexible communication defaults. Agency Swarm takes longer to set up but provides deterministic behavior through explicit communication control and type-safe tools. Teams running continuous workloads generally see lower token costs with Agency Swarm due to its directional communication model, which avoids the broadcast overhead common in other frameworks.
Yes, via the built-in LiteLLM router, which supports 50+ providers including Anthropic Claude, Google Gemini, Grok, Azure OpenAI, and open-source models. OpenAI models (GPT-4o, GPT-5) work natively with full feature support including streaming and function calling. Other providers work but may have partial compatibility issues — particularly around advanced function calling and streaming features.
Each agent makes independent API calls, so a five-agent conversation typically uses 5-10x the tokens of single-agent work. To control costs, use GPT-4o-mini for routine agents (intake, routing, simple tool calls) and reserve GPT-5 or Claude Opus for complex reasoning roles. Budget carefully, since costs scale multiplicatively with agent count and conversation length. Agency Swarm's explicit communication flows help limit unnecessary token usage compared to broadcast models.
Python 3.12 or higher is required for v1.x. The current architecture uses async-first patterns and OpenAI Agents SDK features that depend on Python 3.12+ runtime capabilities such as improved asyncio and type system enhancements. If you are still on Python 3.10 or 3.11, you can use the legacy v0.x branch, but new features like FastAPI integration, MCP Tools Server, and guardrails are only available in v1.x.
Now that you know how to use Agency Swarm, it's time to put this knowledge into practice.
Sign up and follow the tutorial steps
Check pros, cons, and user feedback
See how it stacks against alternatives
Follow our tutorial and master this powerful voice agents tool in minutes.
Tutorial updated March 2026