跳到主要内容
版本：1.8.0

控制 Agent 访问权限

对于 Agent-to-Agent（A2A）流量，每个调用方 API Key 都定义了该调用方可以访问哪些已注册 Agent。除非 API Key 的 allowed_agents 授权涵盖 Agent 的注册名称，否则 AISIX 会拒绝 Agent 调用和 Agent Card 发现请求。

当共享同一网关的不同客户端需要访问不同上游 Agent 时，请分别配置授权。本指南介绍 AISIX 如何匹配 Agent 名称和模式、如何通过 AISIX Cloud 或 resources.yaml 更新授权，以及请求超出授权范围时的行为。

前置条件​

请完成 AISIX Cloud 或开源 AISIX 网关的配置 Agent 网关。如需验证修改后的授权，请保持 Shell、网关和测试 Agent 运行。

Agent 访问权限的工作原理​

allowed_agents 是调用方 API Key 上的 Agent 名称模式列表。如果省略该字段，或将其设置为 null 或空列表，则该 API Key 没有 A2A Agent 访问权限。

每个模式都与 Agent 注册的 name 进行匹配：

条目授予的权限示例
精确名称一个 Agent。invoice-processor 仅授予对该 Agent 的访问权限。
名称模式名称与一个 * 通配符匹配的 Agent。invoice-* 授予对名称以 invoice- 开头的所有 Agent 的访问权限。
*所有已注册 Agent。* 授予对当前和未来 Agent 的访问权限。

如需最小访问权限，请使用精确名称。只有当调用方可以访问当前和未来的所有 Agent 时，才使用 *。

匹配器与 MCP 工具模式使用的单 * Glob 匹配器相同。一个条目最多只能包含一个 *。AISIX Cloud Admin API 会以 400 拒绝含两个及以上 * 的条目。resources 文件不做这项检查，但这类条目不授予任何 Agent。

配置 Agent 访问权限​

设置调用方应保留的完整 Agent 列表。AISIX Cloud 将授权存储在 API Key 资源中；开源 AISIX 网关从 resources.yaml 中读取授权。

AISIX Cloud​

更新配置指南中创建的调用方 API Key：

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

该部分更新会替换原有 Agent 授权，同时保留 API Key 的模型、MCP 和其他设置。控制面会自动将更改下发到已连接的网关。

如需撤销所有 A2A Agent 访问权限，请发送 "allowed_agents": [] 或 "allowed_agents": null。

开源 AISIX 网关​

将现有的 quickstart-caller 条目替换为以下更新后的条目，以设置 allowed_agents。保留 api_keys 中的所有其他条目及所有无关集合，不要创建第二个顶层 api_keys 键：

resources.yaml（Agent 访问权限）
api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
    allowed_agents:
      - echo-agent
      - invoice-*

验证完整文件并重新加载：

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

docker kill --signal HUP aisix-quickstart

删除 allowed_agents 或将其设置为空列表，即可撤销此调用方的所有 A2A Agent 访问权限。

执行访问控制的方式​

网关会先确认 Agent 存在且已启用，再检查授权。对于 A2A 调用和 Agent Card 发现，网关都会在联系上游 Agent 之前执行此检查：

  • 对 /a2a/<agent> 的 JSON-RPC 调用。
  • 对 /a2a/<agent>/.well-known/agent-card.json 的 Agent Card 请求。

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

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

由于系统先检查 Agent 是否存在，经过身份认证的调用方可以区分无权访问的 Agent 与不存在的 Agent。

后续步骤​

你已限定调用方 API Key 可以访问的 Agent。可以继续阅读以下指南，完善调用方和上游控制路径：