Skip to main content
API7.ai Logo

Control Agent Access

For Agent-to-Agent (A2A) traffic, the caller API key is the access boundary. A key cannot invoke or discover an agent until access is granted explicitly.

Configure agent access when different clients should reach different upstream agents through the same gateway. This guide explains how AISIX matches agent grants, how to create or update a key with agent access, and how enforcement behaves when a caller reaches an agent path.

How Agent Access Works​

Agent access is stored on the caller API key in allowed_agents. The value is a list of registered agent names. When the field is omitted, null, or an empty list, the key has no A2A agent access.

Grant agent names directly. Each A2A agent is identified by its registered display_name, such as invoice-processor. This differs from MCP tool access, where grants can target individual tools under a server namespace, such as <server>__<tool>.

Each entry in allowed_agents is matched against the agent name:

EntryGrantsExample
Exact nameOne specific agent.invoice-processor allows only that agent.
*Every registered agent.* allows all current and future agents.

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

allowed_agents uses the same single-* glob matcher as allowed_tools. A pattern such as invoice-* grants every agent whose name starts with invoice-.

Create a Key with Agent Access​

Create the caller API key that the A2A client uses. This example grants access to two agents:

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", "research-assistant"]
  }
EOF

The empty allowed_models list makes this key agent-only. The key can reach only the agents listed in allowed_agents.

Update Agent Access for a Key​

Update the caller API key when its agent grant changes. The Admin API PUT replaces the whole key resource, so include the existing key hash and any other fields you want to keep, along with the new allowed_agents:

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -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

This update keeps the key agent-only and replaces the previous agent grant with invoice-processor only. If the key also needs model access, keep its existing allowed_models values in the update.

To revoke all A2A agent access for a key, set allowed_agents to []. The key keeps its model access and other settings but can no longer reach any agent.

How Enforcement Works​

The gateway checks the key's agent grant after confirming the agent exists and is enabled. AISIX performs this check before contacting the upstream agent for both A2A calls and agent-card discovery:

  • JSON-RPC calls to /a2a/<agent>.
  • Agent-card fetches from /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 the key does not allow returns 403, before AISIX contacts the upstream agent.
  • A known agent the key allows is forwarded upstream.

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

Managed Control Plane​

In a managed deployment, configure agent access from the control plane instead of sending these Admin API commands directly. The same grant model applies: a caller API key can be scoped to individual agents or to every agent available in the environment. This workflow is available with AISIX Cloud and AISIX Cloud On-Premises.

Next Steps​

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