How to transfer control permanently to another agent

Back to how-to guides Use this pattern when a specialist must own the rest of the conversation and the calling agent has no more work to do.

Concept

A permanent handoff sets RETURN: false on a HANDOFF route. RETURN: false is the default. A route with no RETURN line is permanent. EXPECT_RETURN: false is the same setting. When the route fires, ownership moves in four steps.

The calling agent thread ends.
The target becomes the active agent.
The target answers this turn and every later turn.
No value returns to the caller, and ON_RETURN never runs.

The calling agent does not see later messages. The target keeps the conversation until it completes, escalates, or hands off again. Give the target its own HANDOFF entries when it must switch again.

Question	Permanent (`RETURN: false`)	Returnable (`RETURN: true`)
Who owns the next turns?	The target, for good.	The child, until it returns.
What happens to the caller?	Its thread ends.	It waits.
Do values come back?	No.	Yes, through `ON_RETURN` `MAP`.

See Switch the active agent for how HANDOFF changes the active agent. See Returnable handoff when the caller must continue. See Use handoff instead of delegate to choose between HANDOFF and DELEGATE.

Route settings

Setting	Default	Effect
`TO`	None	The target agent. It must exist in the project.
`WHEN`	None	The condition that selects the route. Use a deterministic expression or quoted natural language.
`ENABLED_WHEN`	Always on	Switches the route on or off for the session.
`PRIORITY`	None	Lower values run first when several routes match.
`PASS`	Nothing	Parent variables the target receives.
`SUMMARY`	Empty	The reason for the handoff. The target sees it.
`HISTORY`	`full`	How much conversation the target receives.
`ON_FAILURE`	`continue`	What happens when the handoff fails before the target accepts.
`RETURN`	`false`	Whether control comes back.

HISTORY accepts full, auto, none, summary_only, and a last_n block. auto uses summary_only when SUMMARY has text. Otherwise it passes the last five messages. A project default can change the full default. ON_FAILURE accepts continue, ESCALATE, and RESPOND "message". It runs when the runtime cannot start the handoff. It does not run when the target later fails on its own.

Hand-back to the supervisor

A permanent specialist can hand the conversation back to the supervisor that started it. Add a HANDOFF to that supervisor in the specialist. These rules apply.

Only the direct parent qualifies. An older ancestor does not.
The specialist must have its own HANDOFF to the parent.
The ENABLED_WHEN of that route still applies.
A parent that already took part in the same call chain stays blocked. The runtime refuses it as a cycle.
For a specialist with a FLOW, the hand-back works only while the FLOW is live. After the FLOW reaches COMPLETE, the parent frame is closed.

A refused hand-back ends with handoff_completed outcome: rejected and code: recursion. The trace can also show handoff_authority_denied.

Handoff to a human agent

A HANDOFF target is always an agent in the project. It is never a person. To reach a human, use one of these paths.

Path	Use when
Hand off permanently to an agent that has an `ESCALATE` section	A route such as “customer asks for a person” owns the transfer.
Set `ON_FAILURE: ESCALATE` on the route	A failed handoff must reach a person.
Add `ESCALATE` to the permanent specialist	The specialist decides when to transfer.

See Escalate a conversation to a human for triggers and routing. See Package context for human escalation for what the human agent receives.

Minimal working example

The supervisor sends disputes to Disputes_Agent and requests for a person to Live_Agent. Both routes are permanent. Disputes_Agent can hand back to the supervisor. customer_id is a project-local assumption. Your channel or an earlier gate sets it before the handoff. Live_Agent is a short stand-in. Its ESCALATE section sets what the human agent receives.

SUPERVISOR: Card_Supervisor
GOAL: "Send each card request to the specialist who owns it"

INTENTS:
  dispute: "The customer disputes a card charge."
  human_request: "The customer asks for a person."

HANDOFF:
  - TO: Disputes_Agent
    WHEN: intent.category == "dispute"
    ENABLED_WHEN: _metadata.disputes_enabled != false
    CONTEXT:
      pass: [customer_id]
      summary: "The customer disputes a card charge."
      history: full
    RETURN: false
    ON_FAILURE: RESPOND "Dispute handling is not available right now."
    PRIORITY: 2

  - TO: Live_Agent
    WHEN: intent.category == "human_request"
    SUMMARY: "The customer asks for a person."
    HISTORY: summary_only
    RETURN: false
    ON_FAILURE: ESCALATE
    PRIORITY: 1

AGENT: Disputes_Agent
GOAL: "Collect the disputed charge details and resolve the dispute"

GATHER:
  charge_id:
    PROMPT: "Which charge do you dispute? Give the charge ID."
    TYPE: string
    REQUIRED: true

HANDOFF:
  - TO: Card_Supervisor
    WHEN: "the request is not about a card dispute"
    SUMMARY: "Customer needs a different specialist."
    RETURN: false

COMPLETE:
  - WHEN: charge_id IS SET
    RESPOND: "I have logged the dispute for charge {{charge_id}}."

AGENT: Live_Agent
GOAL: "Transfer the customer to a human agent with the conversation context"

ESCALATE:
  context_for_human:
    - conversation_history

How it works

The customer reports a charge problem. The supervisor classifies the intent as dispute.
ENABLED_WHEN is true unless the caller sets _metadata.disputes_enabled to false. The route is on.
The route fires. The supervisor thread ends. Disputes_Agent receives customer_id, the summary, and the full history.
Disputes_Agent asks for the charge ID. Later messages go to it and not to the supervisor.
The COMPLETE condition is true when charge_id is set. The agent confirms the dispute.
If the customer asks about something else, the model can use the route back to Card_Supervisor. The quoted WHEN is guidance. The model decides.

The WHEN and ENABLED_WHEN rules apply to a permanent route like any other route. ENABLED_WHEN decides whether the route exists. WHEN decides which available route a turn takes. A // outside quotes in a WHEN starts a comment. Use IS SET and IS NOT SET for empty variables. The check != "" is true when the value is missing. A route written without WHEN compiles without a warning. Write a WHEN on every route so the selection stays predictable.

Common variations

Write the context as shorthand

PASS, SUMMARY, and HISTORY can sit directly on the route, as the Live_Agent route shows. The CONTEXT: block groups the same values. Keys inside CONTEXT: must be lowercase. Uppercase keys inside CONTEXT: are ignored. Write a last_n history as an indented block.

HANDOFF:
  - TO: Disputes_Agent
    WHEN: intent.category == "dispute"
    PASS: [customer_id]
    SUMMARY: "The customer disputes a card charge."
    HISTORY:
      mode: last_n
      count: 6
    RETURN: false

A one-line { mode: last_n, count: 6 } and a misspelled value such as recent are ignored. The history falls back to full.

Turn a route off for some sessions

ENABLED_WHEN reads only data known before the turn, such as _metadata.*. It cannot read intent. A condition that reads a missing value turns the route off, unless it uses != true, == null, or IS NOT SET. When the route is off, the ON_FAILURE of the entry runs for an authored route. See the first route in the minimal example. Do not use ENABLED_WHEN as a security boundary. The caller supplies _metadata.

Hand back from the specialist

The Disputes_Agent entry in the minimal example is the hand-back. It targets the direct parent, so it qualifies. Add ENABLED_WHEN to that route to switch it off for some sessions. If every route in the specialist has ENABLED_WHEN, the compiler warns ENABLED_WHEN_ALL_DISABLED_RISK. The specialist then answers directly when all conditions are false.

Verification

Validate the project. Every TO target must exist.
Start a new session and send “I want to dispute a charge”. Expect a handoff event to Disputes_Agent with returnExpected: false and reasonCode: handoff_permanent.
Expect a handoff_completed event with outcome: success and durationMs.
Send another message. Expect Disputes_Agent to answer. The supervisor does not run.
Send “I want to talk to a person” in a new session. Expect a handoff to Live_Agent.
In Disputes_Agent, send an unrelated request. Expect a handoff to Card_Supervisor with returnExpected: false.
Send _metadata.disputes_enabled as false. Expect the supervisor not to offer the route. A forced attempt shows outcome: blocked.

