Agent Gateway Overview

AISIX AI Gateway fronts registered upstream A2A (Agent-to-Agent) agents through its own gateway path. A caller reaches an agent at /a2a/<agent> with an AISIX caller API key, and AISIX forwards the A2A JSON-RPC request to the upstream agent — holding the upstream credential gateway-side, so the caller never receives it.

This gives agent traffic the same authentication, access control, policy, and telemetry boundary as model traffic. One caller API key governs the models a caller may use, the MCP tools it may call, and the A2A agents it may reach. AISIX authenticates the caller, checks agent access, applies rate limits and budgets, forwards the call to the registered upstream agent using the credential you configured, and records A2A usage telemetry.

An A2A agent is a registry entry for one upstream agent that speaks the A2A protocol over HTTP with JSON-RPC 2.0. This page introduces the agent gateway and walks through a minimal end-to-end setup. For depth on each area, see:

• Upstream authentication — how AISIX authenticates to each upstream agent (none, bearer, api_key).
• Control agent access per key — how allowed_agents on a caller API key decides which agents that key can reach.
• Rate limits and budgets — how the caller API key's rate limits and budgets govern A2A calls.
• Observability — the usage events and metrics A2A calls emit.

How the Agent Gateway Works

Each upstream agent is registered as a gateway resource under a display_name. AISIX exposes that agent at /a2a/<display_name> on the proxy listener and forwards each JSON-RPC request body to the upstream agent unchanged.

Because AISIX forwards the request body verbatim, the caller speaks whichever A2A wire version the agent is pinned to. The gateway does not translate between the 0.3 and 1.0 formats, so a caller must send the version its target agent is registered with.

Prerequisites

Before starting, prepare the following:

• A self-hosted AISIX gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• An upstream agent that serves the A2A protocol over HTTP, and its URL.
• A caller API key value that the A2A client will send to AISIX.

Managed deployments

On AISIX Cloud, you register A2A agents and grant agent access from the dashboard instead of the Admin API, scoped to an organization and exposed per environment. The concepts on this page are identical; only the management surface differs. See AISIX Cloud.

Register an A2A Agent

Create an A2A agent resource for the upstream endpoint. The display_name becomes the path segment the agent is exposed under (/a2a/<display_name>), so it must be a single URL path segment and must be unique within the gateway. This example registers an agent that needs no upstream credential; for the authenticated modes, see Upstream authentication.

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none"
  }'

You should see a response similar to the following:

{
  "id": "1d95ac57-7f27-46a4-b5a3-55d3c3ad0a12",
  "value": {
    "display_name": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none",
    "enabled": true
  },
  "revision": 1
}

Copy the highlighted id if you plan to update, inspect, or delete this agent later.

Key fields:

Field	Notes
display_name	The path segment the agent is exposed under (/a2a/<display_name>). Must be a non-empty single URL path segment (no /) and unique within the gateway. A duplicate name is rejected with 409.
url	The upstream agent's A2A service endpoint, reached over HTTP with JSON-RPC 2.0.
protocol_version	The A2A wire format AISIX pins for this agent: 1.0 (default) for the protobuf-JSON envelope, or 0.3 for the JSON-RPC kind-discriminated envelope.
auth_type	How AISIX authenticates to the upstream agent: none (default), bearer, or api_key. See Upstream authentication.
secret	The upstream credential for the chosen auth_type. Held gateway-side and never sent to the calling client.
timeout_ms	Per-operation timeout for upstream calls, in milliseconds. Defaults to 30000 (30 seconds).
enabled	Whether the agent is served. Defaults to true; set false to keep the registration but return 404 at /a2a/<display_name>.

Grant Agent Access

A caller reaches an agent with an AISIX caller API key, not the admin key. Access is granted explicitly: a key with no allowed_agents may reach no agent.

Create a caller API key with the agents you want it to reach. Hash the plaintext caller key before creating the resource:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="sk-demo-caller"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }'

["invoice-processor"] grants this key one agent. Use ["*"] to grant every agent. Use an empty model allowlist when the key is only for A2A traffic. For the full matching rules, see Control agent access per key.

Save the returned id if you want to update this caller API key later.

Reach the Agent Through the Gateway

Send A2A JSON-RPC requests to /a2a/<display_name> on the proxy listener with the caller API key in the Authorization header. AISIX authenticates the key, checks it against allowed_agents, applies rate limits and budgets, forwards the request to the upstream agent, and records a usage event.

