Skip to main content
A handoff lets a model transfer the current request to a configured specialist. Use it when the specialist should continue the work. For an application-defined sequence, use a Workflow; for coordinated members, compare Team modes.

Quick Start

This host function accepts a configured model and creates two owned Agents. Install @agentium/core and your model provider’s dependency before calling it. The input requests billing help; the model must choose the transfer tool, so inspect the event evidence instead of assuming every run transfers.
Call with I need help with my invoice. A completed transfer reports front-desk then billing; the response should ask for an invoice ID. The host owns both Agents and closes them after the request.

How It Works

  1. Agentium exposes a transfer tool for the configured targets.
  2. The model selects a target and a reason.
  3. The handoff manager validates the target and remaining hop budget, then calls any onHandoff hook.
  4. The target executes with the carried context allowed by configuration. Success emits handoff.complete.

Configuration

See handoff declarations for exact exported types. Agent.run() is declared to return RunOutput; use the documented events for transfer evidence rather than assuming result.handoffChain is part of that return type.

Team Handoff Mode

Use TeamMode.Handoff when the host already groups specialist members into a Team. The Team owns coordination; its model and member configuration still need explicit setup. Follow the Team handoff pattern for a typed composition.

Events

Subscribe to the bus used by the relevant Agents. Remove host subscriptions when their owner ends. Events observe execution; use onHandoff for a decision that must block a transfer.

Cycle Detection

Re-entering an Agent name already in the chain is rejected before the target runs. Hitting the hop limit is also an error; the manager does not silently return a successful answer from an unfinished chain. Use unique, meaningful names and test a repeated-name cycle separately from a long valid chain.

onHandoff Callback

This factory takes a borrowed specialist and a host authorization callback. The caller owns the specialist’s lifetime; the returned router must be closed when no longer needed.
Bind authorize to verified host identity and domain permissions. A session ID or model-selected target is not authorization.

Streaming and failures

Streaming handoff can emit source or target text before terminal success. A later guardrail rejection or target failure means that text is an incomplete result. Handle cancellation, iterator closure, and error events in the host. See streaming and operations for the surrounding lifecycle.