Workflow:Microsoft Autogen Swarm Agent Handoff
| Knowledge Sources | |
|---|---|
| Domains | Multi_Agent_Systems, LLM_Orchestration, Agent_Handoff |
| Last Updated | 2026-02-11 18:00 GMT |
Overview
End-to-end process for building a swarm of agents that dynamically route tasks to each other through explicit handoff messages, enabling flexible agent-to-agent delegation without a central orchestrator.
Description
This workflow demonstrates how to construct a Swarm team where agents transfer control to one another via handoff messages. Unlike round-robin or selector-based teams, swarm agents decide autonomously which peer should handle the next step by emitting a HandoffMessage targeting a specific agent. The LLM powering each agent uses tool-like handoff functions to initiate transfers.
The process covers defining agents with handoff targets, configuring the Swarm team, and running it so that control flows organically between agents based on the task requirements. The first agent in the participant list always starts, and subsequent speakers are determined by the most recent HandoffMessage.
Usage
Execute this workflow when agents need to dynamically route work to each other based on task content, rather than following a fixed order or requiring a central selector. Typical scenarios include:
- Customer service routing where a triage agent dispatches to billing, technical support, or account specialists
- Multi-step processing pipelines where each step naturally hands off to the next
- Expert consultation patterns where agents escalate or delegate based on domain boundaries
You have multiple specialized agents and want each agent to decide which peer should handle the conversation next.
Execution Steps
Step 1: Define Agent Specializations
Create multiple AssistantAgent instances, each representing a specialized role. Each agent has a unique name, a focused system message describing its domain, and a model client for inference. The agent descriptions should clearly communicate their area of responsibility so that handoff decisions are well-informed.
Key considerations:
- Agent names must exactly match handoff target strings
- System messages should instruct agents on when to hand off versus when to respond directly
- Each agent can have different model clients, tools, or workbenches
Step 2: Configure Handoff Targets
For each agent, define the set of peer agents it can hand off to by specifying Handoff objects or simple target name strings. A Handoff includes the target agent name, an optional description (used as the tool description for the LLM), and an optional context message passed during transfer.
What happens:
- Each Handoff becomes a function tool registered on the agent
- The LLM can call the handoff tool to transfer control
- The generated tool name follows the pattern "transfer_to_{target}"
- The description guides the LLM on when to use each handoff
Step 3: Set Up Termination Conditions
Define when the swarm conversation should end. In addition to standard conditions like TextMentionTermination and MaxMessageTermination, swarm teams often use HandoffTermination which triggers when a handoff targets a specific agent name (often a human or external system).
Common pattern:
- Use HandoffTermination targeting "user" to pause and await human input
- Combine with MaxMessageTermination as a safety net
- Use TextMentionTermination for a natural "TERMINATE" signal
Step 4: Assemble the Swarm Team
Create a Swarm instance with the list of agents. The Swarm class validates that all handoff targets reference valid participants. The first agent in the list is the initial speaker.
Key considerations:
- Swarm does not accept Teams as participants, only individual agents
- All handoff targets must reference agents in the participants list
- The order of participants determines only the starting agent (index 0)
Step 5: Execute and Monitor the Swarm
Submit a task to the swarm and observe the handoff flow. As agents process messages, they autonomously decide to respond or hand off. Each handoff produces a HandoffMessage that determines the next speaker. The conversation continues until a termination condition is met.
What happens:
- The first agent receives the task and either responds or hands off
- Each HandoffMessage includes a target and optional context for the receiving agent
- The swarm manager extracts the target from the latest HandoffMessage to select the next speaker
- The process repeats until termination
Step 6: Process Results and Resume
Collect the final TaskResult which contains the complete message thread including all handoff events. If the swarm was paused via HandoffTermination, it can be resumed by calling run again with a new task message, which continues from where the conversation left off.
Key considerations:
- Inspect the stop_reason to determine why the swarm terminated
- If terminated by HandoffTermination to "user", provide human input and resume
- Use save_state and load_state for persistent conversation management