Skip to main content
Agents can transfer conversations to other specialized agents when needed.

​
Quick Start

1

Create Agent with Handoffs

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
2

With Descriptions

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 TopicBest Agent
Payment questionsBilling Agent
Technical issuesSupport Agent
Product inquiriesSales Agent
General questionsMain 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

Each agent should handle one domain well. This makes handoffs accurate.
The main agent uses descriptions to decide when to transfer.
Let users know they’re being connected to a specialist.

Agent

Create AI agents

Teams

Multi-agent teams