Response headers

Every x-agent-stream-* response header a surface can return, and whether it appears on a buffered or a streamed response.

Every x-agent-stream-* header below is the exact header name Agent Stream sends, not a paraphrase. A client can read cost and usage figures directly from these headers without parsing the response body.

Every-request headers

Built once per completed LLM-surface execution and attached to the response.

HeaderMeaningBufferedStreamed
x-agent-stream-trace-idRequest trace id.YesYes
x-agent-stream-providerUpstream provider that served the call.YesYes
x-agent-stream-modelModel identifier.YesYes
x-agent-stream-cacheCache status: hit or miss.YesYes (always miss, a stream is never served from cache)
x-agent-stream-input-tokensInput tokens for the execution.YesNo
x-agent-stream-output-tokensOutput tokens for the execution.YesNo
x-agent-stream-total-tokensTotal tokens for the execution.YesNo
x-agent-stream-cached-tokensProvider-side cached input tokens.YesNo
x-agent-stream-cache-write-tokensProvider-side cache-write tokens.YesNo
x-agent-stream-reasoning-tokensReasoning tokens, for a reasoning-capable model.YesNo
x-agent-stream-cost-usdUSD cost for the execution, to 6 decimal places.YesNo
x-agent-stream-cache-saved-usdProvider spend avoided by a cache hit. Present only on a cache-hit response.Only on a cache hitNo

A streamed response is returned before the completion (and so its tokens/cost) is known, so it carries only the request-time subset (trace id, provider, model, and a fixed cache: miss) set at stream start, not the token/cost/cache-saved fields above.

Conditional headers

Present only when the surface used the corresponding feature for this request; absent otherwise.

HeaderMeaningPresent when
x-agent-stream-schema-validWhether the response conformed to the requested structured-output schema.The request asked for a structured output.
x-agent-stream-context-transformWhich context-window compression strategy ran.Context-window compression fired for this request.
x-agent-stream-documentsDocument-ingestion summary for the request.The request included ingested documents.
x-agent-stream-audioAudio-input handling summary for the request.The request included audio input.
x-agent-stream-imagesImage-input handling summary for the request.The request included image input.

Negotiated dialect

HeaderMeaningBufferedStreamed
x-agent-stream-ingress-skinThe negotiated client dialect (openai_chat, anthropic_messages, openai_responses), set on the outer response regardless of success/error/stream.YesYes

API-pipe conversation header

HeaderMeaningPresent when
x-agent-stream-conversation-idServer-assigned conversation id for an API-type surface, so the client can send it back on the next turn.The surface is an API pipe (not an LLM chat surface) and assigned a conversation id.

Inbound-only headers

These are headers a caller sends, not response headers: listed here because they share the x-agent-stream-* / X-Agent-Stream-* prefix and are easy to mistake for response headers.

HeaderMeaning
X-Agent-Stream-Presentation (configurable name)Default header name a caller uses to present verifiable-presentation (VP) evidence, when a surface’s VP evidence source is header.
X-Agent-Stream-Upstream-AuthorizationLets a caller supply a distinct upstream credential (e.g. a Microsoft Graph token for Copilot) alongside the front-door token, separate from the surface’s own configured provider auth.
  • Telemetry and exports: The per-request telemetry record these headers are derived from.
  • Observability concept: Why these figures are exposed on the response rather than only in the dashboard.
  • Server tools and modalities: The document/audio/image ingestion and context-compression features the conditional headers report on.
  • Providers: Upstream provider auth, including the upstream-authorization override header.