Handoff Tool Policy

Secure tool boundaries when one agent hands off to another

Tool policy limits which tools the target agent can use during a handoff — so a low-trust gatekeeper cannot escalate privileges by handing off to a powerful automation agent.

from praisonaiagents import Agent, handoff, tool

@tool
def search_tool(query: str) -> str:
    """Search the knowledge base."""
    return f"Results for: {query}"

gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
automation = Agent(name="Automation", tools=[search_tool])

triage = Agent(
    name="Triage",
    handoffs=[handoff(automation)],
)

triage.start("Find policy docs and hand off to automation")

The user asks the triage agent; tool policy limits what the target can run during handoff.

Quick Start

1. Secure by default

   No extra configuration needed — handoff(target) already enforces intersect mode.

   from praisonaiagents import Agent, handoff, tool
   
   @tool
   def search_tool(query: str) -> str:
       """Search the knowledge base."""
       return f"Results for: {query}"
   
   @tool
   def execute_code(code: str) -> str:
       """Run code in a sandbox."""
       return "executed"
   
   gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
   automation = Agent(name="Automation", tools=[search_tool, execute_code])
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation)],  # automation only gets search_tool during handoff
   )

2. Block dangerous tools

   Always strip specific tool names regardless of mode.

   from praisonaiagents import Agent, handoff
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation, blocked_tools=["execute_code"])],
   )

3. Opt into legacy passthrough

   from praisonaiagents import Agent, handoff
   
   triage = Agent(
       name="Triage",
       handoffs=[
           handoff(
               automation,
               tool_policy_mode="passthrough",
               blocked_tools=["execute_code"],
           ),
       ],
   )

4. Full HandoffConfig

   from praisonaiagents import Agent, handoff, HandoffConfig, HandoffToolPolicy
   
   config = HandoffConfig(
       tool_policy=HandoffToolPolicy(
           mode="intersect",
           blocked_tools=["execute_code", "shell_access"],
       ),
   )
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation, config=config)],
   )

   HandoffConfig also carries max_concurrent, enforced independently per handoff — see Per-Instance Concurrency.

How It Works

Error semantics

A failed handoff returns a dict, so hooks, telemetry, and retry logic treat it as a failed tool call.

{"error": "Handoff cycle detected - ...", "handoff_failed": True}
{"error": "Maximum handoff depth exceeded - ...", "handoff_failed": True}
{"error": "Error during handoff to Billing: ...", "handoff_failed": True}

Modes

Configuration Options

HandoffToolPolicy

handoff() shorthand kwargs

Common Patterns

Gatekeeper → automation (secure default)

from praisonaiagents import Agent, handoff, tool

@tool
def search_tool(query: str) -> str:
    return f"Results for: {query}"

@tool
def execute_code(code: str) -> str:
    return "executed"

gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
automation = Agent(name="Automation", tools=[search_tool, execute_code])

router = Agent(name="Router", handoffs=[handoff(automation)])

Always block destructive tools

router = Agent(
    name="Router",
    handoffs=[
        handoff(
            automation,
            blocked_tools=["execute_code", "shell_access", "delete_file"],
        ),
    ],
)

Passthrough with selective block list

router = Agent(
    name="Router",
    handoffs=[
        handoff(
            automation,
            tool_policy_mode="passthrough",
            blocked_tools=["execute_code"],
        ),
    ],
)

Best Practices

Migration Note

Related