Surfaces

An Agent Surface, referred to simply as a surface, is the single top-level configuration and runtime unit that represents one managed agent in Agent Gateway.

It brings together every concern the gateway manages for that agent: how callers reach it, where traffic is forwarded, what identity the agent carries, which policies govern flow, and what outbound capability the agent has.

What surfaces are

A single managed backend can be exposed through one or more surfaces, depending on the security, policy, and routing posture you need.

Each surface owns and defines:

• Exactly one Access Point: the inbound entry point for callers.
• Exactly one External Target: where the gateway forwards requests.
• Zero or more Transit Points: outbound routes initiated by the managed agent.
• Identity slots evaluated during request and response processing.
• An optional set of Surface Variants.

Surface structure at runtime

Surfaces are pre-resolved at write time into immutable in-memory snapshots. This means request handling does not pay per-request configuration resolution overhead for routing decisions.

When a surface configuration changes, the gateway applies updates through hot reload, without restarting internal request-serving processes.

Visual composition and request flow

You build surfaces on a canvas in the surface builder. The canvas represents the full lifecycle of a request: from the caller arriving at the Access Point, through identity and policy processing, to forwarding at the External Target.

Each inbound request follows this sequence:

1. A caller sends traffic to the surface Access Point.
2. Caller context extracts user claims from the configured IdP context and makes them available to the pipeline.
3. Identity processing derives or resolves the managed agent identity for policy and trust decisions.
4. Policy controls evaluate request context, identity attributes, and governance rules.
5. The request is forwarded to the External Target, which can be another agent, an MCP server, or a REST backend.

When surfaces are connected through gateway-to-gateway routing, identity context can transit across trust boundaries, enabling remote policy enforcement based on verifiable identity claims and issuer root-of-trust context.

Elements with missing configuration are highlighted on the canvas so you can identify what still needs to be completed.

Palette-driven capabilities

The surface builder provides a palette of prebuilt components in the left-hand sidebar. Drag an item onto the canvas to add a capability without hand-authoring configuration. You can also save a selection of elements as a partial template using Create template from canvas, and apply it to another surface without replacing its full configuration.

Protocol support

The gateway supports multiple communication protocols. When you create a new surface, you choose from the available starter templates. The protocols available at surface creation are A2A and MCP.

When you add a Transit Point to a surface from the palette, additional protocols become available for the outbound route, including AP2.

A surface can use one protocol for its inbound Access Point and a different protocol for outbound Transit Points. For example, an MCP surface can route outbound calls over an AP2 Transit Point.

Templates and reuse

Configured surfaces can be saved as templates. Select Save Surface as Template… from the Surface panel, add metadata (name, description, and priority), and the template becomes available when creating a new surface. You can select from prebuilt templates, reuse custom templates, or start from scratch.

Editing and controls

Surface Variants

A Surface Variant is a named variation of a base surface, selected at request time through a route-level alias, without creating a separate surface record. Variants let you evaluate policy references, identity configuration, and endpoint overrides against the same Access Point listener.

This keeps related postures in one surface lifecycle instead of duplicating records. You can maintain multiple variants, switch defaults, and preserve a single audit trail for the underlying surface.

For implementation workflow, see the surfaces guides and the surface builder variant controls.

How listener URLs are formed

Every Access Point is addressed by a URL assembled from three fields set in the surface canvas.

The route stored on the Access Point is {prefix}/{custom_path}, and the full Access Point URL the caller dials is {listen_address}{route}:

https://gateway.example.com/agents/sales-agent

When a Surface Variant is configured, its alias is appended directly to the route with no separator slash:

https://gateway.example.com/agents/sales-agent$staging

Callers choose a variant by including the $ALIAS suffix. Requests without a suffix go to the base surface, or to the variant promoted as the default when one is set. All variants share the same listener. Only the routing behaviour differs.

The per-variant copy-ready URL is shown in the variant panel on the surface canvas.

Related

• Surface routing model: Detailed explanation of Access Point, External Target, Transit Point, and Listener responsibilities.
• Create your first surface: Build a surface and send a test request.
• Protocols: Understand communication patterns supported by the gateway.
• Agent identity and DIDs: Learn how identity derivation works within request flows.