结构化交接协议

In a hub-and-spoke multi-agent system, the coordinator constantly hands work to subagents and receives results back. The CRITICAL fact: subagents do NOT inherit the coordinator's conversation history — the model keeps no state, so the FULL request history travels in messages every turn.

That means every handoff must carry its own context explicitly. An unstructured "go fix the auth bug" loses the case ID, what was already tried, and what decision the coordinator needs back. A structured handoff protocol fixes this: each transfer carries an identifier, a summary, the actions taken, and a recommendation.

A reliable handoff payload has four fields, each solving a specific failure mode:

• ID — a stable correlation key (case_id, custom_id) so results can be matched to requests, even across parallel calls.
• Summary — the verbatim transactional facts the receiver needs (verified customer ID, order number, amounts).
• Actions — what was already attempted, with results, so work isn't repeated.
• Recommendation — the proposed next step or decision the receiver must confirm or override.

This maps directly onto how coordinators decompose, delegate, aggregate, and route.

Because the subagent starts with a blank history, you cannot rely on "it already knows." Build the handoff into the subagent's prompt itself. Notice how the ID, summary, and prior actions are spelled out — nothing is assumed.

A free-text handoff is easy to malform. To guarantee all four fields are present, make the handoff a tool with a JSON Schema and use tool_choice to force structured output. tool_use + JSON Schema eliminates syntax errors and enforces required fields.

Key rule from the fact sheet: mark a field required ONLY if it is always present. id, summary, actions, and recommendation are always present in a valid handoff — so they are legitimately required. An optional field like escalation_reason must NOT be required, or the model will fabricate it.

How you set tool_choice decides whether you actually get a structured handoff:

• "auto" — the model may reply with prose instead of a handoff. Risky for protocols.
• "any" — the model MUST call some tool, guaranteeing structured output.
• {"type":"tool","name":"emit_handoff"} — forces exactly this tool. Use this when the subagent's job is to return one well-formed handoff.

The ID is what lets a coordinator aggregate results that arrive out of order. When you issue multiple Task calls in one response, they run in parallel — replies don't come back in the order you sent them. Without a correlation key you cannot map a result to its request.

This is the same principle as the Batch API's custom_id, which correlates requests so you can re-submit only the failures. In a synchronous multi-agent flow, your handoff id plays that role.

The summary is where handoffs quietly break. Progressive summarization makes numbers, percentages, and dates vague — exactly the fields a receiver needs to act ($420 becomes "a few hundred dollars"). And models attend to the start and end of context more than the middle (lost-in-the-middle).

The fix: pull transactional facts into a separate case-facts block kept verbatim, outside any prose summary. The handoff's summary field should carry these exact facts, never a lossy paraphrase.

The actions field must record not just what ran, but what each call returned — and it must distinguish an access FAILURE (maybe retryable) from a valid EMPTY result (no matches, do not retry). Use structured errors, not generic ones.

A structured error carries isError, errorCategory (transient / validation / business / permission), isRetryable, the attempted query, and partial results. Generic "Operation failed" blocks recovery; structured context lets the receiver route intelligently.

The fourth field is a recommendation the receiver can confirm or override — not a unilateral action. This keeps decision authority where it belongs and supports clean escalation.

Good escalation triggers belong in the recommendation: an explicit human request (escalate immediately), a policy gap, no progress after attempts, or a threshold violation. BAD triggers must never drive it: sentiment analysis, a model self-rated confidence score, or an untrained classifier. A recommendation reading "customer sounds frustrated, escalate" is the anti-pattern.

A handoff's recommendation is probabilistic — prompt guidance is right roughly 90% of the time. When acting on a handoff has financial, legal, or safety consequences, the guarantee must be deterministic, enforced by a hook, not by the recommendation text.

An outgoing-call hook can block a policy-violating action (e.g. refund > $500) regardless of what the subagent recommended. A programmatic precondition — block process_refund until get_customer returned a verified ID — gives a guarantee prompts cannot. Hooks = 100% deterministic; prompts ≈ 90% probabilistic.

Sometimes a handoff continues earlier work. --resume <name> continues a named session and fork_session branches from a shared point. But beware: resumed tool results can be STALE if the codebase or data changed underneath them.

When the underlying state has moved, a fresh session seeded with a structured handoff (ID + verbatim facts + actions + recommendation) is often more reliable than resuming a session full of outdated tool output. The structured handoff is what makes a clean restart cheap.

Key takeaways:

• Subagents inherit no history — every handoff carries its own context explicitly.
• Four fields: ID (correlate parallel results), summary (verbatim facts), actions (with structured errors), recommendation (confirm/override).
• Force the shape with a handoff tool + JSON Schema and tool_choice; require only always-present fields.
• Keep numbers and dates verbatim in a case-facts block — summarization makes them vague.
• In actions, distinguish access failure from a valid empty result via errorCategory and isRetryable.
• Gate consequential actions with deterministic hooks, never with the recommendation alone.
• If resumed tool output may be stale, restart fresh with the structured handoff.