# Control which A2A versions and messages a surface accepts

> Choose the A2A protocol versions an A2A surface accepts and how strictly the gateway checks each request before it reaches your managed agent.

This guide sets the A2A Protocol section of an A2A surface’s Access Point: which A2A versions callers may use, and how much of each request the gateway checks before forwarding it. For background on how the gateway negotiates versions, see [A2A protocol](/products/affinidi-trust-fabric/agent-gateway/concepts/protocols/a2a.md#how-the-gateway-handles-a2a-versions).

A2A 0.3 and A2A 1.0 use different method names and message fields, and the gateway passes each request on in the version the caller sent. The gateway refuses a caller whose version is outside the surface’s selected versions, and tells it which versions the surface accepts. Callers on every selected version reach your agent, so select only the versions your agent supports. The validation level decides whether malformed requests are refused at the gateway or reach your agent.

Use this guide when:

- Your managed agent supports only one A2A version and you want callers on the other version refused at the gateway.

- You want the gateway to refuse requests with malformed A2A fields before they reach your agent.

- Callers receive JSON-RPC error -32009 and you need to check which versions the surface accepts.

This guide applies to surfaces whose Managed Agent uses Direct URL or via Gateway Connection. For a surface that uses via A2A Proxy, the gateway sets the versions and validation level itself, as described in [A2A Proxy](/products/affinidi-trust-fabric/agent-gateway/reference/proxies/a2a-proxy.md#a2a-versions-and-replies).
Request shape checks

With the default Message validation, JSON-RPC envelope, the gateway forwards a well-formed JSON-RPC request even when its A2A fields are malformed, and your agent decides how to answer it. To refuse such requests at the gateway, set Message validation to Envelope + A2A fields as described in Step 3.

## Prerequisites

- An A2A surface whose Managed Agent uses Direct URL or via Gateway Connection. See [A2A surface starter](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/setup/a2a-surface-starter.md).

- Access to the Agent Gateway dashboard with permission to edit surfaces.

- The A2A versions your managed agent supports. Check its agent card or its own documentation.

## Steps

Open the Access Point of the surface

- Open Surfaces in the Agent Gateway dashboard and select the A2A surface.

- On the canvas, select the Access Point node.

- Scroll the panel to the A2A Protocol section.

Select the supported versions

Under Supported versions, select the A2A versions your managed agent supports:

- A2A 0.3: callers that send A2A-Version: 0.3, or no A2A-Version header, which counts as 0.3.

- A2A 1.0: callers that send A2A-Version: 1.0.

Select at least one version. Both are selected by default.

Choose the message validation level

From the Message validation dropdown, select how much of each request the gateway checks:

| Option | Choose it when |
| JSON-RPC envelope | Your agent should receive every well-formed JSON-RPC request and decide how to answer it. The gateway refuses invalid JSON and batch requests, and requires "jsonrpc": "2.0" and a string method on every request. This is the default. |
| Envelope + A2A fields | The gateway should also refuse requests whose A2A fields are missing or wrong, such as the message ID, the role, or the message parts. message/send is checked against A2A 0.3 and SendMessage against A2A 1.0. |
| Off | The gateway should forward every request as it is. Batch requests and requests with a missing or invalid method name then reach your surface policies with no method to match. |

For the full field reference, see [Access Point: A2A Protocol](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md#a2a-protocol).

Save the surface

Select the save button in the toolbar (tooltip: Save changes).

## Confirm

Replace <ENTRY_POINT_URL> in the commands below with the Entry point URL shown at the top of the Access Point panel. If the surface has caller authentication configured, add the required credentials to each request.

### Test 1: request with a selected version returns a response from the agent

Send a request in a version you selected in Step 2.

curl -X POST "<ENTRY_POINT_URL>" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0",
    "method": "SendMessage",
    "id": 1,
    "params": {
      "message": {
        "messageId": "test-1",
        "role": "ROLE_USER",
        "parts": [{"text": "Hello"}]
      }
    }
  }'

curl -X POST "<ENTRY_POINT_URL>" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 0.3" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": 1,
    "params": {
      "message": {
        "messageId": "test-1",
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello"}]
      }
    }
  }'

Expected: a JSON-RPC response from your managed agent with a result.

### Test 2: request with an unsupported version returns -32009

```bash
curl -X POST "" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 2.0" \
  -d '{"jsonrpc": "2.0", "method": "SendMessage", "id": 1, "params": {}}'
```

Expected: HTTP 400 with a JSON-RPC error whose data.supported lists the versions you selected in Step 2. For example, with both versions selected:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32009,
    "message": "Unsupported A2A protocol version '2.0'",
    "data": {
      "requested": "2.0",
      "supported": ["0.3", "1.0"]
    }
  }
}
```

### Test 3: batch request returns -32600

Run this test when Message validation is JSON-RPC envelope or Envelope + A2A fields. If you selected only A2A 0.3, change the header to A2A-Version: 0.3.

```bash
curl -X POST "" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '[{"jsonrpc": "2.0", "method": "SendMessage", "id": 1, "params": {}}]'
```

Expected: HTTP 400 with JSON-RPC error code -32600.

### Test 4: SendMessage with an A2A 0.3 role returns -32602

Run this test if you chose Envelope + A2A fields and selected A2A 1.0. The request uses the A2A 0.3 role user on the A2A 1.0 method SendMessage.

```bash
curl -X POST "" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0",
    "method": "SendMessage",
    "id": 1,
    "params": {
      "message": {
        "messageId": "test-1",
        "role": "user",
        "parts": [{"text": "Hello"}]
      }
    }
  }'
```

Expected: HTTP 400 with JSON-RPC error code -32602, and error data that names the role field. With JSON-RPC envelope, the same request reaches your managed agent instead.

## Troubleshooting

| Symptom | Likely cause | Fix |
| Callers that send no A2A-Version header receive -32009. | A request without the header counts as A2A 0.3, and A2A 0.3 is not selected. | Select A2A 0.3, or have callers send A2A-Version: 1.0. |
| The Supported versions checkboxes are locked. | The surface’s Managed Agent uses via A2A Proxy, so the gateway fixes the versions. | Have callers send a version the panel lists. See [A2A Proxy](/products/affinidi-trust-fabric/agent-gateway/reference/proxies/a2a-proxy.md#a2a-versions-and-replies). |
| Message validation is locked at JSON-RPC envelope. | The Target in view is an A2A proxy, which always checks the JSON-RPC envelope. | Use a variant whose Target is a URL to set a different level for that Target. |
| Requests with malformed A2A fields reach the agent. | Message validation is JSON-RPC envelope, which checks only the envelope. | Set Message validation to Envelope + A2A fields. |

## Next steps

- [Restrict surface access with API key authentication](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/access/restrict-surface-access-with-api-key.md): Require callers to present a key before their requests reach the agent.

- [Enable A2A communication with a Copilot Studio agent](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/setup/enable-a2a-communication-with-a-copilot-studio-agent.md): Route an A2A surface to a Copilot Studio agent through an A2A proxy.

## Related

- [Access Point reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md): Every Access Point field, including the A2A Protocol section.

- [A2A Proxy](/products/affinidi-trust-fabric/agent-gateway/reference/proxies/a2a-proxy.md): Fixed versions and reply shapes for surfaces that target an A2A proxy.

- [A2A protocol](/products/affinidi-trust-fabric/agent-gateway/concepts/protocols/a2a.md): How the gateway processes A2A traffic.