跳到主要内容

上游认证

每个已注册的 A2A Agent 都会保存 AISIX 用来认证到该上游 Agent 的凭证。AISIX 在网关侧持有该凭证，并在转发调用时向上游出示。A2A 客户端发送给 AISIX 的调用方 API Key 只用于认证调用方到 AISIX，不会被转发或暴露给上游 Agent。

在注册或更新 Agent 时，通过 auth_type 字段及其配套字段设置上游凭证。AISIX 会把同一凭证用于它对上游执行的两类操作：获取 Agent card，以及转发 JSON-RPC 调用。

认证模式​

请选择与上游 Agent 要求 AISIX 使用的认证方式相匹配的模式：

auth_type上游凭证AISIX 如何发送
none无不发送凭证。
bearersecret（Bearer Token）Authorization: Bearer <secret>
api_keysecret（API Key）x-api-key: <secret>

secret 保存 AISIX 需要向上游出示的明文凭证。该凭证只在网关侧使用，不会发送给调用方客户端。要轮换凭证，请使用新的 secret 更新资源。

无认证​

当上游 Agent 不需要凭证时使用 none，例如该 Agent 只在可信内部网络中可访问。

下面的示例会创建一个不带上游凭证的 Agent 资源：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "invoice-processor",
    "url": "https://agents.internal/invoice",
    "protocol_version": "0.3",
    "auth_type": "none"
  }'

auth_type 默认为 none，因此也可以省略。none Agent 不应设置 secret。

Bearer Token​

当上游 Agent 期望在 Authorization 请求头中收到静态令牌时，使用 bearer，并把该令牌写入 secret。

下面的示例会创建一个 Agent 资源，并配置 AISIX 向上游发送的 Bearer Token：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "research-assistant",
    "url": "https://agents.example.com/a2a",
    "protocol_version": "0.3",
    "auth_type": "bearer",
    "secret": "YOUR_UPSTREAM_TOKEN"
  }'

❶ bearer 会在每个发往该上游的请求中发送 Authorization: Bearer <secret>。

❷ secret 必填且不能为空。

API Key​

当上游 Agent 期望在 x-api-key 请求头中收到 Key 时，使用 api_key，并把 Key 写入 secret。

下面的示例会创建一个 Agent 资源，并配置 AISIX 向上游发送的 API Key：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "translator",
    "url": "https://agents.example.com/translate",
    "protocol_version": "0.3",
    "auth_type": "api_key",
    "secret": "YOUR_UPSTREAM_API_KEY"
  }'

❶ api_key 会在每个发往该上游的请求中发送 x-api-key: <secret>。

❷ secret 必填且不能为空。

凭证处理​

上游凭证绝不会传递给调用方客户端。客户端只出示自己的 AISIX 调用方 API Key，AISIX 使用该 Agent 配置的凭证转发请求。

如果凭证后续失效（例如密钥被轮换或吊销），只有该 Agent 的调用会失败，其它已注册 Agent 仍可正常工作。AISIX 返回 HTTP 502；上游状态只会出现在 JSON-RPC 错误信息中，上游响应体不会被代理返回。

AISIX 提供的 Agent card 包含上游 Agent 声明的元数据，并将服务 url 重写为网关地址，其中不包含上游凭证。

下一步​

你现在已了解 AISIX 如何向上游 Agent 认证。使用以下指南控制哪些调用方可以访问这些 Agent，以及如何治理其流量：

  • 控制 Agent 访问：将调用方 API Key 的权限限定为特定 Agent 或全部 Agent。
  • 限流与预算：对 A2A 调用应用请求限制、并发限制和预算。
  • 可观测性：查看 A2A 调用产生的用量事件和指标。