The request body is the A2A JSON-RPC envelope for the agent's pinned protocol_version. The example below is the 0.3 form the agent above was registered with:

export AISIX_API_KEY="sk-demo-caller"

curl -sS -X POST "http://127.0.0.1:3000/a2a/invoice-processor" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Review this vendor invoice."}],
        "messageId": "msg-1"
      }
    }
  }'

Expected result: AISIX returns the upstream agent's JSON-RPC response unchanged. A missing or invalid caller API key receives 401; a valid key whose allowed_agents does not include the agent receives 403; an unknown or disabled agent returns 404.

AISIX forwards every A2A JSON-RPC method through this one governed path, not just message/send. The same endpoint accepts message/stream, tasks/get, tasks/cancel, tasks/resubscribe, and the push-notification configuration methods. For each, AISIX authenticates the caller key, checks allowed_agents, applies rate limits and budgets, forwards the request body verbatim, and records a usage event tagged with the called method. It does not special-case any method or alter the request or response body.

If the gateway cannot reach the upstream agent, or the upstream returns a non-success status, AISIX replies with HTTP 502 and a JSON-RPC error envelope (error.code -32000). The error message describes the failure — including the upstream status code when the upstream responded — while the upstream response body is not proxied back to the caller.

Discover the Agent Card

AISIX serves the upstream agent's card at the well-known path under the agent, rewriting the card's advertised service url to the gateway so clients route subsequent requests through AISIX:

curl -sS "http://127.0.0.1:3000/a2a/invoice-processor/.well-known/agent-card.json" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

AISIX fetches the card from the well-known path at the origin of the upstream URL (https://<upstream-host>/.well-known/agent-card.json). It rewrites the url field to http(s)://<your-gateway-host>/a2a/invoice-processor, derived from the request Host header, and preserves every other card field (skills, capabilities, version, security schemes) verbatim.

Apply Traffic Controls

A2A calls pass through the same caller API key boundary as model requests, so the same controls apply:

• Rate limits and budgets. The caller API key's request-rate limits and concurrency apply to each /a2a/<agent> invocation; in managed deployments, AISIX Cloud budget checks also apply. A rejected call returns before AISIX contacts the upstream agent. See Rate limits and budgets.
• Access control. The caller API key's allowed_agents list gates which agents the key may reach. See Control agent access per key.
• Telemetry. Each call emits a usage event recording the caller key, the agent name, and the JSON-RPC method. Token and cost fields are zero, because the gateway does not meter model tokens on this path. See Observability.

Current Behavior and Limitations

The agent gateway currently supports the flow above. The following are not yet available:

note

• Protocol binding. AISIX fronts the A2A JSON-RPC binding at POST /a2a/<agent>, plus the agent-card GET. The REST/HTTP binding's path-based methods, such as POST .../v1/message:send or GET .../v1/tasks/{id}, are not separately routed.
• Upstream authentication is limited to none, bearer, and api_key. The auth_type value oauth2 is accepted on the resource for forward compatibility, but a call to an oauth2 agent returns 501 because the runtime does not mint the token yet. See Upstream authentication.
• Guardrails do not yet scan A2A message content. Access control, rate limits, budgets, and usage apply today; content moderation over A2A is planned. Guardrails inspect model and MCP traffic in the meantime.
• Streaming. A message/stream response is buffered and returned as one response rather than streamed chunk by chunk.
• Protocol translation between A2A 0.3 and 1.0 is not performed, and AISIX does not infer the version from client signals. It serves and forwards the version the agent is pinned to, so callers must send that version.
• Agent-card rewriting covers the card's top-level service url only. Other endpoints a card advertises, such as additionalInterfaces, are passed through unchanged and continue to point at the upstream agent.
• Managed-platform agents — agents hosted on a cloud agent runtime such as Amazon Bedrock AgentCore, Azure AI Foundry, or Vertex AI Agent Engine — are not yet a registration option; register agents by their A2A HTTP URL.

Next Steps

• Upstream authentication — configure none, bearer, or api_key for each upstream agent.
• Control agent access per key — scope callers to specific agents or every agent.
• Rate limits and budgets — throttle and cap A2A calls on the caller API key.
• Observability — read the usage events and metrics A2A calls emit.
• Caller API Keys — manage caller credentials and their allowed_agents lists.