Skip to main content
API7.ai Logo

Control Agent Access

For Agent-to-Agent (A2A) traffic, each caller API key defines which registered agents that caller can reach. AISIX denies agent calls and agent-card discovery unless the key's allowed_agents grant covers the agent's registered name.

Use separate grants when clients sharing a gateway need access to different upstream agents. This guide explains how AISIX matches agent names and patterns, how to update grants through AISIX Cloud or resources.yaml, and what happens when a request falls outside the grant.

Prerequisites​

Complete Set Up Agent Gateway for AISIX Cloud or the open-source AISIX gateway. Keep the shell, gateway, and test agent running if you want to verify a changed grant.

How Agent Access Works​

allowed_agents is a list of agent-name patterns on the caller API key. When the field is omitted, null, or an empty list, the key has no A2A agent access.

Each pattern is matched against the agent's registered name:

EntryGrantsExample
Exact nameOne agent.invoice-processor grants only that agent.
Name patternAgents whose names match one * wildcard.invoice-* grants every agent whose name starts with invoice-.
*Every registered agent.* grants current and future agents.

Choose exact names for the narrowest access. Use * only for a caller that may reach every current and future agent.

The matcher is the same single-* glob matcher used by allowed_tools. An entry can contain at most one *.

Configure Agent Access​

Set the complete list of agents that the caller should keep. AISIX Cloud stores the grant on the API key resource; an open-source AISIX gateway reads it from resources.yaml.

AISIX Cloud​

Update the caller API key created in the setup guide:

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", "invoice-*"]
  }' | jq

This partial update replaces the previous agent grant while retaining the key's model, MCP, and other settings. The control plane projects the change to attached gateways automatically.

To revoke all A2A agent access, send "allowed_agents": [] or "allowed_agents": null.

Open-Source AISIX Gateway​

Set allowed_agents on the caller entry in resources.yaml:

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

Validate the complete file and reload it:

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

docker kill --signal HUP aisix-quickstart

Remove allowed_agents or set it to an empty list to revoke all A2A agent access for this caller.

How Enforcement Works​

The gateway checks the grant after confirming that the agent exists and is enabled. It performs the check before contacting the upstream agent for both A2A calls and agent-card discovery:

  • JSON-RPC calls to /a2a/<agent>.
  • Agent-card requests to /a2a/<agent>/.well-known/agent-card.json.

The caller-visible outcome depends on the agent and key state:

  • An unknown or disabled agent returns 404.
  • A known agent outside the key's grant returns 403 before AISIX contacts the upstream agent.
  • A known agent covered by the key's grant is forwarded upstream.

Because the existence check runs first, an authenticated caller can distinguish an agent it cannot access from an agent that does not exist.

Next Steps​

You have now scoped which agents a caller API key may reach. Use these guides to complete the caller and upstream control path: