Getting Started with Agency Swarm: A Practical Guide

I was drowning in a content pipeline problem. My team needed to process hundreds of product descriptions weekly—research competitors, draft copy, run SEO checks, and format for different platforms. I'd tried chaining prompts together manually, but the context got messy, error handling was a nightmare, and I kept hitting rate limits in unpredictable ways. I needed something that could model this as an actual workflow with specialized roles, not just a series of API calls.

That's what led me to Agency Swarm. The idea of structuring agents like a real organization—where a "CEO" agent routes tasks to specialists who hand off to each other—clicked immediately. Here's what I learned building my first agency with it.

What Agency Swarm Actually Is

Agency Swarm is a multi-agent orchestration framework built on top of the OpenAI Agents SDK. Instead of writing raw API calls and managing conversation state yourself, you define agents with specific roles, tools, and communication paths, then let the framework handle the orchestration. Think of it as giving your agents an org chart and letting them figure out the collaboration.

The framework handles the stuff that's tedious to build from scratch: inter-agent communication, tool validation with Pydantic, conversation threading, and graceful error handling when one agent's output doesn't match what the next agent expects.

Setting Up Your First Agency

First, install the package:

pip install agency-swarm

You'll need your OpenAI API key set as an environment variable:

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

I made the mistake early on of trying to use a project key without the right permissions. Make sure your key has access to the models you want to use—Agency Swarm defaults to GPT-4o, and you'll get cryptic auth errors if your key can't access it.

Defining Your Agents

The core building block is the Agent class. Each agent gets a role, instructions, and optionally, tools. Here's how I set up a simple content agency:

from agency_swarm import Agent

ceo = Agent(
    name="CEO",
    instructions="""You are the CEO of a content agency. Your job is to:
    1. Receive requests from the user
    2. Break them down into clear tasks
    3. Delegate to the appropriate specialist
    4. Review and synthesize the final output
    
    Always confirm your plan with the user before delegating.""",
    model="gpt-4o"
)

researcher = Agent(
    name="Researcher",
    instructions="""You are a research specialist. When given a topic:
    1. Identify key competitors and their content strategies
    2. Find relevant statistics and data points
    3. Note content gaps in the market
    4. Return a structured research brief
    
    Be thorough but concise. Focus on actionable insights.""",
    model="gpt-4o"
)

copywriter = Agent(
    name="Copywriter",
    instructions="""You are a skilled copywriter. Using the research brief provided:
    1. Write compelling product descriptions
    2. Adapt tone based on the target platform
    3. Include relevant keywords naturally
    4. Provide 2-3 variations when possible
    
    Always ask for the research brief before writing.""",
    model="gpt-4o"
)

One thing that surprised me: the instructions matter enormously. My first attempt gave the CEO vague instructions like "manage the team," and it kept trying to do everything itself instead of delegating. Being explicit about when and how to delegate made a huge difference.

Wiring Up Communication

This is where Agency Swarm differs from simpler agent setups. You define communication flows—who can talk to whom—when you create the Agency object:

from agency_swarm import Agency

agency = Agency(
    name="ContentAgency",
    agents=[ceo, researcher, copywriter],
    communication_flows=[
        (ceo, researcher),
        (ceo, copywriter),
        (researcher, copywriter),  # Researcher can hand off directly to copywriter
    ],
    shared_instructions="Always be professional. Return responses in markdown format."
)

The communication_flows define the org chart. The CEO can talk to both the researcher and copywriter. The researcher can hand off to the copywriter. But the copywriter can't bypass the CEO to assign tasks to the researcher—that's not in the flow.

I initially made everything bidirectional, thinking more communication paths would be better. Wrong. The agents got confused, looping requests between each other. Constraining communication actually made the system more reliable.

Adding Custom Tools

Agents are more useful when they can actually do things. Agency Swarm uses Pydantic for type-safe tool definitions. Here's a tool I built for the researcher to search the web:

