> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A proxy

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

Agentgateway supports the [Agent2Agent (A2A) protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/), 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`:

```yaml config.yaml theme={null}
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

<Steps>
  <Step title="Clone and start the sample A2A agent">
    The A2A samples project provides a reference agent implementation you can use for testing.

    ```bash theme={null}
    git clone https://github.com/a2aproject/a2a-samples
    cd a2a-samples/samples/python
    uv run agents/helloworld
    ```

    This starts the agent on `localhost:9999`.
  </Step>

  <Step title="Start Agentgateway">
    In a separate terminal, run the gateway with the A2A example config:

    ```bash theme={null}
    cargo run -- -f examples/a2a/config.yaml
    ```

    The gateway listens on port 3000 and proxies A2A traffic to `localhost:9999`.
  </Step>

  <Step title="Connect a client">
    Run the sample CLI client and point it at the gateway:

    ```bash theme={null}
    uv run hosts/cli --agent http://localhost:3000
    ```

    Send a few messages through the CLI to generate traffic through the gateway.
  </Step>
</Steps>

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

```bash theme={null}
curl http://localhost:3000/.well-known/agent.json | jq
```

```json theme={null}
{
  "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:

```plain theme={null}
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`.

<Tip>
  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.
</Tip>

## Policy support

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

```yaml theme={null}
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](/guides/authentication) and [Authorization guide](/guides/authorization) for details on securing A2A routes.