Getting Started with Swarm: Build Your First Multi-Agent System

Getting Started with Swarm: A Practical Tutorial

This guide will walk you through setting up and running your first multi-agent system using OpenAI's Swarm framework. By the end, you'll have a working agent orchestration pipeline running locally.

Prerequisites

• Python 3.10+ installed on your machine
• An OpenAI API key (or a local OpenAI-compatible server like Ollama)
• Basic familiarity with Python functions

Installation

pip install git+https://github.com/openai/swarm.git

That's it! Swarm has minimal dependencies — just the OpenAI Python client library.

Your First Agent

Let's create a simple agent that can hand off tasks between a Spanish speaker and a French speaker:

from swarm import Swarm, Agent

client = Swarm()

def transfer_to_spanish():
    return Agent(
        name="Spanish Agent",
        instructions="You only speak Spanish. Respond in Spanish."
    )

def transfer_to_french():
    return Agent(
        name="French Agent",
        instructions="You only speak French. Respond in French."
    )

english_agent = Agent(
    name="English Agent",
    instructions="You are a helpful assistant that routes language requests.",
    functions=[transfer_to_spanish, transfer_to_french]
)

messages = [{"role": "user", "content": "Hablemos en español"}]
response = client.run(agent=english_agent, messages=messages)
print(response.messages[-1]["content"])

How Handoffs Work

When the user asks to speak Spanish, the English agent calls transfer_to_spanish(), which returns a new Agent instance. Swarm automatically hands off the conversation to that agent, including all message history. The Spanish agent then continues the conversation entirely in Spanish.

Running with a Local Model

To use Swarm with a locally-hosted model (via Ollama, vLLM, or LocalAI), simply point the client to your local endpoint:

client = Swarm(
    base_url="http://localhost:11434/v1",  # Ollama
    api_key="not-needed"
)

Best Practices

• Keep agents focused: Each agent should have a single responsibility
• Use descriptive function names: Function names serve as the handoff mechanism
• Write clear docstrings: The docstring becomes the agent's context for when to call a function
• Test in isolation: Each agent can be tested independently before connecting handoffs

Conclusion

Swarm makes multi-agent orchestration as simple as writing Python functions. Its minimalist design philosophy means you can prototype complex agent workflows in minutes and deploy them with confidence. Start with simple handoffs, then gradually build up to sophisticated multi-agent systems running entirely on your own infrastructure.