跳到主要内容

按 Key 控制 Agent 访问

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

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

本页示例使用 AISIX Cloud Admin API。请使用组织的控制面 URL、环境 ID 和具有写入权限的 Admin Token。对于 On-Premises 部署，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。然后设置：

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

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 名称匹配：

条目授权范围示例
精确名称一个指定 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 "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "a2a-client",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor", "research-assistant"]
  }'

响应只会返回一次生成的 Key plaintext，请将其保存在客户端，因为无法再次获取。A2A 客户端使用该值作为 Bearer Token。还要记录响应中 api_key 对象的 Key id，更新操作需要使用该 ID。

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

更新 Key 的 Agent 访问权限​

当授权范围发生变化时，更新调用方 API Key。更新操作使用部分 PATCH：省略的字段会保留当前值，但 allowed_agents 本身是替换列表，因此请发送该 Key 应继续保留的完整 Agent 集合：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_agents": ["invoice-processor"]
  }'

此更新会将之前的 Agent 授权替换为只允许 invoice-processor。由于请求中没有包含 allowed_models 和其他设置，这些字段不会改变。

要撤销该 Key 的全部 A2A Agent 访问权限，请把 allowed_agents 设置为 [] 或 null。该 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）。

AISIX Cloud 控制面​

本页命令直接调用控制面，生成的 Key 配置会自动下发到环境关联的每个网关。所有部署方式使用相同的授权模型：调用方 API Key 可以限定为访问指定 Agent，也可以访问环境中所有 Agent。该工作流适用于 AISIX Cloud 的两种控制面部署方式：On-Premises 和 Hybrid Cloud。

下一步​

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

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