Surfaces

A surface is the single configuration and runtime unit Agent Stream uses to represent one governed connection. Every capability described in the concepts section, guardrails, budgets, resilience, and attribution, attaches to a surface. Pipeline and stages →

What a surface owns

A surface owns:

• One Access Point: its front door.
• One Target: its upstream. A Target isn’t necessarily a single provider destination: it can represent failover, load balancing pools, content-aware Deciders, and aggregators.
• Variants, cache settings, guardrail chains, budgets, policy references, and integration bindings.

Administrators compose the request path visually on the surface canvas, dragging elements, Prompt Guard, Expert Witnesses, Judge, Jury, Decider, load-balancing pools, between the Access Point and Target.

Surfaces are pre-resolved into immutable in-memory snapshots at design time, so routing decisions don’t pay a per-request resolution cost. Changes hot-reload, taking effect without dropping in-flight requests.

How the two surface types differ

Agent Stream manages traffic through two surface types that share the same configuration model and access-control permissions:

The dashboard’s sidebar lists them by their short form, LLM and IDE, under a Surfaces heading. This documentation uses the fuller names LLM Surface and IDE Surface throughout.

LLM Surface

The LLM Surface is Agent Stream’s primary surface type: an LLM provider your application or agent calls out to, carrying the full guardrail, routing, resilience, and cost pipeline.

What it configures

An LLM Surface composes optional configuration blocks. Nothing is mandatory: a surface with none configured behaves as a thin, low-latency proxy, and adding a block switches on only that behaviour.

• Identity and access: source authentication, OPA policy, team attribution.
• Guardrails: prompt guard, expert witnesses, judge, jury.
• Routing and resilience: decider, routing rules, canary, variants, failover, load balancing, retry policy, circuit breaker, rate limit.
• Cost and limits: usage limits, usage alerts, cost tracking, reasoning token limits.
• Performance: cache, streaming, request timeout, accepted ingress schemas.
• Observability and compliance: metrics, request/response logging, governance recording.
• Other: server tools, context management, document ingestion.

Server tools let the appliance itself execute web_search and web_fetch calls, instead of leaving the caller’s application to run them:

• The model emits a tool call, and the appliance runs the search or fetch under policy control, a per-surface domain allow/deny list, and an SSRF guard.
• The result is injected back into the conversation and the model is re-invoked. This runs as a bounded loop, up to a configured maximum number of iterations, not an open-ended one.

See Server tools and modalities → for the full field reference, including search engines and domain-policy configuration.

What order an LLM Surface applies its stages in

Each LLM Surface applies the configured stages of Agent Stream’s pipeline in order:

1. Authenticate and gate: source authentication, rate limiting, gateway OPA policy, and team access checks.
2. Prepare and guard the request: prompt-reference expansion, response-cache lookup, Prompt Guard, and request-side Expert Witnesses.
3. Route and call the model: the Decider selects a route while the Judge pre-check runs in parallel. The call can use retry, circuit breaking, failover, and load balancing.
4. Review the response: Jury review, response-side Prompt Guard, and response-side Expert Witnesses inspect the output before it returns to the caller.
5. Record the execution: per-stage cost and token metering, telemetry emission, and configured integration delivery.

See Pipeline and stages → for the complete stage order and how unconfigured stages are skipped.

How requests and providers stay decoupled

An LLM Surface reaches one configured provider: OpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI, Microsoft 365 Copilot, Ollama (local), or an OpenAI-compatible preset (Groq, xAI, OpenRouter, Fireworks AI, Cerebras, DeepSeek, Moonshot AI, SambaNova Cloud, Hyperbolic, NVIDIA NIM, Nebius AI Studio). A provider can ship disabled in the catalogue until an administrator turns it on; the dropdown still lists it, greyed out with a “Not Available” suffix, rather than hiding it entirely. See Providers → for provider configuration.

Requests and providers are decoupled in both directions:

• Outbound: your application speaks one request shape regardless of provider. Agent Stream normalises and transforms the wire format for non-OpenAI-schema providers, such as Anthropic Messages and Gemini generateContent. Pricing, capabilities, and request profiles come from a hot-reloadable model catalogue, so a new model becomes available through the dashboard, not a code change.
• Inbound: a surface accepts requests in the OpenAI Chat Completions, Anthropic Messages, or OpenAI Responses format, selected by the endpoint path a client calls, independent of the configured provider. An Anthropic SDK can call a surface backed by an OpenAI model, and an OpenAI SDK can call a surface backed by Claude, with no code change on either side. Every surface accepts all three formats by default; restricting a surface to specific formats is optional.

What request types ride the same governed pipeline

A surface is path-transparent: the path suffix a client sends to an OpenAI-compatible provider is forwarded as-is, so embeddings, moderation, rerank, image generation, transcription, translation, text-to-speech, batch jobs, and file operations all ride the same governed pipeline, rather than being separate integrations.

IDE Surface

An IDE Surface has no provider of its own. It consolidates one or more LLM Surfaces into a single, governed, OpenAI-compatible model-discovery menu, added through its Catalogue node’s member picker:

• IDE clients and OpenAI-compatible agents point to one Access Point URL, sign in with corporate SSO, and see only the models they’re entitled to use.
• Each dispatched request runs the full governance pipeline, guardrails, budgets, quotas, policies, routing rules, cache, retries, failover, on its backing LLM Surface, and the outcome is recorded for later review.
• The IDE Surface mirrors cost, token, telemetry, and log data back for a unified per-editor view.

Besides corporate SSO, other identity-binding options are mTLS, API key, and JWT Bearer: callers present only the standard authentication material for that method, and the appliance derives the caller’s identity from the credential itself. See Security and access control → for more information.

An IDE Surface fans a single client-facing endpoint out to one or more LLM Surfaces, each still running its own full governance pipeline:

Variants: one endpoint, many behaviours

Each surface carries a catalogue of named variants, addressable at {route}$alias/.... A variant overrides part or all of a surface’s behaviour, such as its provider, model, guardrails, or limits, without a separate surface record or endpoint. Identity and routing fields stay fixed, so a variant is reachable at the same base route and observed under the same metrics as its parent surface.

Variants are the substrate for progressive rollout. See Variants and progressive rollout → for how routing rules and canary splits select one automatically.

Related

• Pipeline and stages: The stage order every surface request follows.
• Variants and progressive rollout: How variants, routing rules, and canary splits change behaviour safely.
• Security and access control: Authentication methods and identity binding for both surface types.
• Providers →: Provider adapter configuration.
• Guardrails: Prompt guard, expert witnesses, Judge, and Jury, one of the configuration blocks a surface composes.