A2A proxy

Configure Agentgateway as an Agent2Agent (A2A) proxy to secure, observe, and route agent-to-agent traffic.

Agentgateway supports the Agent2Agent (A2A) protocol, enabling it to proxy traffic between AI agents. Enabling A2A mode adds protocol-level telemetry, agent card rewriting, and A2A-specific processing to any route.

How A2A proxying works

Unlike MCP, an A2A backend is a plain HTTP host — any A2A-compatible agent server. The a2a policy on a route tells Agentgateway to treat traffic on that route as A2A and process it accordingly.

When A2A mode is active, the gateway:

• Rewrites the agent card at /.well-known/agent.json so the url field points back to the gateway, preventing clients from bypassing it on subsequent requests
• Extracts the A2A method (message/send, message/stream, etc.) from each request and adds it to structured logs as a2a.method
• Applies all standard gateway policies (CORS, authentication, authorization, rate limiting) to A2A traffic

Configuration

Here is the complete configuration from examples/a2a/config.yaml:

config.yaml

config:
  logging:
    format: json
frontendPolicies:
  accessLog:
    add:
      backend: backend
binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
          - '*'
          allowHeaders:
          - content-type
          - cache-control
        # Mark this route as a2a traffic
        a2a: {}
      backends:
      - host: localhost:9999

The key addition compared to a plain HTTP proxy is a2a: {} in the route’s policies block. The backend is a host reference — the address of your upstream A2A agent server.

Running the example

1. Clone and start the sample A2A agent

   The A2A samples project provides a reference agent implementation you can use for testing.

   git clone https://github.com/a2aproject/a2a-samples
   cd a2a-samples/samples/python
   uv run agents/helloworld
   

   This starts the agent on localhost:9999.

2. Start Agentgateway

   In a separate terminal, run the gateway with the A2A example config:

   cargo run -- -f examples/a2a/config.yaml
   

   The gateway listens on port 3000 and proxies A2A traffic to localhost:9999.

3. Connect a client

   Run the sample CLI client and point it at the gateway:

   uv run hosts/cli --agent http://localhost:3000
   

   Send a few messages through the CLI to generate traffic through the gateway.

Agent card rewriting

The A2A protocol uses an agent card at /.well-known/agent.json to advertise an agent’s capabilities and endpoint URL. When Agentgateway proxies A2A traffic, it rewrites the url field in the agent card to point back to the gateway.

This ensures that clients always route future requests through the gateway, rather than connecting directly to the upstream agent.

For example, fetch the agent card through the gateway:

curl http://localhost:3000/.well-known/agent.json | jq

{
  "description": "Just a hello world agent",
  "url": "http://localhost:3000"
}

The url has been rewritten from localhost:9999 to localhost:3000 — the gateway’s address.

A2A telemetry

When A2A mode is active, Agentgateway adds the a2a.method field to structured access logs. This captures the A2A JSON-RPC method for each request, making it easy to filter and analyze agent communication patterns.

Example log line from a streaming message exchange:

2025-07-03T16:56:34.379262Z     info    request gateway=bind/3000 listener=listener0
    route=route0 endpoint=localhost:9999 src.addr=127.0.0.1:57408
    http.method=POST http.host=localhost http.path=/ http.version=HTTP/1.1 http.status=200
    a2a.method=message/stream duration=2ms

The a2a.method field identifies the specific A2A operation — in this case, message/stream.

Enable JSON log format (config.logging.format: json) when running in production to make log aggregation and querying easier with tools like Loki, Elasticsearch, or CloudWatch.

Policy support

All standard Agentgateway route policies apply to A2A routes. You can layer authentication, authorization, and rate limiting on top of A2A traffic:

policies:
  a2a: {}
  cors:
    allowOrigins:
    - '*'
  # Add JWT authentication
  jwtAuth:
    issuer: https://your-idp.example.com
    audiences: [your-agent]
    jwks:
      url: https://your-idp.example.com/.well-known/jwks.json

See the Authentication guide and Authorization guide for details on securing A2A routes.