Agency Swarm — Multi-agent AI framework using corporate hierarchy metaphor
Project Overview
The multi-agent AI space has seen an explosion of frameworks, but most fall into two camps: low-level orchestration libraries that leave you to wire everything yourself, or opinionated platforms that abstract away too much. Agency Swarm (VRSEN/agency-swarm) sits in a compelling middle ground — it builds directly on top of OpenAI’s Agents SDK rather than reinventing the wheel, layering on a structured organizational metaphor that maps agent interactions to real-world corporate hierarchies. At 4,294 stars[1], it has attracted significant attention from developers who find the CEO-agent-to-specialist-agent model more intuitive than raw tool-calling graphs. The framework’s v1.x rewrite, moving from a custom agent implementation to wrapping OpenAI’s SDK, was a notable architectural pivot that traded some control for better alignment with OpenAI’s evolving API surface.
What It’s For
This framework is for developers building multi-agent systems who want structure without a heavy framework tax. If you’ve worked with the OpenAI Agents SDK directly, you know it gives you agents and handoffs but leaves the orchestration patterns entirely up to you. Agency Swarm provides that missing layer — defining communication flows between agents as explicit directional edges, much like how a CEO delegates to managers who delegate to specialists. It works well for scenarios like customer support triage (an agent that routes to specialized sub-agents), content generation pipelines (research → draft → review), or any workflow where agents have distinct roles with controlled communication paths. The tradeoff is that you’re committing to the OpenAI SDK ecosystem — if you need multi-provider support without going through LiteLLM, or if your use case requires agents to communicate in more dynamic patterns than the predefined flows allow, you might find the structure constraining.
How to Use It
The core workflow starts by defining agent roles as classes that extend the framework’s Agent base, each with its own instructions, tools, and optional sub-agents. You then create an Agency instance that connects these agents through explicit communication flows — think of it as declaring who can talk to whom. The framework handles the underlying message passing, routing requests through the defined hierarchy. Tools are defined either with a decorator or by extending a BaseTool class with Pydantic fields for type-safe argument validation. State persistence is handled through callbacks for loading and saving thread history, which gives you flexibility in where you store conversations without coupling to a specific database.
Decorator for defining tools with automatic type validation, the modern recommended approach
@function_toolAlternative class-based tool definition using Pydantic Field for argument descriptions
class MyCustomTool(BaseTool):Install or upgrade to the latest version from PyPI
pip install -U agency-swarmRecent Updates
Latest Release: v1.9.8 (2025-01-15)
Latest release in the v1.9.x series, continuing refinements to the OpenAI Agents SDK integration
The project has been actively maintained with multiple point releases in the v1.9.x line, suggesting steady incremental improvements rather than major architectural changes. The community around VRSEN’s YouTube channel and Discord indicates an engaged user base, though the migration from v0.x to v1.x likely caused some friction for existing users who had to adapt to the new SDK-based approach.
Sources & Attributions
[1] Star count as of repository analysis — VRSEN/agency-swarm