Handoff Module

API reference for the agent handoff system

Overview

The handoff module provides functionality for agents to delegate tasks to other agents dynamically. It includes the Handoff class for creating custom handoff tools and the handoff function for standard handoff operations.

Classes

Handoff

A subclass of Tool that provides handoff-specific functionality.

class Handoff(Tool):
    def __init__(
        self,
        name: str,
        agent: Union[str, Agent],
        template: str = DEFAULT_TEMPLATE,
        description: str = DEFAULT_DESCRIPTION,
        input_model: Optional[Type[BaseModel]] = None,
        callback: Optional[Callable] = None
    )

Parameters

name · str · required

The name of the handoff tool

agent · Union[str, Agent] · required

Target agent name or Agent instance

template · str · default: "DEFAULT_TEMPLATE"

Template for handoff instructions

description · str · default: "DEFAULT_DESCRIPTION"

Description of the handoff tool

input_model · Optional[Type[BaseModel]]

Pydantic model for structured input

callback · Optional[Callable]

Callback function called during handoff

Methods

run()

def run(self, message: str = "") -> str

Executes the handoff operation.

Parameters:

• message (str): Message to pass to the target agent

Returns:

• str: Handoff prompt with instructions

Example:

handoff_tool = Handoff(name="escalate", agent="Supervisor")
result = handoff_tool.run("Customer needs manager approval")

HandoffInputData

Pydantic model for structured handoff input when using input_model.

class HandoffInputData(BaseModel):
    agent: str = Field(..., description="The name of the agent to hand off to")
    message: str = Field("", description="Additional message or context")

Functions

handoff()

Creates a handoff tool or executes a handoff operation.

def handoff(
    agent: Optional[Union[str, Agent]] = None,
    name: str = "handoff",
    description: str = DEFAULT_DESCRIPTION,
    template: str = DEFAULT_TEMPLATE,
    input_model: Optional[Type[BaseModel]] = HandoffInputData,
    callback: Optional[Callable] = None,
    # Direct execution parameters
    message: str = ""
) -> Union[Handoff, str]

Parameters

agent · Optional[Union[str, Agent]]

Target agent for handoff

name · str · default: "handoff"

Name of the handoff tool

description · str

Description of the handoff functionality

template · str

Template for handoff instructions

input_model · Optional[Type[BaseModel]]

Model for structured input

callback · Optional[Callable]

Callback function for handoff events

message · str

Message for direct handoff execution

Returns

• Handoff: When creating a tool (no message provided)
• str: When executing directly (message provided)

Usage Examples

Creating a handoff tool:

# Basic handoff tool
transfer = handoff(agent="Specialist")

# Custom named handoff
escalate = handoff(
    agent="Supervisor",
    name="escalate_to_supervisor",
    description="Escalate complex issues to supervisor"
)

# With callback
def log_handoff(from_agent, to_agent, context):
    print(f"Handoff: {from_agent} -> {to_agent}")
    
transfer_with_log = handoff(
    agent="Support",
    callback=log_handoff
)

Direct handoff execution:

# Execute handoff immediately
prompt = handoff(
    agent="TechSupport",
    message="User experiencing login issues"
)

prompt_with_handoff_instructions()

Generates a handoff prompt with specific instructions and context.

def prompt_with_handoff_instructions(
    agent: str,
    template: str,
    message: str = ""
) -> str

Parameters

agent · str · required

Name of the target agent

template · str · required

Instruction template

message · str

Additional context or message

Returns

• str: Formatted handoff prompt

Built-in Filters

handoff_filters()

Returns available handoff filter options.

def handoff_filters() -> List[str]

Returns

List of available filters:

• "all" - Accept handoffs from any agent
• "none" - Reject all handoffs
• "self" - Only accept from same agent
• "other" - Accept from any agent except self
• "team:<name>" - Only accept from agents in specified team

Example

filters = handoff_filters()
print(filters)  # ["all", "none", "self", "other", "team:"]

# Use in agent configuration
agent = Agent(
    name="Specialist",
    handoff_filter="team:support"
)

Constants

DEFAULT_TEMPLATE

Default template for handoff instructions:

DEFAULT_TEMPLATE = '''Transferred to: {agent}
{message}

Continue the conversation and help the user with their request.'''

DEFAULT_DESCRIPTION

Default description for handoff tools:

DEFAULT_DESCRIPTION = "Hand off the conversation to another agent"

Integration with Agents

Using Handoffs in Agent Configuration

from praisonaiagents import Agent, handoff

# Method 1: Specify handoff targets
agent = Agent(
    name="Support",
    handoffs=["Billing", "Technical", "Sales"]
)

# Method 2: Provide handoff as a tool
transfer_tool = handoff(name="transfer")
agent = Agent(
    name="Support",
    tools=[transfer_tool]
)

# Method 3: Multiple custom handoffs
escalate = handoff(agent="Supervisor", name="escalate")
transfer = handoff(agent="Specialist", name="transfer")

agent = Agent(
    name="Support",
    tools=[escalate, transfer]
)

Callback Function Signature

def handoff_callback(
    from_agent: str,
    to_agent: str, 
    context: Dict[str, Any]
) -> bool:
    """
    Process handoff event.
    
    Args:
        from_agent: Name of agent initiating handoff
        to_agent: Name of target agent
        context: Handoff context including message and history
        
    Returns:
        bool: True to allow handoff, False to block
    """
    # Custom logic here
    return True

Error Handling

The handoff system handles various error conditions:

• Invalid agent name: Returns error message if target agent not found
• Circular handoffs: Can be prevented using handoff filters
• Callback errors: Logged and handoff continues if callback fails

Best Practices

1. Use descriptive names for custom handoff tools
2. Implement callbacks for logging and monitoring
3. Set appropriate filters to prevent handoff loops
4. Provide context in handoff messages
5. Test handoff chains to ensure smooth transitions

Complete Example

from praisonaiagents import Agent, Task, AgentTeam, handoff
from typing import Dict, Any

# Callback for logging
def log_handoffs(from_agent: str, to_agent: str, context: Dict[str, Any]) -> bool:
    timestamp = context.get('timestamp', 'unknown')
    message = context.get('message', '')
    print(f"[{timestamp}] Handoff: {from_agent} -> {to_agent}")
    print(f"Context: {message[:50]}...")
    return True

# Create specialized handoff tools
escalate_to_manager = handoff(
    agent="Manager",
    name="escalate",
    description="Escalate to manager for approval",
    callback=log_handoffs
)

transfer_to_tech = handoff(
    agent="TechSupport",
    name="transfer_to_tech",
    description="Transfer technical issues to tech support",
    callback=log_handoffs
)

# Create agents with handoff capabilities
frontdesk = Agent(
    name="FrontDesk",
    role="Customer Service Representative",
    goal="Help customers and route complex issues",
    tools=[escalate_to_manager, transfer_to_tech],
    handoff_filter="other"  # Can receive from others but not self
)

manager = Agent(
    name="Manager",
    role="Customer Service Manager",
    goal="Handle escalated issues and approvals",
    handoff_filter="all"  # Can receive from anyone
)

tech_support = Agent(
    name="TechSupport",
    role="Technical Support Specialist",
    goal="Resolve technical issues",
    handoff_filter="team:support"  # Only from support team
)

# Create workflow
workflow = AgentTeam(
    agents=[frontdesk, manager, tech_support],
    memory=True
)

# The agents can now hand off tasks based on conversation context