Swarm Workflow Pattern

Overview

The Swarm pattern implements OpenAI’s Swarm framework for multi-agent handoffs, enabling seamless context transfer between specialized agents based on conversation flow and requirements.

Quick Example

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
from mcp_agent.workflows.swarm.swarm_orchestrator import SwarmOrchestrator

app = MCPApp(name="swarm_example")

async with app.run() as context:
    # Create specialized agents
    sales_agent = Agent(
        name="sales",
        instruction="Handle sales inquiries and product recommendations.",
        server_names=["database", "fetch"]
    )

    support_agent = Agent(
        name="support",
        instruction="Provide technical support and troubleshooting.",
        server_names=["knowledge_base", "ticketing"]
    )

    billing_agent = Agent(
        name="billing",
        instruction="Handle billing, refunds, and account management.",
        server_names=["billing_system", "database"]
    )

    # Define handoff conditions
    handoff_rules = {
        "sales": {
            "triggers": ["price", "buy", "purchase", "product"],
            "confidence_threshold": 0.7
        },
        "support": {
            "triggers": ["error", "bug", "help", "troubleshoot"],
            "confidence_threshold": 0.8
        },
        "billing": {
            "triggers": ["refund", "payment", "invoice", "subscription"],
            "confidence_threshold": 0.9
        }
    }

    # Create swarm orchestrator
    swarm = SwarmOrchestrator(
        agents=[sales_agent, support_agent, billing_agent],
        handoff_rules=handoff_rules,
        llm_factory=OpenAIAugmentedLLM,
        initial_agent="sales"
    )

    # Execute with automatic handoffs
    result = await swarm.generate_str(
        message="I'm interested in your premium plan but having trouble with payment"
    )
    # Automatically hands off from sales -> billing agent

Key Features

  • Automatic Handoffs: Context-aware agent switching based on conversation flow
  • Context Preservation: Full conversation history maintained across handoffs
  • Trigger-Based Routing: Configurable keywords and confidence thresholds
  • Bidirectional Communication: Agents can hand back to previous agents
  • State Management: Maintains conversation state and agent history

Use Cases

  • Customer Service: Route between sales, support, and billing specialists
  • Multi-Domain Assistance: Hand off between technical and business experts
  • Progressive Disclosure: Start general, become more specialized as needed
  • Workflow Orchestration: Pass tasks through specialist processing pipeline

Full Implementation

See the complete swarm pattern implementation with OpenAI Swarm compatibility.