Handoff Module

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
    )

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

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

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

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]

# 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
)

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

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

def handoff_filters() -> List[str]

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

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

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

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

DEFAULT_DESCRIPTION = "Hand off the conversation to another agent"

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]
)

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

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