Surface reference

Field reference for the top-level AgentSurface configuration.

The AgentSurface is the top-level configuration and runtime entity in the Agent Gateway. One surface represents one managed agent’s full surface area: how it is reached, where it routes, what identity it carries, and what it can call out to. Use this reference when creating or editing a surface to understand what each field controls and how protocol, identity, and policy settings interact across the pipeline.

For the complete sub-component field references, see Access Point, Managed Agent, Transit Points, and Variants.

Top-level fields

FieldTypeRequiredDefaultDescription
Surface IDstringRead-onlyAuto-assignedUnique identifier assigned at creation. Shown in edit mode. Never changes after creation.
NamestringYes—Human-readable name. Appears in the dashboard, logs, and metrics.
DescriptionstringNo—Optional description.
ProtocolProtocol optionsYesA2A / UCPAgent protocol for both inbound and target communication. Locked once elements are added to the canvas.
Surface enabledtoggleNoOnWhen off, the surface returns HTTP 503 to all inbound requests.
IssuerstringNo—Owning issuer for this surface. Drives Trust Check and Trust Recorder authority defaults. Selects from the issuer records managed at Identity → Issuers.
Tagsstring[]No—Labels for grouping, filtering, and search.
Publish to Gateway DID documenttoggleNoOffWhen on, advertises this surface in the gateway’s DID document.
Gateway DID injectiontoggleNoOffWhen on, injects a did:webvh identity on every outbound request from this surface. See Gateway DID injection settings.
Terminate trace at egresstoggleNoOffKeeps the incoming trace ID for this surface’s own audit; forwards a fresh trace ID downstream. Prevents the trace from crossing to the next gateway or agent.
Access PointAccess Point settingsYes—Inbound configuration: how callers reach this agent.
Managed AgentManaged Agent settingsYes—The single upstream destination: the managed agent backend.
Outbound ListenerTransit Point settingsNo—Agent-initiated outbound routes.
VariantsVariantsNo—Named surface variations selectable at request time via $alias in the URL. Use Promote to default in the Variants panel to set the active default variant.
Agent IdentityIdentity elementNo—Three independent identity resolution slots covering each pipeline edge. See Canvas elements.

Protocol options

Selected when creating the surface and locked once elements are added to the canvas.

ProtocolDescription
A2A / UCPAgent-to-Agent protocol (JSON-RPC 2.0 with A2A extensions). Default. Use for direct agent-to-agent communication and UCP extension flows.
AP2Agent Payments Protocol. Extends A2A with Verifiable Credential and VP transformation for payment-agnostic financial transactions.
MCPModel Context Protocol (JSON-RPC 2.0). Use when connecting AI models to external tools and data sources.

Gateway DID injection settings

These fields appear in the Gateway DID Injection section of the surface panel when Gateway DID injection is enabled.

SettingRequiredDescription
Identity IDNoBind to an existing managed identity by its UUID. Leave blank to create a new identity automatically.
Auto-create identity if it does not existNoWhen on, the gateway creates a new managed identity if the specified Identity ID does not exist. Requires Identity ID to be set.
DID PathNoCustom path segment for the did:webvh DID. Defaults to the surface name when blank.
Injection ModeYes (when enabled)How the DID is injected into outbound requests. See Injection modes.

Injection modes

ModeDescription
HeaderInjects the DID as the X-DID-Identity HTTP header.
Signed HeaderInjects a signed DID assertion as the X-DID-Signed-Identity HTTP header.
Protocol NativeInjects the DID using the protocol’s native extension mechanism: A2A extension or MCP _meta field.

Canvas elements

Canvas elements are pipeline components added to the Access Point, Managed Agent, or Transit Points edges in the surface builder. They configure how requests are processed, authenticated, and transformed at each stage.

ElementReferenceDescription
Caller ContextCaller ContextExtracts and forwards caller identity headers through the pipeline.
IdentityIdentity elementResolves and attaches agent identity at each pipeline edge. Three independent slots cover inbound, internal, and outbound edges.
PolicyOPA policies: Policy elementAttaches an OPA policy to a pipeline stage for request authorisation.
Rate LimitNetworking elements: Rate LimitThrottles requests at a pipeline stage with configurable request limit, window, and burst.
Trust CheckTrust elements: Trust CheckValidates trust assertions against the trust registry before forwarding.
Trust RecorderTrust elements: Trust RecorderRecords trust events for audit and compliance.
Extension ValidationProtocol extension elementsValidates UCP extension headers on inbound A2A and AP2 requests.
Extension RulesProtocol extension elementsDefines per-URI outbound extension rules for A2A and AP2 surfaces.
Metadata InjectionMetadata elementsInjects metadata headers or context values into the request pipeline.
Metadata ExtractionMetadata elementsExtracts metadata from requests for downstream consumption.
Credential DelegationOutbound binding elementsInjects Verifiable Presentations into outbound requests from the managed agent.
Workload BindingOutbound binding elementsAttaches caller workload identity context to outbound requests.
MCP ToolsMCP toolsConfigures tool access permissions and policy for MCP surfaces.
NetworkingNetworkingControls timeouts, retries, circuit breaking, traffic mirroring, and rate limiting.
PaymentPaymentConfigures x402 and MPP payment protocol handling.