Handoffs - PraisonAI

Agents can transfer conversations to other specialized agents when needed.

Quick Start

Simple Usage

import { Agent, handoff } from 'praisonai';

const billingAgent = new Agent({
  name: 'Billing',
  instructions: 'You handle billing and payment questions'
});

const mainAgent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
  handoffs: [billingAgent]
});

// Automatically transfers billing questions
await mainAgent.chat("I have a question about my invoice");
// → Billing agent responds

With Configuration

const mainAgent = new Agent({
  handoffs: [
    handoff({
      agent: billingAgent,
      description: 'Transfer for payment or billing questions'
    }),
    handoff({
      agent: supportAgent,
      description: 'Transfer for technical issues'
    })
  ]
});

User Interaction Flow

Configuration Levels

// Level 1: Array - Simple agent list
const agent = new Agent({
  handoffs: [billingAgent, supportAgent]
});

// Level 2: Dict - With descriptions
const agent = new Agent({
  handoffs: [
    { agent: billingAgent, description: 'For billing questions' }
  ]
});

// Level 3: Instance - Full control with conditions
import { handoff, handoffFilters } from 'praisonai';

const agent = new Agent({
  handoffs: [
    handoff({
      agent: billingAgent,
      description: 'For billing',
      condition: handoffFilters.topic(['invoice', 'payment', 'refund'])
    })
  ]
});

When to Transfer

User Topic	Best Agent
Payment questions	Billing Agent
Technical issues	Support Agent
Product inquiries	Sales Agent
General questions	Main Agent

Safety Features

Handoffs include built-in protections:

Cycle detection: Prevents A → B → A loops
Depth limits: Maximum 10 handoffs in a chain
Timeouts: Handoffs timeout after 5 minutes

API Reference

Agent Module

Agent module with handoff support

AgentConfig

Agent configuration

Best Practices

Create focused specialists

Each agent should handle one domain well. This makes handoffs accurate.

Write clear descriptions

The main agent uses descriptions to decide when to transfer.

Explain transfers to users

Let users know they’re being connected to a specialist.

Agent

Create AI agents

Teams

Multi-agent teams

​Quick Start

​User Interaction Flow

​Configuration Levels

​When to Transfer

​Safety Features

​API Reference