Skip to main content
Handoffs wrap a specialist Agent as a Tool the parent can call. Two entry points:
  • handoff() — recommended shorthand
  • createHandoff() — full options object

handoff(agent, description, options?)

Shorthand for the most common case.

Parameters

Agent
required
The specialist agent to delegate to.
string
required
Shown to the parent model — explain when to use this specialist.
HandoffOptions
Optional configuration (see below).

createHandoff(options)

Full form when you need an explicit tool name or all options in one object.

HandoffOptions

string
Short identifier used to build the tool name (handoff_<id>). Provide id or name, not both required.
string
Explicit tool name. Overrides auto-generated handoff_<id>.
string
required
When the parent model should call this handoff.
Agent
required
Specialist agent instance.
"full" | "summary" | "none"
default:"full"
How much parent conversation history to pass to the sub-agent.
(event: AgentEvent) => void
Callback for events inside the sub-agent run.
number
Max turns for the sub-agent run (forwarded to subAgent.run()).

Tool schema

Every handoff exposes a single argument to the parent model:
The parent model fills task when it decides to delegate.

Return value

The handoff tool’s execute returns a plain text string — the sub-agent’s final result.text. It is not wrapped in an object.