按 Key 控制 Agent 访问

调用方 API Key 的 allowed_agents 决定该 Key 可以访问哪些 A2A Agent。网关会在每个 A2A 请求上检查该字段，包括 /a2a/<agent> 的 JSON-RPC 调用，以及 /a2a/<agent>/.well-known/agent-card.json 的 Agent card 获取请求。对于不在允许列表中的 Agent，AISIX 会在联系上游 Agent 之前拒绝请求。

没有 allowed_agents 的 Key（字段省略、为 null 或为空列表）不能访问任何 A2A Agent。访问权限需要显式授予。

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

匹配规则

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

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

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

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor", "research-assistant"]
  }'

这个 Key 可以访问 invoice-processor 和 research-assistant 两个 Agent，不能访问其它 Agent。

高级匹配

条目使用单 * 通配模式，与 allowed_tools 使用同一个匹配器，因此 * 可以出现在模式内部，例如 invoice-* 会授权所有名称以 invoice- 开头的 Agent。除非明确需要前缀模式，否则建议优先使用精确名称或 *。

更新 Key 的 Agent 访问权限

更新操作会替换整个资源，因此请同时带上现有 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" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }'

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

执行方式

网关会在确认 Agent 存在且已启用后，对每个 A2A 请求检查 allowed_agents：

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

Agent card 端点也会执行同样检查，因此调用方既不能调用授权范围外的 Agent，也不能发现其 card。由于存在性检查会先执行，已认证调用方可以区分自己无权访问的 Agent（403）和不存在的 Agent（404）；请据此谨慎设置 allowed_agents 范围。

在 AISIX Cloud 中管理 Agent 访问

在 AISIX Cloud 中，可以在 Dashboard 的调用方 API Key 表单中设置 Agent 访问权限，而不是使用 Admin API。你可以授权该 Key 访问所有 A2A Agent，也可以选择暴露到该 Key 所属环境中的具体 Agent。编辑该 Key 时，已保存的授权会映射回这些控件。更多信息请参见 AISIX Cloud。

下一步

上游认证：配置 AISIX 如何认证到每个 Agent。
Agent 网关概览：注册 Agent 并完成端到端访问。
调用方 API Key：管理调用方凭证。

匹配规则​

更新 Key 的 Agent 访问权限​

执行方式​

在 AISIX Cloud 中管理 Agent 访问​

下一步​

匹配规则

更新 Key 的 Agent 访问权限

执行方式

在 AISIX Cloud 中管理 Agent 访问

下一步