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 →

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. Parses the JSON-RPC payload and identifies the A2A method (message/send, tasks/get, and so on).
  2. Validates any extension data present in message.metadata.
  3. Extracts identity attributes (if identity is enabled) and computes a DID for the agent.
  4. Evaluates OPA policies against the request context and identity.
  5. Injects a Verifiable Presentation into the forwarded message (if identity is enabled and a VC has been issued).
  6. 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:

ModeBehaviour
requiredBoth parties must include identity metadata. Requests without it are rejected.
allowedIdentity metadata is optional. The gateway accepts it if present.
noneThe 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.

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.