handoff_release

Return control of a received handoff back to the originating agent’s visitor.

handoff_release

Returns control of a received handoff back to the originating agent’s visitor. Used by the receiving side of a sibling-agent handoff to finish its work and hand back, rather than waiting for a release token or idle timeout.

The tool is only registered when this turn is the receiving side of a sibling-agent handoff — it doesn’t appear on regular conversations or when the agent itself initiated the handoff.

Parameters

Name	Type	Required	Description
summary	string (1-2000)	yes	Short note of what you did during this handoff. Written into the audit log and shown to the originator.
outcome	"resolved" | "cannot_help" | "transferring" | "no_action"	no	Default "resolved".
reason	string (≤2000)	no	Optional extra context for the audit log.
return_values	object	no	Key/value object matching the originator’s expected_return schema (shown to you in the [EXPECTED RETURN SCHEMA] block of your initial context).

Filling return_values

When the originator declared an expected_return schema, your initial context contains an [EXPECTED RETURN SCHEMA] block listing the field names, types, and which are required. Populate return_values with keys matching those names:

{
  "summary": "Looked up order 1234 — shipped two days ago via FedEx.",
  "outcome": "resolved",
  "return_values": {
    "order_status": "shipped",
    "tracking_url": "https://www.fedex.com/track/abc123",
    "eta_date": "2026-06-10"
  }
}

Each value is coerced to the declared type — strings to strings, "yes"/"true"/"1" to true for booleans, numeric strings to numbers, etc. Missing required fields are logged but do NOT block the release (best-effort).

Returns

{
  "ok": true,
  "session_id": "...",
  "status": "released",
  "outcome": "resolved",
  "return_values": { "order_status": "shipped", "..." : "..." },
  "missing_required": ["foo"]
}

return_values and missing_required are present only when relevant.

What the originator sees

After release, the originator’s chat receives a [Bot resumed — the sibling agent has handed control back. Outcome: resolved. <summary>] system message, with a Returned data: block appended when values were filled. The originator’s LLM reads these on its next turn.

Notes

• The originator’s bot is bypassed during the handoff — calling this tool is what wakes it back up.
• If you cannot help, set outcome: "cannot_help" so the originator’s LLM knows to try something else rather than parroting your summary as a final answer.
• See handoff_request for the originator-side tool and the expected_return schema.