Implementation:Microsoft Autogen Handoff Init
| Knowledge Sources | |
|---|---|
| Domains | Multi-Agent Systems, Task Routing, Agent Communication, Workflow Design |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Concrete tool for configuring explicit handoff routes between agents in a swarm, provided by Microsoft AutoGen.
Description
The Handoff class is a Pydantic BaseModel that defines a single handoff route from one agent to another. When instantiated, it captures the target agent name, a natural-language description of when the handoff should occur, an optional custom tool name, and a message to deliver upon transfer.
A model_validator (mode="before") auto-generates sensible defaults for any fields not explicitly provided:
- name defaults to
transfer_to_{target}(lowercased), validated as a Python identifier. - description defaults to
"Handoff to {target}.". - message defaults to
"Transferred to {target}, adopting the role of {target} immediately.".
The handoff_tool property dynamically creates a FunctionTool wrapping a closure that returns the configured message string. This tool is what the LLM sees and invokes during conversation. The tool is created with strict=True to enforce schema validation.
Usage
Import and instantiate Handoff when you need fine-grained control over how an agent's handoff routes are configured. For simple cases, passing a plain string to the handoffs parameter of AssistantAgent is sufficient (the string is auto-converted to a HandoffBase). Use the explicit Handoff class when you need custom descriptions, tool names, or transfer messages.
Code Reference
Source Location
- Repository: Microsoft AutoGen
- File:
python/packages/autogen-agentchat/src/autogen_agentchat/base/_handoff.py(Lines 12-62)
Signature
class Handoff(BaseModel):
target: str
description: str = Field(default="")
name: str = Field(default="")
message: str = Field(default="")
@model_validator(mode="before")
@classmethod
def set_defaults(cls, values: Dict[str, Any]) -> Dict[str, Any]: ...
@property
def handoff_tool(self) -> BaseTool[BaseModel, BaseModel]: ...
Import
from autogen_agentchat.base import Handoff
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| target | str | Yes | The name of the target agent to hand off to. Must match a participant name in the swarm team. |
| description | str | No | Natural-language description of when this handoff should occur. Guides the LLM's decision to invoke the handoff tool. Defaults to "Handoff to {target}.". |
| name | str | No | Custom tool name for this handoff. Must be a valid Python identifier. Defaults to "transfer_to_{target}" (lowercased). |
| message | str | No | The message delivered to the target agent upon transfer. Serves as the tool's return value. Defaults to "Transferred to {target}, adopting the role of {target} immediately.". |
Outputs
| Name | Type | Description |
|---|---|---|
| Handoff instance | Handoff | A configured handoff route object. Access the handoff_tool property to obtain the FunctionTool that can be registered with an agent. |
| handoff_tool | BaseTool[BaseModel, BaseModel] | A FunctionTool created from the handoff configuration. When invoked, it returns the configured message string. |
Usage Examples
Basic Example
from autogen_agentchat.base import Handoff
# Minimal handoff with auto-generated defaults
simple_handoff = Handoff(target="billing_agent")
# tool name: "transfer_to_billing_agent"
# description: "Handoff to billing_agent."
# message: "Transferred to billing_agent, adopting the role of billing_agent immediately."
# Customized handoff with explicit description and message
detailed_handoff = Handoff(
target="escalation_agent",
description="Transfer to escalation when the customer is dissatisfied or the issue cannot be resolved.",
name="escalate_issue",
message="Escalating this conversation to a senior support agent for further assistance.",
)
# Use with AssistantAgent
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
model_client = OpenAIChatCompletionClient(model="gpt-4o")
agent = AssistantAgent(
name="support",
model_client=model_client,
handoffs=[simple_handoff, detailed_handoff],
system_message="You are a front-line support agent.",
)