PlatformHeaders Class

Definition

Namespace:
Azure.AI.AgentServer.Core
Assembly:
Azure.AI.AgentServer.Core.dll
Package:
Azure.AI.AgentServer.Core v1.0.0-beta.26
Source:
PlatformHeaders.cs

Defines the HTTP header names used across the AgentServer platform. These headers form the wire contract between the Foundry platform, agent containers, and downstream storage services.

public static class PlatformHeaders
type PlatformHeaders = class
Public Class PlatformHeaders
Inheritance
Object
PlatformHeaders

Remarks

Response headers (set by the server on every response):

Error response headers (set on 4xx/5xx responses):

  • ErrorSource — classifies error origin (user, platform, or upstream).
  • ErrorDetail — internal diagnostic detail for platform telemetry.

Request headers (set by the platform or client):

  • RequestId — client-provided correlation ID (echoed back on the response).
  • UserId — global, cross-agent per-user partition key.
  • FoundryCallId — opaque per-request call identifier (protocol 2.0.0).
  • ClientHeaderPrefix — prefix for pass-through client headers.
  • TraceParent — W3C Trace Context propagation header.
  • ClientRequestId — Azure SDK client correlation header.

Fields

Name Description
ClientHeaderPrefix

The prefix x-client- for pass-through client headers. All request headers starting with this prefix are extracted and forwarded to the handler via the invocation context.
ClientRequestId

The x-ms-client-request-id header — Azure SDK client correlation header. Logged for diagnostic correlation with upstream Azure SDK callers.
ErrorDetail

The x-platform-error-detail header — internal diagnostic detail for platform telemetry. Not intended for end-user display. Present on error responses when additional diagnostic context is available.
ErrorSource

The x-platform-error-source header — classifies every error response so the platform can route actionable errors to the right team. Present on all 4xx/5xx responses from protocol endpoints. Values: user, platform, upstream.
ErrorSourcePlatform

Error source value indicating the error was caused by the SDK, library, or a platform dependency — not by the caller or the developer's handler.
ErrorSourceUpstream

Error source value indicating the developer's handler code or an external service it called failed or returned incorrect behaviour.
ErrorSourceUser

Error source value indicating the caller's input is invalid. The caller can fix the request and retry.
FoundryCallId

The x-agent-foundry-call-id header — the platform-minted opaque per-request call identifier. Present only on container protocol version 2.0.0. The container must forward this value on outbound calls to Foundry platform services (Storage, Toolboxes/MCP, A2A) so that 1P services resolve the server-side-stored caller context. Never parsed.
RequestId

The x-request-id header — carries the request correlation ID. On responses, the server always sets this header (OTEL trace ID → incoming header → GUID). On requests, clients may set it to provide their own correlation ID.
RequestIdItemKey

Key used to store the resolved request ID in Items. Downstream filters and middleware can read this value to correlate the request ID without re-resolving it.
ServerVersion

The x-platform-server header — identifies the server SDK stack (hosting version, protocol versions, language, and runtime). Set on every response by ServerVersionMiddleware.
SessionId

The x-agent-session-id header — the resolved session ID for the request. Set on responses by protocol-specific session resolution logic.
TraceParent

The traceparent header — W3C Trace Context propagation header. Used for distributed tracing correlation on outbound storage requests.
UserId

The x-agent-user-id header — the platform-injected global, cross-agent partition key for per-user state. The same user yields the same value regardless of which agent they interact with. Consumed container-side for per-user state partitioning; it is not forwarded on outbound 1P calls (not accepted/trusted by 1P services).

Applies to