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 and grants the quickstart caller access. The official A2A Go SDK client then sends an A2A 1.0 message through the gateway.

Follow either the AISIX Cloud or open-source configuration path. The registration steps differ, but both paths configure the same gateway behavior. After either path, use the same agent-card readiness check and SDK client call 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. The server publishes a dual A2A 0.3 and 1.0 compatibility card so you can also verify client-facing discovery through AISIX. The echo server starts without upstream credentials; later client checks pass the disposable quickstart caller key into this test container. 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.5.0 \
    serve --echo --card-compat --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 (caller and agent)
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 with an A2A Client​

The commands in this section are the same for both management paths. First, wait until the gateway can fetch the registered agent's card. This preserves the projection tolerance needed by AISIX Cloud without sending a handcrafted JSON-RPC message:

for attempt in $(seq 1 45); do
  curl -fsS \
    "$AISIX_PROXY/a2a/echo-agent/.well-known/agent-card.json" \
    -H "Authorization: Bearer $AISIX_A2A_KEY" \
    >/dev/null 2>&1 && break
  sleep 2
done

curl -fsS \
  "$AISIX_PROXY/a2a/echo-agent/.well-known/agent-card.json" \
  -H "Authorization: Bearer $AISIX_A2A_KEY" \
  >/dev/null

Set the agent URL that the client container can reach. Both AISIX quickstart guides use port 3000 inside the gateway container:

export AISIX_A2A_URL="http://${AISIX_GATEWAY_CONTAINER}:3000/a2a/echo-agent"

Run the command-line client from the official A2A Go SDK inside the echo-agent container. --transport jsonrpc connects directly to the registered AISIX endpoint instead of resolving an agent card first:

docker exec aisix-a2a-echo \
  go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
  send "$AISIX_A2A_URL" "Hello through AISIX" \
  --transport jsonrpc \
  --auth "Bearer $AISIX_A2A_KEY" \
  --output json | jq -e \
  '.artifacts[].parts[] | select(.text == "Hello through AISIX")'

The command prints the matching artifact part. AISIX authenticated the caller, checked its agent grant, and forwarded the SDK client's A2A 1.0 request 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 message through AISIX with the official SDK client. Use these guides to extend the setup: