Skip to main content
API7.ai Logo

Set Up Agent Gateway

AISIX exposes registered Agent-to-Agent (A2A) agents through caller-authenticated gateway endpoints at /a2a/<agent>. This setup connects an official A2A echo agent to an existing AISIX gateway, registers it, grants the quickstart caller access, and verifies an A2A 1.0 JSON-RPC request.

Follow either the AISIX Cloud or open-source configuration path. The registration steps differ, but both paths configure the same gateway behavior and use the same request to verify the result.

Prerequisites​

Before starting, prepare the following:

Start an A2A Test Agent​

The example runs the echo server provided by the official A2A Go SDK in Docker. The agent and your existing gateway join a temporary Docker network, so the gateway can reach the agent without a restart. Use the echo server only for local testing: it has no authentication and returns the caller's message text. Its generated A2A 1.0 card omits the compatibility url field that AISIX currently requires for card discovery. This setup therefore verifies the JSON-RPC call path, not the agent-card route. The container receives no secrets. Stop and remove it after finishing the guide.

Set the gateway container name for your configuration path.

For AISIX Cloud:

export AISIX_GATEWAY_CONTAINER="aisix-dp"

For the open-source AISIX gateway:

export AISIX_GATEWAY_CONTAINER="aisix-quickstart"

Create a temporary network and connect the running gateway to it:

docker network create aisix-a2a
docker network connect aisix-a2a "$AISIX_GATEWAY_CONTAINER"

Start the echo agent on the same network. The pinned Go SDK is downloaded and compiled inside the container, so the first startup can take about a minute:

docker run -d --name aisix-a2a-echo \
  --network aisix-a2a \
  golang:1.25-alpine \
  sh -c 'go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.4.0 \
    serve --echo --host 0.0.0.0 --port 8080 \
    --transport jsonrpc --protocol latest --name "AISIX A2A Echo"'

Wait until the agent is ready:

for attempt in $(seq 1 120); do
  docker logs aisix-a2a-echo 2>&1 | grep -q "Listening on" && break
  sleep 1
done

docker logs aisix-a2a-echo 2>&1 | grep "Listening on"

The final command prints the listener address. From the gateway container, the agent is available at http://aisix-a2a-echo:8080.

Register the Agent and Grant Access​

Register the agent using the management path for your deployment. Both paths name the agent echo-agent, pin it to A2A 1.0, and grant it to the existing quickstart caller.

AISIX Cloud​

Register the test agent and expose it to the quickstart environment:

A2A_AGENT_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/a2a_agents" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "name": "echo-agent",
  "url": "http://aisix-a2a-echo:8080",
  "protocol_version": "1.0",
  "auth_type": "none",
  "allowed_environments": ["${ENV_ID}"]
}
EOF
)

export A2A_AGENT_ID=$(echo "$A2A_AGENT_RESPONSE" | jq -er '.a2a_agent.id')
echo "$A2A_AGENT_RESPONSE" | jq

❶ protocol_version identifies the wire format that callers and the upstream agent use. AISIX forwards requests without translating between versions.

❷ allowed_environments controls which environments receive this organization-level resource.

Grant echo-agent to the caller API key created by the quickstart:

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allowed_agents":["echo-agent"]}' | jq

export AISIX_A2A_KEY="$AISIX_API_KEY"

The partial update retains the key's existing model access. The control plane projects both resources to the attached gateway automatically.

Open-Source AISIX Gateway​

In the existing resources.yaml, add allowed_agents to the quickstart caller and add the a2a_agents collection. Keep the existing provider key and model entries unchanged:

resources.yaml
api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
    allowed_agents:
      - echo-agent

a2a_agents:
  - name: echo-agent
    url: http://aisix-a2a-echo:8080
    protocol_version: "1.0"
    auth_type: none

❶ allowed_agents grants the quickstart caller the registered echo-agent.

❷ name becomes the caller-facing path segment under /a2a.

Validate the complete file inside the running gateway container, then reload it without restarting the container:

docker exec aisix-quickstart \
  aisix validate --resources /etc/aisix/resources.yaml

docker kill --signal HUP aisix-quickstart

export AISIX_A2A_KEY="$CALLER_API_KEY"

If the updated file is invalid, the gateway keeps serving the last valid configuration. Check docker logs aisix-quickstart for the rejected load.

Verify the A2A Call​

The commands in this section are the same for both management paths. They use the existing AISIX_PROXY value and the caller credential saved in AISIX_A2A_KEY.

AISIX Cloud can take a few seconds to project configuration to a gateway. Poll the agent for up to 90 seconds:

for attempt in $(seq 1 45); do
  A2A_RESPONSE=$(curl -sS -X POST "$AISIX_PROXY/a2a/echo-agent" \
    -H "Authorization: Bearer $AISIX_A2A_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": "req-1",
      "method": "SendMessage",
      "params": {
        "message": {
          "messageId": "msg-1",
          "role": "ROLE_USER",
          "parts": [{"text": "Hello through AISIX"}]
        }
      }
    }') || true

  if echo "$A2A_RESPONSE" | jq -e \
    '.result.task.artifacts[].parts[] | select(.text == "Hello through AISIX")' \
    >/dev/null 2>&1; then
    break
  fi
  sleep 2
done

echo "$A2A_RESPONSE" | jq -e \
  '.result.task.artifacts[].parts[] | select(.text == "Hello through AISIX")'

The final command prints the matching text part. AISIX authenticated the caller, checked its agent grant, and forwarded the JSON-RPC request unchanged to the echo agent.

Adapt the Setup for Your Agent​

Replace the test URL with an A2A JSON-RPC endpoint reachable from the gateway. Set protocol_version to the wire format the agent supports, and send requests in that format. AISIX supports "1.0" and "0.3" but does not translate between them.

Configure a required upstream credential with auth_type and secret. See Upstream Authentication.

For an open-source AISIX gateway, validate the complete resources file and send SIGHUP when the running gateway already has every referenced environment variable. If you add or change an environment variable, recreate the container with the new value. See Reload a Resources File.

Clean Up​

Keep the agent and caller grant if you plan to continue with the other Agent Gateway guides. Otherwise, remove the resources added through your management path.

For AISIX Cloud, clear the caller's agent grant and delete the agent:

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allowed_agents":[]}' | jq

curl -fsS -X DELETE "$AISIX_CP/a2a_agents/$A2A_AGENT_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

For an open-source AISIX gateway, remove the allowed_agents and a2a_agents additions from resources.yaml, validate the file, and send SIGHUP again.

Remove the test agent and temporary network:

docker rm -f aisix-a2a-echo
docker network disconnect aisix-a2a "$AISIX_GATEWAY_CONTAINER"
docker network rm aisix-a2a

Next Steps​

You have now registered an A2A agent, granted caller access, and sent an A2A 1.0 request through AISIX. Use these guides to extend the setup: