Handoff

A handoff is the API telling your application that control should pass back to it: the user asked for a human, declined AI triage, or wants something triage cannot do. The conversation does not end — you decide what happens next.

Handoff detection is opt-in per conversation through handoff_policies in settings. An empty list, which is the default, disables it entirely.

Enabling detectors

{
  "settings": {
    "handoff_policies": ["stop_intent_handoff", "pre_triage_handoff"]
  }
}

Values must be known policy members; anything else is rejected as a validation error.

Receiving a handoff

A handoff record surfaces in two places, depending on transport:

• Blocking turns — the handoff field on the Turn, null when none was recorded.
• Streaming and WebSocket — a conversation.handoff.requested event, emitted only when at least one detector is enabled.

{
  "type": "conversation.handoff.requested",
  "handoff": {
    "reason": "stop_intent_detected",
    "user_request": "Can I talk to a real doctor?"
  }
}

What your application does

The API records the handoff and keeps the conversation usable; routing is yours. Typical responses:

• transfer to a live agent, passing user_request along as context;
• switch the user into a different workflow — appointment booking, prescription renewal — when the reason is non_triage_intent_detected;
• offer a choice between continuing triage and leaving.

You can also read the current assessment at the moment of handoff and hand the partial triage state to whoever takes over.