Skip to main content
API7.ai Logo

Agent Gateway Overview

AISIX exposes registered Agent-to-Agent (A2A) agents at /a2a/<agent>, giving A2A clients and other agents one authenticated path to reach them. Callers present an AISIX caller API key; the gateway checks whether the key may reach the target and forwards the A2A JSON-RPC request without exposing the upstream credential.

Agent traffic therefore uses the same authentication, access-control, traffic-control, and telemetry boundary as model and MCP traffic. The same caller API key can govern the models, MCP tools, and A2A agents a caller may use.

Each A2A agent resource represents one upstream agent that speaks the A2A protocol over HTTP with JSON-RPC 2.0.

How the Agent Gateway Works​

Each upstream agent has a name. AISIX exposes the agent at /a2a/<name> on the proxy listener. In AISIX Cloud, the agent is registered at the organization level and exposed to selected environments. In an open-source AISIX gateway, it is normally declared in resources.yaml.

AISIX forwards the request body unchanged. Each agent resource is pinned to A2A 1.0 or 0.3, and the caller must use the format configured for that agent. AISIX does not translate between protocol versions.

For an agent call that passes authentication and access checks, the gateway applies request and concurrency limits, contacts the agent with its configured upstream credential, and records A2A usage telemetry. AISIX Cloud can also apply budgets that cover the caller API key.

Get Started​

Follow Set Up Agent Gateway to run an A2A echo agent, register it through AISIX Cloud or resources.yaml, grant caller access, and send an A2A 1.0 request through the gateway. Both management paths configure the same gateway runtime and A2A endpoint.

Client Connection​

A2A clients call the registered agent on the AISIX proxy listener:

SettingValue
Agent URL<gateway-origin>/a2a/<agent-name>
ProtocolA2A 1.0 or 0.3 over HTTP with JSON-RPC 2.0
Request headerAuthorization: Bearer <caller-api-key>

The caller API key controls which agents the client may reach. The client connects only to AISIX; it does not receive the upstream credential.

The endpoint accepts the JSON-RPC methods defined by the agent's configured A2A version, including message, task, streaming, and push-notification configuration methods. Streaming methods return text/event-stream, and AISIX relays each event as the upstream agent emits it.

Agent Cards​

Clients can request a registered agent's discovery document through AISIX:

GET /a2a/<agent-name>/.well-known/agent-card.json

The request uses the same caller authentication and agent-access check as an A2A call. AISIX fetches the upstream card with the agent's configured upstream credential, then rewrites every advertised service URL to the gateway path. Other card fields are preserved.

AISIX derives the advertised scheme from X-Forwarded-Proto and the authority from Host. Configure a trusted reverse proxy to set these headers to the gateway's public address. When X-Forwarded-Proto is absent, AISIX uses https.

The upstream card currently must include the top-level url field used by A2A 0.3. For an A2A 1.0 agent, publish a compatibility card with both url and supportedInterfaces. AISIX rewrites every service URL in the card.

AISIX first checks agent-card.json under the registered path and then under its origin. If neither location returns a usable card, AISIX repeats the checks for the earlier agent.json filename.

Govern A2A Calls​

A2A calls use the same caller API key boundary as model requests. You do not configure a separate policy stack for agent traffic.

Use these guides to refine the A2A path:

Current Limitations​

The following limitations affect the agent interfaces and controls that AISIX exposes:

  • AISIX serves A2A JSON-RPC calls through /a2a/<agent>. It does not expose 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 none, bearer, or api_key as described in Upstream Authentication.
  • Guardrails do not scan A2A message content. Access control, request and concurrency limits, AISIX Cloud budgets, and usage telemetry still apply.
  • 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.

Troubleshoot Agent Calls​

If a caller cannot reach an agent, check these items:

  • The A2A agent resource is enabled and reachable from the gateway.
  • In AISIX Cloud, allowed_environments includes the caller key's environment.
  • The caller API key's allowed_agents grant covers the registered agent name.
  • The request body and method use the agent's configured A2A protocol version.
  • The configured upstream authentication matches what the agent expects.

A missing or invalid caller API key returns 401. A known agent outside the key's grant returns 403, while an unknown or disabled agent returns 404. For a JSON-RPC call, an unreachable upstream or an unsuccessful upstream HTTP status returns 502 with a JSON-RPC error envelope; AISIX does not expose the upstream response body. An unsuccessful agent-card fetch also returns 502, but as an ordinary HTTP error rather than a JSON-RPC envelope.

For endpoint-level behavior, see Proxy API Reference. For error response details, see Headers and Error Codes.

Next Steps​

Use these guides to configure how A2A traffic is handled: