A transfer an agent's model may make to another agent of its family. build() compiles the root and every agent reachable through handoffs into one graph, keyed by agent id. The model is offered the handoff as a tool named handoff_to_<id>; calling it, as the only call of its message, moves the conversation to the target, which stays active - the next turn starts with it
- until it hands off again.
The target is either a builder (Handoff.to, Handoff.of), which brings that agent into the family, or an agent id alone (Handoff.toId), which names an agent some builder of the family defines. Builders are immutable, so a cycle - the specialist handing back to the agent that handed to it - names the earlier agent by id:
val physics = Agent.builder("physics", client)
.withSystemPrompt("You are a physicist.")
.withHandoffs(Handoff.toId("triage", "Questions that are not about physics"))
val triage = Agent.builder("triage", client)
.withHandoffs(Handoff.to("physics", physics, "Requires physics expertise"))
.build()
Value parameters
- id
-
the target's agent id,
[a-zA-Z0-9_-]{1,52};build()refuses one that differs fromtarget's, and an id-only target no builder of the family defines - preserveContext
-
when
false, the target is sent only the user's last question before the transfer and the transfer onwards; the stored history is unchanged either way - target
-
the agent to hand off to, or
Nonewhen it is named byidalone - transferReason
-
offered to the model in the handoff tool's description
Attributes
- Companion
- object
- Graph
-
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass Any