Handoffs

Agent-to-agent task delegation in PraisonAI Rust SDK

Handoffs enable agents to delegate tasks to specialized agents, with built-in safety features like cycle detection and depth limits.

Quick Start

1. Create a Handoff

   use praisonai::Handoff;
   
   // Create a handoff to a specialist agent
   let handoff = Handoff::new("CodeReviewer")
       .tool_description("Transfer to code review specialist");
   
   // The handoff is represented as a tool to the LLM
   println!("Tool name: {}", handoff.get_tool_name());
   // Output: "transfer_to_code_reviewer"

2. Configure Handoff Behavior

   use praisonai::{Handoff, HandoffConfig, ContextPolicy};
   
   let config = HandoffConfig::new()
       .context_policy(ContextPolicy::LastN)
       .max_context_messages(5)
       .max_depth(3)
       .detect_cycles(true);
   
   let handoff = Handoff::new("Specialist")
       .config(config)
       .tool_name("delegate_to_expert")
       .tool_description("Transfer complex tasks to the expert");

3. Execute a Handoff

   use praisonai::{Handoff, HandoffInputData, HandoffResult};
   
   let handoff = Handoff::new("Specialist");
   
   // Create input data for the handoff
   let input = HandoffInputData::new("Process this request");
   
   // Execute the handoff (returns HandoffResult)
   let result: HandoffResult = handoff.execute(input).await?;
   println!("Result: {}", result.response);

User Interaction Flow

Handoff

Main struct for defining agent-to-agent transfers.

pub struct Handoff {
    pub target_agent_name: String,
    pub tool_name_override: Option<String>,
    pub tool_description_override: Option<String>,
    pub config: HandoffConfig,
}

Methods

) -> Self | Create handoff to target agent | | tool_name(name) | fn tool_name(self, impl Into

) -> Self | Override tool name | | tool_description(desc) | fn tool_description(self, impl Into

) -> Self | Override description | | config(cfg) | fn config(self, HandoffConfig) -> Self | Set configuration | | get_tool_name() | fn get_tool_name(&self) -> String | Get resolved tool name | | check_safety(source, chain) | fn check_safety(&self, &str, &HandoffChain) -> Result<()>` | Verify safety |

HandoffConfig

Configuration for handoff behavior and safety.

pub struct HandoffConfig {
    pub context_policy: ContextPolicy,
    pub max_context_tokens: usize,
    pub max_context_messages: usize,
    pub preserve_system: bool,
    pub timeout_seconds: f64,
    pub max_concurrent: usize,
    pub detect_cycles: bool,
    pub max_depth: usize,
    pub async_mode: bool,
}

Configuration Options

Builder Methods

ContextPolicy

Controls how context is shared during handoffs.

pub enum ContextPolicy {
    Full,           // Share entire conversation
    Summary,        // Summarize conversation (default)
    LastN,          // Last N messages only
    Custom(String), // Custom handling
}

HandoffResult

Result returned from handoff execution.

pub struct HandoffResult {
    pub success: bool,
    pub response: Option<String>,
    pub target_agent: Option<String>,
    pub source_agent: Option<String>,
    pub duration_seconds: f64,
    pub error: Option<String>,
    pub handoff_depth: usize,
}

Factory Methods

) -> Self | Create success result | | failure(error) | fn failure(impl Into

) -> Self` | Create failure result |

Builder Methods

) -> Self | Set target agent | | with_source(agent) | fn with_source(self, impl Into

) -> Self | Set source agent | | with_duration(seconds) | fn with_duration(self, f64) -> Self` | Set duration |

Safety Features

Cycle Detection

Prevents infinite loops between agents.

let config = HandoffConfig::new()
    .detect_cycles(true);

// A -> B -> A would be detected and blocked

Depth Limits

Limits how deep handoff chains can go.

let config = HandoffConfig::new()
    .max_depth(5);

// Prevents A -> B -> C -> D -> E -> F (would be blocked at F)

Best Practices

Related