Preserve the complete protocol envelope

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

An agent response contains text, a tool call and opaque continuation state. You need both display and tool-loop continuation. The teaching envelope has text ‘Checking’, tool_call id=call-7 and opaque content. Its host requires necessary blocks/order on continuation and a result referencing call-7. These are illustrative fields, not a complete SDK schema.

Mechanism

Store the permitted full structured response and dispatch by block type rather than treating displayed text as complete state. Extract text separately for UI, match results to original IDs and preserve necessary opaque blocks under the host contract. Establish allowed retention/replay/transformation first. Report missing state instead of reconstructing it from a summary or fabricated ciphertext.

Bad example

Save only the text block and discard the rest. Rebuild the next request from 'we were checking' and invent a tool-call ID for the result.

Good example

Retain the response envelope under the teaching host contract; display extracts text only. Process tool_call using original call-7 and reference call-7 in its result. Preserve required typed blocks, order and opaque content during continuation without decrypting or rewriting it. Report missing necessary state rather than rebuilding from display text. Check the real host's retention/replay contract before implementation.

Why the change matters

Text is a presentation view; tool identities and opaque blocks carry continuation state. Separating display from the full envelope prevents presentation processing from deleting required material and makes result-to-call identity inspectable.

Observable expectation

Compare stored and continued fixtures: call-7 matches, required opaque content is unchanged and no result binds to another ID. Text-only display does not reduce protocol storage.

Removing a required block should yield an explicit incomplete state. Summary-only continuation, silently discarded unknown types or invented opaque content fail the contract.

Limits

Retention, signatures, server tools and pauses differ by API; frozen source versions do not establish current SDK behavior. Follow privacy and retention rules instead of indefinitely storing secrets for completeness. Replay only permitted content. No real API was called here.