Skip to content

ADR-0010: Trace-Native Inference and Observability

Status

Accepted — 2026-08-31

Context

Mission Control previously modeled every external and managed execution as a platform-owned Run with explicit start/finalize routes, custom telemetry upload, Run-scoped permissions, and separate Chat token routes. That lifecycle duplicated standards already carried by W3C Trace Context, OpenTelemetry, and AG-UI, split one inference attempt across several owners, and made correlation look like authority.

The gateway must preserve Chat Completions while adding a strict Responses subset, work across explicitly supported OpenAI-compatible provider capabilities, and provide one authorization-aware investigation model for direct model, MCP, and managed Agent traffic. Provider-hosted internal operations are not consistently portable across providers and require a separate design.

Decision

  • The public inference listener exposes exactly GET /v1/models, POST /v1/chat/completions, POST /v1/responses, POST /mcp, and POST /v1/agents/{agentId}:invoke.
  • A separate private listener exposes health, readiness, configuration, telemetry identity/binding, and component heartbeat routes. Neither listener mounts the other's routes.
  • Every accepted inference request carries or receives caller-owned W3C Trace context. Mission Control records request spans and Trace-scoped evidence; it does not open, close, finalize, or own a Trace lifecycle resource.
  • Standard OTLP HTTP/protobuf and gRPC are the only observation transports. External exporters authenticate with an Agent key; the managed runtime uses signed workload identity. Correlation never grants authority.
  • AG-UI adapters normalize managed Agent stream vocabulary and feed a content-free trajectory. AG-UI runId and RUN_* names remain protocol fields only and create no Mission Control Run.
  • Optional bounded client Session IDs group authorized Agent Traces without lifecycle or permission semantics.
  • The Console exposes authorization-aware Logs, Traces, Sessions, and Metrics over authoritative gateway evidence plus independently observed spans and trajectory.
  • Provider-hosted tools and provider-internal operation parsing remain deferred. The gateway rejects unsupported capabilities instead of approximating them or inventing internal operations.
  • The development cutover is big-bang: old Run/application/observation stores and /runs, /runtime/v1/*, and /apps/v1/* routes are removed with no compatibility layer or historical data migration.

2026-09-24: current routes, keys and navigation

The route list, "Agent key" wording and Console views above describe the release this record was written for. External code now uses ordinary user or service-account virtual keys, managed deployments are invoked at POST /v1/deployments/{deploymentId}:invoke, and Observe offers Requests, Traces, Sessions and Usage. Current release holds the current contract.

Consequences

  • Chat Completions remains a supported peer of the stateless Responses subset.
  • The gateway owns authorization, admission, routing, evidence intent, and provider/Connector request state. Adapters translate protocols but do not define a second lifecycle.
  • Governed evidence, observed spans, and AG-UI trajectory retain distinct trust and grain even when they share a Trace ID.
  • Operators use one Observability workspace and explicit partial/unknown states instead of reconstructing a platform Run.
  • Deployments must replace all components and empty development storage as one compatible set.

Superseded decisions

This decision supersedes ADR-0007 completely. It supersedes the Run lifecycle, managed per-run key, chat-token, /apps/v1, and Run-visibility portions of ADR-0008. ADR-0008's managed draft/version/publication, local transcript, approval, and private runtime boundaries remain accepted.

Rejected alternatives

  • Keep /runs as a compatibility alias. Rejected because it preserves two lifecycle authorities and contradicts the empty-development cutover.
  • Open and close a Trace around each gateway request. Rejected because a Trace is caller-owned distributed context, not a server lifecycle record.
  • Make AG-UI the governed evidence source. Rejected because adapter events describe application trajectory, not authorization or provider/Connector execution facts.
  • Blindly forward provider-specific Responses fields. Rejected because OpenAI-compatible providers do not expose identical capabilities; adapters must advertise and enforce explicit support.