from pydantic import Field
from agency_swarm import Tool

class WebSearchTool(Tool):
    """Search the web for information on a given topic."""
    
    query: str = Field(
        ..., 
        description="The search query to look up"
    )
    num_results: int = Field(
        default=5,
        description="Number of results to return"
    )
    
    def run(self):
        # Your actual search implementation here
        # I used a simple SerpAPI integration
        from serpapi import GoogleSearch
        search = GoogleSearch({
            "q": self.query,
            "num": self.num_results,
            "api_key": "your-serp-api-key"
        })
        results = search.get_dict().get("organic_results", [])
        return "\n".join([
            f"- {r['title']}: {r.get('snippet', '')}" 
            for r in results[:self.num_results]
        ])

Then attach it to the agent:

researcher = Agent(
    name="Researcher",
    instructions="...",
    model="gpt-4o",
    tools=[WebSearchTool]
)

The Pydantic validation caught me more than once. I initially defined num_results as just int without a default, and the agent kept failing because it wasn't always passing that parameter. Adding a default value fixed it. The framework validates tool inputs before execution, which saves you from runtime crashes—but you need to design your schemas thoughtfully.

Running the Agency

With everything wired up, running a task is straightforward:

response = agency.get_response(
    message="Write a product description for our new wireless earbuds targeting fitness enthusiasts"
)

print(response)

What happens behind the scenes is the CEO receives the message, decides to delegate research to the researcher, the researcher uses the web search tool, hands findings to the copywriter, and the copywriter produces the final draft. The CEO then synthesizes and returns the response.

You can also stream the output to see what's happening in real time:

response = agency.get_response(
    message="Write a product description for our new wireless earbuds",
    yield_messages=True
)

for msg in response:
    print(f"[{msg.agent_name}]: {msg.content}")

This was invaluable for debugging. I could see exactly where the chain was breaking or where an agent was going off track.

Debugging Tips from the Trenches

Watch for infinite loops. Early on, my researcher would ask the copywriter for clarification, the copywriter would ask the researcher for more data, and they'd ping-pong until hitting the token limit. Adding explicit instructions like "never ask for clarification, work with what you have" broke the cycle.

Log everything. Agency Swarm has built-in logging you can enable:

import logging
logging.basicConfig(level=logging.DEBUG)

This shows you every inter-agent message, tool call, and decision. It's noisy but essential when something goes wrong.

Start simple. My first agency had six agents. It was chaos. I stripped it back to two agents (CEO + one specialist), got that working reliably, then added agents one at a time. Each addition broke something, but it was manageable to fix.

Honest Limitations

Agency Swarm isn't magic. Here's what I ran into:

Token costs add up fast. Each inter-agent message consumes tokens. A simple task that should take 500 tokens can balloon to 5,000+ when agents discuss among themselves. Monitor your usage.
Latency compounds. Sequential agent handoffs mean sequential API calls. My content pipeline takes 30-60 seconds for a single description. Not suitable for real-time applications.
Error recovery is still manual. When an agent produces garbage output, the framework doesn't automatically retry or reroute. You need to handle this in your instructions or add guardrail tools.
The framework is evolving. It recently migrated to be built on the OpenAI Agents SDK, and some older tutorials are outdated. Check the migration guide if you're coming from v0.x.

When It's Worth Using

Agency Swarm shines when you have a genuine multi-step workflow with distinct roles. If you're just doing prompt chaining—step A feeds step B feeds step C—a simpler framework or even raw API calls might be more efficient. But when you need conditional routing (the CEO decides which specialist to use), parallel work (researcher and SEO analyst work simultaneously), or complex handoffs with validation, the organizational metaphor really does make things cleaner.

My content pipeline now runs reliably with four agents, processes 50+ descriptions daily, and the modular structure means I can swap out the copywriter for a different tone without touching the rest of the system. That alone made the learning curve worth it.

Getting started with Agency Swarm: a practical guide