Praison AI

Handoff

Enable agent-to-agent task delegation for complex workflows

The --handoff flag enables agent-to-agent task delegation, allowing multiple specialized agents to collaborate on complex tasks.

Quick Start

bash
praisonai "Research and write article" --handoff "researcher,writer,editor"

Usage

Basic Handoff

bash
praisonai "Research AI trends and write a blog post" --handoff "researcher,writer"

Expected Output:

🤝 Handoff enabled: researcher → writer

╭─ Agent Chain ────────────────────────────────────────────────────────────────╮
│  1. 🔍 researcher - Research AI trends                                       │
│  2. ✍️  writer - Write blog post based on research                           │
╰──────────────────────────────────────────────────────────────────────────────╯

━━━ Agent 1: researcher ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Researching AI trends...

Key findings:
• Generative AI adoption increased 300% in 2024
• Multi-agent systems gaining popularity
• Edge AI deployment growing rapidly

→ Handing off to: writer

━━━ Agent 2: writer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Writing blog post based on research...

╭────────────────────────────────── Response ──────────────────────────────────╮
│ # AI Trends Shaping 2024                                                     │
│                                                                              │
│ The artificial intelligence landscape has undergone remarkable               │
│ transformation this year. Here are the key trends...                        │
│                                                                              │
│ ## 1. Generative AI Goes Mainstream                                         │
│ With a 300% increase in adoption, generative AI has moved from...           │
╰──────────────────────────────────────────────────────────────────────────────╯

✅ Handoff chain completed successfully

Multi-Agent Chain

bash
praisonai "Analyze data and create report" --handoff "analyst,visualizer,writer,reviewer"

Expected Output:

🤝 Handoff enabled: analyst → visualizer → writer → reviewer

╭─ Agent Chain ────────────────────────────────────────────────────────────────╮
│  1. 📊 analyst - Analyze the data                                           │
│  2. 📈 visualizer - Create visualizations                                   │
│  3. ✍️  writer - Write the report                                            │
│  4. 🔍 reviewer - Review and finalize                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

━━━ Agent 1: analyst ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Analysis output...]
→ Handing off to: visualizer

━━━ Agent 2: visualizer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Visualization output...]
→ Handing off to: writer

━━━ Agent 3: writer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Report draft...]
→ Handing off to: reviewer

━━━ Agent 4: reviewer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Final review and output...]

✅ Handoff chain completed successfully

Handoff Configuration Options

bash
# Context policy - control what context is shared
praisonai "Task" --handoff "a,b" --handoff-policy summary

# Timeout - set execution timeout
praisonai "Task" --handoff "a,b" --handoff-timeout 60

# Max depth - limit handoff chain depth
praisonai "Task" --handoff "a,b" --handoff-max-depth 5

# Max concurrent - limit concurrent handoffs
praisonai "Task" --handoff "a,b" --handoff-max-concurrent 3

# Cycle detection - enable/disable
praisonai "Task" --handoff "a,b" --handoff-detect-cycles true

Context Policies

PolicyDescription
fullShare full conversation history
summaryShare summarized context (default)
noneNo context sharing
last_nShare last N messages

Combine with Other Features

bash
# Handoff with metrics
praisonai "Complex task" --handoff "agent1,agent2" --metrics

# Handoff with guardrail
praisonai "Write code" --handoff "coder,reviewer" --guardrail "Follow best practices"

# Handoff with memory
praisonai "Research project" --handoff "researcher,writer" --auto-memory

# Handoff with custom config
praisonai "Task" --handoff "a,b,c" --handoff-policy summary --handoff-timeout 120 --handoff-max-depth 5

YAML Equivalent

Every --handoff* flag has a YAML equivalent under the agent’s handoff: block:

yaml
roles:
  coordinator:
    role: Coordinator
    handoff:
      to: [writer, reviewer]
      policy: summary
      timeout: 120
      max_depth: 5

How It Works

Diagram

Prompt

Agent 1

Handoff

Agent 2

Handoff

Agent 3

Final Output

  1. Parse Agents: The handoff string is parsed into agent names
  2. Create Chain: Agents are created with handoff capabilities
  3. Sequential Execution: Each agent processes and hands off to the next
  4. Context Passing: Previous agent’s output becomes next agent’s input
  5. Final Output: Last agent’s response is returned

Agent Naming

Agents are automatically configured based on their names:

NameRoleGoal
researcherResearch SpecialistFind and analyze information
writerContent WriterCreate written content
editorEditorReview and improve content
analystData AnalystAnalyze data and patterns
coderDeveloperWrite and review code
reviewerReviewerReview and validate work
plannerPlannerCreate plans and strategies

Custom Agent Names

You can use any name – agents will be configured with generic roles:

bash
praisonai "Task" --handoff "custom_agent1,custom_agent2"

Use Cases

Content Creation Pipeline

bash
praisonai "Write a technical blog about Kubernetes" \
  --handoff "researcher,writer,editor"

Code Review Workflow

bash
praisonai "Review and improve this code" \
  --handoff "analyzer,refactorer,reviewer" \
  --fast-context ./src

Data Analysis Pipeline

bash
praisonai "Analyze sales data and create executive summary" \
  --handoff "analyst,visualizer,writer"

Research to Report

bash
praisonai "Research quantum computing advances and write a report" \
  --handoff "researcher,fact_checker,writer,editor"

Handoff Patterns

Research → Write
bash
--handoff "researcher,writer"

Research a topic, then write about it

 Code → Review
bash
--handoff "coder,reviewer"

Write code, then review it

 Analyze → Report
bash
--handoff "analyst,writer"

Analyze data, then create report

 Plan → Execute → Review
bash
--handoff "planner,executor,reviewer"

Full workflow with planning

Best Practices

Logical Order

Arrange agents in a logical workflow sequence

 Specialized Agents

Use descriptive names that indicate specialization

 Chain Length

Keep chains to 2-4 agents for efficiency

 Clear Tasks

Ensure each agent has a clear, distinct role

Monitoring Handoffs

Use --metrics to see token usage across all agents:

bash
praisonai "Task" --handoff "a1,a2,a3" --metrics

Expected Output:

📊 Handoff Metrics:
┌─────────────────────┬──────────────┐
│ Agent               │ Tokens       │
├─────────────────────┼──────────────┤
│ a1 (researcher)     │ 523          │
│ a2 (writer)         │ 1,247        │
│ a3 (editor)         │ 456          │
├─────────────────────┼──────────────┤
│ Total               │ 2,226        │
│ Estimated Cost      │ $0.0134      │
└─────────────────────┴──────────────┘

Related