A2A protocol

A2A (Agent-to-Agent) is Google’s protocol for structured task execution between AI agents. The Agent Gateway treats A2A as a first-class protocol: it understands the A2A message format, inspects extensions, extracts agent identity, and enriches messages in transit. Set up an A2A surface →

What A2A enables

A2A enables agents to:

• Discover other agents via Agent Cards at /.well-known/agent-card.json.
• Send tasks with structured input and receive structured output.
• Stream responses for long-running operations.
• Exchange artifacts, including files, data, and structured content.
• Negotiate capabilities through extensions.

Transport is JSON-RPC 2.0 over HTTP/HTTPS.

How the gateway processes A2A traffic

An A2A surface acts as a protocol-aware proxy. When a request arrives, the gateway:

1. Reads the caller’s A2A version from the A2A-Version header and checks it against the versions the surface accepts, refusing any other.
2. Checks the request at the surface’s message validation level and identifies the A2A method (SendMessage, message/send, tasks/get, and so on).
3. Validates any extension data present in message.metadata.
4. Extracts identity attributes (if identity is enabled) and computes a DID for the agent.
5. Evaluates OPA policies against the request context and identity.
6. Injects a Verifiable Presentation into the forwarded message (if identity is enabled and a VC has been issued).
7. Forwards the request to the target agent.

When the gateway returns an agent card, public or extended, it rewrites the card’s endpoint URLs to point at the gateway, so callers keep sending their requests through the surface.

How the gateway handles A2A versions

The gateway understands both A2A 0.3 and A2A 1.0, and each A2A surface states which of them its callers may use. A caller names its version in the A2A-Version request header, and a request that omits the header counts as version 0.3, as the A2A specification defines. When the requested version is outside the surface’s list, the gateway refuses the request with JSON-RPC error -32009 and lists the versions the surface accepts. The gateway passes each request on in the caller’s version, so list only the versions the managed agent behind the surface understands.

Each surface also sets how much of a request the gateway checks before forwarding it. By default the gateway checks only the JSON-RPC envelope, so a well-formed request reaches the agent, which decides how to answer any malformed A2A fields. A stricter level also checks the A2A request fields, using the rules of the A2A version that the method name belongs to. On a surface that routes to another gateway over Fabric, the sending gateway applies these checks before the request leaves it.

A surface whose managed agent is an A2A proxy has fixed versions, and a new one accepts A2A 1.0 only. To choose a surface’s versions and validation level, see Control which A2A versions and messages a surface accepts.

How the gateway handles A2A streams

A2A agents stream long-running work with SendStreamingMessage (message/stream in A2A 0.3) and SubscribeToTask (tasks/resubscribe). When a surface’s Managed Agent uses Direct URL and the agent answers with an event stream, the gateway forwards each event as it arrives, in the agent’s order, so callers see progress straight away.

Each event gets the same response checks as a non-streaming reply. Where an event’s message asks for the agent identity credential, the gateway puts the signed credential in place of the raw identity claim. It also adds the surface’s response metadata, and runs the response extension rules and response policy on the event. The first agent identity resolved holds for the whole stream. An event that fails a check is not sent, and the stream ends with a JSON-RPC error event whose data.code names the cause, because the HTTP status has already gone to the caller. On a surface that reads the agent’s identity from its responses, a stream that delivers results without ever claiming an identity also ends with an error event, unless the request already identified the agent.

A stream ends when the agent closes it, when the agent sends nothing for the surface’s Networking Idle timeout, or when it reaches a maximum stream lifetime the gateway sets. The gateway sends a streaming request once, whatever the surface’s retry settings. A surface that routes via Gateway Connection, and a Transit Point, still collect the whole stream and return it as one response when the agent closes it. An A2A proxy does not stream, and its agent card says so.

Agent Identity extension

The gateway supports the Affinidi Agent Identity extension (https://fabric.affinidi.io/extensions/agent-identity/v1). This extension allows agents to exchange identity metadata, including model information, software version, and provisioning details, through A2A message metadata.

Extension handling depends on whether identity extraction is configured for the surface at all, not on a separate per-surface mode selector:

Custom metadata injection

The gateway can inject custom data into every A2A message passing through a surface. The payload is defined in the surface configuration and is resolved at request time. Secret values are referenced using a $SECRET: prefix, which the gateway resolves from the secrets vault, so raw secret values are never stored in surface configuration. Three further template helpers resolve at request time: $TIMESTAMP, $REQUEST_ID, and $SURFACE_ID.

Trust registry verification

An A2A surface can require that all incoming agents are registered and authorised in a configured trust registry. Requests from unregistered agents are rejected before being forwarded. See Trust registries.

Surface aliases with A2A

A single A2A surface can route to different backend agents based on a URL alias. Different surface alias variants can carry different extension requirements, allowing a single surface entry point to serve multiple agent versions or environments.

Related

• Set up an A2A surface: Step-by-step guide to creating an A2A surface.
• Control which A2A versions and messages a surface accepts: Set a surface’s A2A versions and message validation.
• Surfaces: The general surface model.
• Agent identity and DIDs: How identity extraction works.
• Trust registries: How trust verification works.