Skip to main content
Agency Swarm supports two paradigms for inter-agent communication that can work together seamlessly: SendMessage tools (orchestrator pattern) and OpenAI SDK Handoffs (sequential pattern). This guide explains how these patterns interact and provides practical examples for building multi-agent systems.

SendMessage Tools

Control returns to the caller, ideal for coordination with oversight. Implemented via SendMessage tool variants.

Handoffs

Control transfers to the target, ideal for full task transfer and specialization. Powered by SendMessageHandoff + OpenAI SDK.

​
Understanding the Two Paradigms

​
SendMessage Tools (Orchestrator Pattern)

  • Control Flow: Control returns to the calling agent
  • Use Case: Delegation with oversight and coordination
  • Implementation: Via SendMessage tool variants
  • Example: Orchestrator → Worker → responds to Orchestrator
  • Conversation History: Each A→B communication flow maintains its own conversation thread. Agent B only sees the history from that specific A→B thread.

​
Handoffs (Sequential Pattern)

  • Control Flow: Control transfers to the handoff target
  • Use Case: Complete task transfer and specialization
  • Implementation: Via SendMessageHandoff tool class + OpenAI SDK
  • Example: Worker → Specialist (control stays with Specialist)
  • Conversation History: The receiving agent gets the full conversation history and continues the interaction

​
The Hybrid Resolution

When both patterns are used together, you can use Agency Swarm to implement a hybrid approach that allows both to coexist without conflicts.

​
How It Works

The hybrid approach works by layering the two communication patterns:
1

Primary Communication Uses Orchestrator Pattern

When Agent A sends a message to Agent B using SendMessage, Agent A will always receive a response (either from Agent B directly, or from a specialist that Agent B handed off to).
2

Internal Processing Can Use Handoffs

While Agent B is working on Agent A’s request, Agent B can hand off to specialists. The specialist receives Agent B’s context and responds directly to Agent A.
3

Best of Both Worlds

  • Agent A gets the coordination benefits of the orchestrator pattern (responses come back)
  • Agent B can hand off to specialists for specialized tasks
  • Agent A receives the specialist’s response without managing multiple conversations

​
Setting Up Handoffs

In this framework, handoffs are configured via the SendMessageHandoff tool.
agency_setup.py
from agency_swarm import Agency, Agent
from agency_swarm.tools import SendMessageHandoff

# Create specialized agents
orchestrator = Agent(
    name="ProjectManager",
    instructions="Coordinate project tasks and oversee completion",
    # ... other config
)

worker = Agent(
    name="Developer",
    instructions="Handle development tasks, consult specialists when needed",
    send_message_tool_class=SendMessageHandoff,
    # ... other config
)

specialist = Agent(
    name="SecurityExpert",
    instructions="Provide security expertise and recommendations",
    # Agent description will be added to the handoff tool instructions
    description="Provides security expertise and recommendations",
    # ... other config
)

# Create agency with communication flows
agency = Agency(
    orchestrator,
    communication_flows=[
        (orchestrator, worker),      # Creates send_message_to_Developer tool
        (orchestrator, specialist),  # Creates send_message_to_SecurityExpert tool
        (worker, specialist),        # Creates a handoff from worker to specialist (since worker has a special send message class)
    ]
)
See the full working example: hybrid_communication_flows.py

​
Execution Flow

1

ProjectManager delegates to Developer

ProjectManager uses send_message_to_Developer: “Implement user authentication with security best practices”.
2

Developer hands off to SecurityExpert

Developer recognizes the need for security expertise and performs a handoff to SecurityExpert. Control transfers completely.
3

SecurityExpert responds with full context

SecurityExpert receives the full conversation history and provides comprehensive security recommendations directly to ProjectManager.
4

ProjectManager receives specialist response

ProjectManager receives the SecurityExpert’s response with complete security guidance, without needing to coordinate multiple conversations.

​
When to Use Hybrid Patterns

​
Ideal Use Cases

  • Hierarchical task delegation with oversight: Manager delegates to workers who can hand off to specialists
  • Expert consultation workflows: Agents can sequentially hand off to specialists while orchestrator maintains control
  • Complex approval processes: Multiple specialists review work with responses going to orchestrator
  • Quality assurance pipelines: Work flows through specialists but orchestrator tracks progress

​
Design Guidelines

When to use:

SendMessage (Orchestrator)

• Control and visibility
• Coordination between multiple agents
• Task-focused agent boundaries

Sequential Handoffs

• Internal agent decision-making
• Allow agents to have the entire context
• Fewer agent-to-agent passes
⚠️ Important: In this framework, handoffs must be configured using SendMessageHandoff tools only. The agent.handoffs parameter is not supported to avoid confusion.

​
Benefits of the Hybrid Approach

  • Internal Transfer: Agents can independently use handoffs to access necessary context and tools without additional agent-to-agent passes.
  • Maintained Control: Some agents can receive a short summary of the response to avoid hallucinations while others can receive full context to increase response accuracy and coverage.
  • Clean Separation of Concerns: High-level coordination remains simple while detailed specialist work happens independently within appropriate agents.

​
Conclusion

Agency Swarm’s hybrid paradigm resolution enables multi-agent architectures that would be difficult to achieve with either pattern alone. By understanding how SendMessage tools and Sequential Handoffs work together, you can build systems that combine the best of both orchestration and sequential transfer patterns, giving you the flexibility to design complex multi-agent workflows.
For more details on individual patterns, see the Overview page. For implementation examples, check the Common Use Cases page.