按 Key 控制 Agent 访问

对于 Agent-to-Agent（A2A）流量，调用方 API Key 是访问边界。只有显式授权后，一个 Key 才能调用或发现 Agent。

当不同客户端需要通过同一个网关访问不同的上游 Agent 时，应配置 Agent 访问权限。本页说明 AISIX 如何匹配 Agent 授权、如何创建或更新带 Agent 权限的 Key，以及调用方访问 Agent 路径时网关如何执行权限检查。

Agent 访问权限的工作方式

调用方 API Key 的 allowed_agents 决定该 Key 可以访问哪些 A2A Agent。没有 allowed_agents 的 Key（字段省略、为 null 或为空列表）不能访问任何 A2A Agent。

每个 A2A Agent 都是一个可寻址单元，由其 display_name 标识，例如 invoice-processor。因此授权列表直接写 Agent 名称，而不是 MCP 工具使用的 <server>__<tool> 组合。

每个 allowed_agents 条目都会作为单 * 通配模式与 Agent 的 display_name 匹配：

条目	授权范围	示例
精确名称	一个指定 Agent。	`invoice-processor` 只允许访问该 Agent。
`*`	所有已注册 Agent。	`*` 允许访问当前和未来的所有 Agent。

请为调用方选择满足需求的最小权限。可以逐个列出调用方需要访问的 Agent，也可以对确实需要全量访问的 Key 使用 *。

allowed_agents 与 allowed_tools 使用同一个单 * 通配匹配器。例如，invoice-* 会授权所有名称以 invoice- 开头的 Agent。

创建带 Agent 访问权限的 Key

创建 A2A 客户端使用的调用方 API Key。下面的示例授权访问两个 Agent：

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

空的 allowed_models 列表让这个 Key 仅用于 Agent。该 Key 只能访问 allowed_agents 中列出的 Agent。

更新 Key 的 Agent 访问权限

当授权范围发生变化时，更新调用方 API Key。Admin API 的 PUT 会替换整个 Key 资源，因此请同时带上现有 Key 哈希、需要保留的其它字段和新的 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

此更新让 Key 继续保持仅用于 Agent，并将之前的授权替换为只允许 invoice-processor。如果该 Key 还需要访问模型，请在更新时保留原有的 allowed_models 值。

要撤销该 Key 的全部 A2A Agent 访问权限，请把 allowed_agents 设置为 []。该 Key 会保留模型访问权限和其它配置，但不能再访问任何 Agent。

执行方式

网关会在确认 Agent 存在且已启用后检查 Key 的 Agent 授权。对于 A2A 调用和 Agent card 发现，AISIX 都会在联系上游 Agent 之前完成此检查：

对 /a2a/<agent> 的 JSON-RPC 调用。
从 /a2a/<agent>/.well-known/agent-card.json 获取 Agent card。

调用方看到的结果取决于 Agent 和 Key 的状态：

未知或已禁用的 Agent 返回 404。
已知但该 Key 未授权的 Agent 返回 403，且 AISIX 不会联系上游 Agent。
已知且该 Key 已授权的 Agent 会被转发到上游。

由于存在性检查会先执行，已认证调用方可以区分自己无权访问的 Agent（403）和不存在的 Agent（404）。

托管控制面

在托管部署中，请通过控制面配置 Agent 访问，而不是直接发送这些 Admin API 命令。授权模型保持不变：调用方 API Key 可以限定为访问指定 Agent，也可以访问环境中所有 Agent。该工作流适用于 AISIX Cloud 和 AISIX Cloud On-Premises。

下一步

你现在已经限定了每个调用方 API Key 可以访问的 Agent。请使用以下指南完成调用方和上游控制路径：

上游认证：配置 AISIX 如何认证到每个 Agent。
限流与预算：对 A2A 调用应用请求限制、并发限制和预算。
调用方 API Key：查看同时治理模型和 MCP 流量的共享 Key 设置。

Agent 访问权限的工作方式​

创建带 Agent 访问权限的 Key​

更新 Key 的 Agent 访问权限​

执行方式​

托管控制面​

下一步​

Agent 访问权限的工作方式

创建带 Agent 访问权限的 Key

更新 Key 的 Agent 访问权限

执行方式

托管控制面

下一步