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.

For the complete sub-component field references, see Access Point, Target, 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-registry injection defaults. References a Department record, not the Issuer entity 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 IdentityAgent IdentityNo—Three independent identity resolution slots covering each pipeline edge.
Credential Delegation—No—Outbound credential bindings injected when the managed agent forwards a request upstream. Added as a Credential Delegation canvas element on the Managed Agent → External edge.

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.

Agent Identity

Three independent identity slots, one per pipeline edge. Each slot defines how the gateway derives an agent DID on that edge. Configure each slot by adding an Identity canvas element to the corresponding edge.

SlotPipeline edgePurpose
Caller (inbound)Caller → Access PointExtracts the caller agent’s identity from the inbound request.
Managed agent (protected)Managed agent → Access Point responseExtracts the managed agent’s identity from the response body.
External agentExternal target → Transit Point responseExtracts the external agent’s identity from an outbound response.

Identity slot modes

Each slot can be configured in one of the following modes:

ModeDescription
From PayloadParses identity metadata from the request or response body. Requires the agent-identity/v1 extension on inbound A2A / MCP traffic.
From API KeyDerives the DID from the validated API key credential. Rotating the key produces the same DID.
From mTLS certificateDerives the DID from the client certificate presented during the request.
Static DIDUses a fixed, pre-known DID for all requests through this slot.
From JWT ClaimsExtracts the DID from a named JWT claim. Requires JWT Bearer authentication on the same surface. Only available on the inbound pipeline.

Policy definition

The Policy Definition settings attach an OPA policy to a surface component. Used on the Access Point, Managed Agent, and Transit Points.

FieldTypeRequiredDefaultDescription
Policy DefinitionstringYes—ID of the OPA policy definition in the policy store.
Require agent contextboolNofalseWhen enabled, the pipeline fetches the target’s agent card and queries the trust registry before evaluating this policy, populating input.agent in the OPA input. Adds latency; only enable when the policy uses input.agent.

Rate limit

The Rate Limit settings control inbound and outbound request throttling. Used on the Access Point and Transit Points.

| Field | Type | Required | Description | |—|—|—| | Max requests per window | integer | Yes | Maximum number of requests allowed within the rate limit window. | | Window (seconds) | integer | Yes | Duration of the rate limit window in seconds. |