Agent as a Tool the parent can call. Two entry points:
handoff()— recommended shorthandcreateHandoff()— 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:task when it decides to delegate.
Return value
The handoff tool’sexecute returns a plain text string — the sub-agent’s final result.text. It is not wrapped in an object.
Related
Agent.spawn()— used internally; also available for custom sub-agent flows- Handoffs concept guide — patterns and examples