# A2A protocol

> How the Agent Gateway handles Google Agent-to-Agent protocol traffic, including extensions, identity, and trust verification.
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 →](/products/affinidi-trust-fabric/agent-gateway/how-to-guides.md)

## 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:

- Parses the JSON-RPC payload and identifies the A2A method (message/send, tasks/get, and so on).

- Validates any extension data present in message.metadata.

- Extracts identity attributes (if identity is enabled) and computes a DID for the agent.

- Evaluates OPA policies against the request context and identity.

- Injects a Verifiable Presentation into the forwarded message (if identity is enabled and a VC has been issued).

- Forwards the request to the target agent.

## 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 is configured per-surface with three modes:

| Mode | Behaviour |
| required | Both parties must include identity metadata. Requests without it are rejected. |
| allowed | Identity metadata is optional. The gateway accepts it if present. |
| none | The extension is disabled on this surface. |

## 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. Raw secret values are never stored in surface configuration.

## 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](/products/affinidi-trust-fabric/agent-gateway/concepts/connections/trust-registry.md).

## 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](/products/affinidi-trust-fabric/agent-gateway/how-to-guides.md): Step-by-step guide to creating an A2A surface.

- [Surfaces](/products/affinidi-trust-fabric/agent-gateway/concepts/surfaces.md): The general surface model.

- [Agent identity and DIDs](/products/affinidi-trust-fabric/agent-gateway/concepts/identity.md): How identity extraction works.

- [Trust registries](/products/affinidi-trust-fabric/agent-gateway/concepts/connections/trust-registry.md): How trust verification works.