​
Agent Handoff System

The handoff system enables seamless task delegation between specialised agents, allowing complex workflows where each agent contributes their expertise.

​
Key Concepts

Agents can transfer conversations to specialists based on context and requirements

Full conversation history and context are maintained during handoffs

Handoffs appear as tools that agents can invoke naturally

Dynamic routing based on conversation context and agent expertise

​
Quick Start

from praisonaiagents import Agent

# Specialist agents
billing_agent = Agent(
    name="Billing Specialist",
    instructions="You handle billing inquiries and payment issues."
)

tech_agent = Agent(
    name="Technical Support",
    instructions="You solve technical problems and provide guidance."
)

# Main agent with handoffs
triage_agent = Agent(
    name="Customer Service",
    instructions="You help customers and route to specialists.",
    handoffs=[billing_agent, tech_agent]
)

​
Handoff Configuration

​
Basic Parameters

ParameterTypeDescriptionDefault
agentAgentTarget agent for handoffRequired
tool_name_overridestrCustom name for handoff tooltransfer_to_<agent_name>
tool_description_overridestrCustom descriptionAuto-generated
on_handoffCallableCallback functionNone
input_filterCallableFilter for conversation dataNone

​
Handoff Filters

# Remove tool calls from history
handoff(
    agent,
    input_filter=handoff_filters.remove_all_tools
)

​
Advanced Features

​
Structured Input Types

Use Pydantic models for typed handoff data:

from pydantic import BaseModel

class EscalationData(BaseModel):
    reason: str
    priority: str
    customer_id: str

escalation = handoff(
    escalation_agent,
    input_type=EscalationData,
    tool_description_override="Escalate to senior management with structured data"
)

​
Callback Patterns

def on_transfer():
    print("Transfer initiated")

handoff(agent, on_handoff=on_transfer)

​
Complete Example

from praisonaiagents import Agent
from praisonaiagents.agent.handoff import handoff, handoff_filters

# Specialist agents
order_agent = Agent(
    name="Order Management",
    instructions="You help with order status and tracking.",
    tools=[check_order_status, track_shipment]
)

refund_agent = Agent(
    name="Refund Specialist",
    instructions="You process refunds and handle return requests.",
    tools=[process_refund, check_refund_policy]
)

technical_agent = Agent(
    name="Technical Support",
    instructions="You solve technical issues and provide guidance.",
    tools=[diagnose_issue, create_ticket]
)

# Escalation with structured input
class EscalationRequest(BaseModel):
    issue_type: str
    severity: str
    description: str

escalation_agent = Agent(
    name="Senior Manager",
    instructions="You handle escalated issues requiring management attention."
)

# Main triage agent
triage_agent = Agent(
    name="Customer Service",
    instructions="""You are the first point of contact. Route customers to the right specialist:
    - Order issues → Order Management
    - Refunds → Refund Specialist
    - Technical problems → Technical Support
    - Complex issues → Escalate to management
    """,
    handoffs=[
        order_agent,
        refund_agent,
        technical_agent,
        handoff(
            escalation_agent,
            tool_name_override="escalate_to_management",
            input_type=EscalationRequest,
            on_handoff=lambda src, data: log_escalation(src.name, data)
        )
    ]
)

# Start the service
response = triage_agent.chat("I need a refund for order #12345")

​
Best Practices

Define specific expertise for each agent to ensure proper routing

Use input filters to manage conversation history size

Implement callbacks to handle failed handoffs gracefully

Limit handoff chains to prevent excessive delegation

​
Integration with Agent Instructions

The handoff system automatically enhances agent prompts:

# Automatic prompt enhancement
agent = Agent(
    name="Support Agent",
    instructions="You help customers with their issues.",
    handoffs=[billing_agent, tech_agent]
)

# The system adds:
# "You have the ability to transfer conversations to:
#  - Billing Specialist for billing issues
#  - Technical Support for technical problems"

​
Next Steps

Build complex multi-agent workflows

Add persistent memory to your agents