Skip to main content

Agent Handoff

Agent Handoff enables seamless mid-conversation transfers between agents. When a user’s request falls outside the current agent’s expertise, it can transfer to a specialist agent while carrying over the full conversation context.

Quick Start

How It Works

  1. The agent receives a transfer_to_agent tool based on the configured targets
  2. When the LLM decides a handoff is needed, it calls the tool with the target agent name
  3. The HandoffManager catches the signal and transfers the conversation
  4. The target agent receives the full conversation history and continues naturally

Configuration

Team Handoff Mode

For managed teams, use TeamMode.Handoff:

Events


Cycle Detection

Agentium prevents infinite handoff loops automatically. If agent A hands off to agent B, which hands off back to A, the system detects the cycle and stops:

onHandoff Callback

Use onHandoff to log, validate, or modify behavior when a handoff occurs:

The Complete Tool

Each agent in a handoff chain receives a complete tool. Calling it signals that the task is done and no further handoffs are needed:

Cross-References

  • Teams — Team orchestration modes (Handoff, Broadcast, Sequential)
  • Events — Listen for handoff.transfer and handoff.complete events
  • Observability — Trace handoff chains across agents