`outcome`	Meaning
`success`	The target accepted and ran.
`rejected`	The runtime refused the route, for example a cycle.
`blocked`	A `WHEN` was false, `ENABLED_WHEN` switched the target off, or authentication was required.
`error`	Setup or dispatch failed, or an error was thrown.
`timeout`	The runtime stopped waiting for the target.

The event also has cause and code on a failure, and siblingIntentMs when a queued sibling request ran inside the attempt.

Production readiness checklist

Every TO target exists. Replace the stand-in agents with real agents.
The target has its own exit: a COMPLETE condition, an ESCALATE section, or a HANDOFF. A permanent target without an exit keeps the conversation.
Variables in PASS have a source. customer_id here comes from your channel or an earlier gate.
Each route sets ON_FAILURE on purpose.
A human path exists, and the human agent receives the context it needs.
Tests cover each route, a route that is switched off, a hand-back, a refused hand-back, and a message that matches no route.
Trace checks cover handoff and handoff_completed.

Common mistakes

Mistake	Why it happens	How to avoid it
Expecting the supervisor to see later messages	The thread looks shared.	After `RETURN: false`, only the target answers.
Relying on the default `RETURN: false` for a gate	`RETURN: true` is missing.	Write `RETURN: true` for gates. See Returnable handoff.
Writing `RETURN: True` or `RETURN: "true"`	Only lowercase `true` reads as true.	Write `RETURN: true`.
Adding `ON_RETURN` to a permanent route	The returnable pattern is copied.	Remove it. The compiler warns `HANDOFF_ON_RETURN_WITHOUT_RETURN`.
Using a hand-back to an older ancestor	Only the direct parent qualifies.	Hand back to the agent that handed off directly.
Treating `ENABLED_WHEN` as access control	The caller supplies `_metadata`.	Enforce access in tools and data.
Gating with `!= ""`	It reads like an empty check.	Use `IS NOT SET`.
Handing off to a person by name	`TO` accepts agents only.	Hand off to an agent with `ESCALATE`.

Troubleshooting

Symptom	Likely cause	What to check
The route never fires	The `WHEN` is false, or the route is off.	`handoff_condition_check` and the `ENABLED_WHEN` condition.
The wrong specialist answers	Two routes match.	`PRIORITY` and the `WHEN` conditions.
`handoff_completed` shows `blocked`	The `WHEN` is false, `ENABLED_WHEN` switched the target off, or authentication is required.	The trace `cause` and `code`, and the auth profile.
The hand-back is refused	The target is not the direct parent, it is already unwound, or `ENABLED_WHEN` is false.	`handoff_authority_denied` and the route in the specialist.
The specialist cannot hand back	The specialist has no `HANDOFF` to the supervisor.	The specialist `HANDOFF` section.
The conversation never ends	The target has no exit.	`COMPLETE`, `ESCALATE`, and `HANDOFF` in the target.
The target asks for what the customer already said	The route passes no field, or the history is limited.	`PASS`, `HISTORY`, and the target `GATHER`.
The human agent gets no context	The `ESCALATE` section has no `context_for_human`.	The `ESCALATE` section of the agent that escalates.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

How to transfer control permanently to another agent

Concept

Route settings

Hand-back to the supervisor

Handoff to a human agent

Minimal working example

How it works

Common variations

Write the context as shorthand

Turn a route off for some sessions

Hand back from the specialist

Verification

Production readiness checklist

Common mistakes

Troubleshooting

​Concept

​Route settings

​Hand-back to the supervisor

​Handoff to a human agent

​Minimal working example

​How it works

​Common variations

​Write the context as shorthand

​Turn a route off for some sessions

​Hand back from the specialist

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

Concept

Route settings

Hand-back to the supervisor

Handoff to a human agent

Minimal working example

How it works

Common variations

Write the context as shorthand

Turn a route off for some sessions

Hand back from the specialist

Verification

Production readiness checklist

Common mistakes

Troubleshooting