Handoffs from agents.yaml

Declare handoffs and HandoffConfig from YAML or CLI — no Python needed

Declare which agents can hand off to which — and their execution limits — directly in agents.yaml.

Quick Start

1. Declare handoff: in agents.yaml

   Add a handoff: block under any agent. to: lists the target agent keys.

   # agents.yaml
   agents:
     triage:
       role: Customer Service Triage
       goal: Route the customer to the right specialist
       handoff:
         to: [billing, tech, refund]
         timeout: 30
         max_depth: 3
         max_concurrent: 1
         detect_cycles: true
     billing:
       role: Billing Specialist
       goal: Resolve billing questions
     tech:
       role: Technical Support
       goal: Fix technical issues
     refund:
       role: Refund Specialist
       goal: Process refunds

2. Run it

   The adapter wires the handoff: dict into core Agent.handoffs — no Python required.

   praisonai run agents.yaml

Three Surfaces, Same Wiring

YAML, CLI, and Python all populate the same Agent.handoffs with the same HandoffConfig.

# agents.yaml
agents:
  triage:
    role: Customer Service Triage
    goal: Route the customer to the right specialist
    handoff:
      to: [billing, tech, refund]
      timeout: 30
      max_depth: 3
      max_concurrent: 1
      detect_cycles: true

praisonai --handoff to=billing,tech,refund \
          --handoff-timeout 30 \
          --handoff-max-depth 3 \
          --handoff-max-concurrent 1 \
          --handoff-detect-cycles

from praisonaiagents import Agent
from praisonaiagents.agent.handoff import HandoffConfig

billing = Agent(name="billing", role="Billing Specialist", goal="Resolve billing questions")
tech = Agent(name="tech", role="Technical Support", goal="Fix technical issues")
refund = Agent(name="refund", role="Refund Specialist", goal="Process refunds")

triage = Agent(
    name="triage",
    role="Customer Service Triage",
    goal="Route the customer to the right specialist",
    handoffs=[billing, tech, refund],
    handoff_config=HandoffConfig(
        timeout_seconds=30,
        max_depth=3,
        max_concurrent=1,
        detect_cycles=True,
    ),
)

How It Works

The adapter runs a wiring pass after every agent is built, then resolves each to: role by name.

Unknown target roles are logged and skipped — they never raise.

Configuration Options

Every key under handoff: maps onto a field of core HandoffConfig.

Common Patterns

Triage router — one agent fans out to specialists with a single-hop limit:

agents:
  triage:
    role: Triage
    goal: Send each request to the right specialist
    handoff:
      to: [billing, tech]
      max_depth: 1

Safe chains — cap depth and refuse cycles for deep delegation graphs:

agents:
  planner:
    role: Planner
    goal: Break work into steps and delegate
    handoff:
      to: [researcher, writer]
      max_depth: 3
      detect_cycles: true

Best Practices

Related