Skip to main content
API7.ai Logo

Agent Gateway Overview

AISIX AI Gateway fronts registered upstream Agent-to-Agent (A2A) agents through its own gateway path. A caller reaches an agent at /a2a/<agent> with an AISIX caller API key. AISIX forwards the A2A JSON-RPC request to the upstream agent while keeping the upstream credential gateway-side.

This gives agent traffic the same authentication, access control, policy, and telemetry boundary as model and MCP traffic. One caller API key can govern 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 shows how to register and call an agent through a self-hosted gateway.

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.

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

Register and Call an Agent​

The example below registers one upstream A2A agent, grants a caller API key access to it, and sends a request through the gateway.

Prerequisites​

The following example uses a self-hosted AISIX gateway. Before running it, prepare the following:

  • An 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.

For managed deployments, use the control-plane workflow instead of the self-hosted Admin API commands. The concepts are the same; only the management surface differs. This workflow is available with AISIX Cloud and AISIX Cloud On-Premises.

Register an A2A Agent​

This example registers an upstream A2A agent that uses the A2A 0.3 wire format and needs no credential. Create the agent resource for the upstream endpoint:

# Replace with your values
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"
  }'

❶ display_name becomes the path segment where AISIX exposes the agent, such as /a2a/invoice-processor. It must be unique and cannot contain /.

❷ url is the upstream agent endpoint AISIX forwards A2A JSON-RPC requests to.

❸ protocol_version: "0.3" configures this agent to accept A2A 0.3 request bodies. AISIX does not translate between A2A versions.

❹ auth_type: "none" registers an upstream agent that does not require AISIX to send a credential.

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
}

Save the returned id if you plan to update, inspect, or delete this agent later.

For upstream credential options, see Upstream authentication.

For the complete request and response schema, see Create A2A Agent in the Admin API Reference.

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:

# Replace with your values
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" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }
EOF

❶ Use an empty model allowlist when the key is only for A2A traffic.

❷ ["invoice-processor"] grants this key one agent. Use ["*"] to grant every agent. For matching details, see Control agent access.

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

Verify Agent Calls Through AISIX​

Send a JSON-RPC request to the agent's proxy path with the caller API key. The request body must match the agent's configured A2A protocol version:

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"
      }
    }
  }'

❶ message/send sends a message to the upstream agent.

❷ The message shape follows the A2A 0.3 version configured when you registered the agent.

A successful request returns the upstream agent's JSON-RPC response unchanged.

For calls that pass agent lookup and access checks, AISIX applies rate limits and budgets, forwards the request to the upstream agent, and records a usage event. Token and cost fields are zero for A2A calls because the gateway does not meter model tokens on this path.

The same endpoint accepts message/stream, tasks/get, tasks/cancel, tasks/resubscribe, and the push-notification configuration methods. Each method uses the same caller authentication, agent access check, traffic controls, request forwarding, and usage-event recording.

If the request is rejected before AISIX contacts the upstream agent, check the status code:

  • 401: the caller API key is missing or invalid.
  • 403: the caller API key is valid, but its allowed_agents does not include the agent.
  • 404: the agent is unknown or disabled.

If AISIX cannot reach the upstream agent, or the upstream returns a non-success status, AISIX replies with HTTP 502 and a JSON-RPC error envelope with error.code set to -32000. The upstream response body is not proxied back to the caller.

Discover the Agent Card​

An agent card is the A2A discovery document that describes an agent's capabilities and service URL. Clients can discover the registered agent through AISIX instead of contacting the upstream agent directly:

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 upstream origin's well-known path:

https://<upstream-host>/.well-known/agent-card.json

Before returning the card, AISIX rewrites its service url to the gateway path, derived from the request Host header, so clients keep sending later calls through AISIX. Other card fields, including skills, capabilities, version, security schemes, and additional advertised endpoints, are preserved unchanged.

Current Limitations​

Agent Gateway is under active development. These current limitations affect which agent endpoints and controls you can rely on:

  • AISIX serves A2A JSON-RPC calls through /a2a/<agent>. It does not expose the A2A REST path-based endpoints, such as POST .../v1/message:send or GET .../v1/tasks/{id}.
  • OAuth 2.0 upstream authentication is not available. Use one of the supported upstream authentication modes: none, bearer, or api_key.
  • Guardrails do not scan A2A message content. Access control, rate limits, budgets, and usage apply to A2A calls. Guardrails continue to inspect model and MCP traffic.
  • A message/stream response is buffered and returned as one response instead of streamed chunk by chunk.
  • Register agents by their A2A HTTP URL. Direct registration for cloud agent runtime resources, such as Amazon Bedrock AgentCore, Azure AI Foundry, or Vertex AI Agent Engine, is not available yet.

Next Steps​

You have now learned how to register an A2A agent, grant caller access, call the agent through AISIX, and discover its agent card. Use these guides to refine how A2A traffic is handled: