Agent 网关概览

AISIX AI 网关可以在自己的网关路径上代理已注册的上游 A2A（Agent-to-Agent）Agent。调用方使用 AISIX 调用方 API Key 访问 /a2a/<agent>，AISIX 再把 A2A JSON-RPC 请求转发给上游 Agent。上游凭证保留在网关侧，调用方不会接触到这些凭证。

这样，Agent 流量就可以与模型流量共用同一个认证、访问控制、策略和遥测边界。一个调用方 API Key 可以同时控制调用方可使用的模型、可调用的 MCP 工具，以及可访问的 A2A Agent。AISIX 会认证调用方、检查 Agent 访问权限、应用限流和预算、使用你配置的上游凭证转发请求，并记录 A2A 用量遥测。

A2A Agent 是一个网关注册项，代表一个通过 HTTP 和 JSON-RPC 2.0 提供 A2A 协议的上游 Agent。本页介绍 Agent 网关，并演示一个最小端到端配置。深入了解各主题请参见：

上游认证：AISIX 如何使用 none、bearer 或 api_key 认证到每个上游 Agent。
按 Key 控制 Agent 访问：调用方 API Key 上的 allowed_agents 如何决定该 Key 可访问哪些 Agent。
限流与预算：调用方 API Key 的限流和预算如何治理 A2A 调用。
可观测性：A2A 调用会产生哪些用量事件和指标。

Agent 网关如何工作

每个上游 Agent 都会以一个 display_name 注册为网关资源。AISIX 会在代理监听器上通过 /a2a/<display_name> 暴露该 Agent，并把每个 JSON-RPC 请求体原样转发给上游 Agent。

由于 AISIX 会原样转发请求体，调用方需要使用目标 Agent 固定的 A2A 传输版本。网关不会在 0.3 和 1.0 格式之间做协议转换，因此调用方必须发送该目标 Agent 注册时指定的版本。

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个通过 HTTP 提供 A2A 协议的上游 Agent 及其 URL。
一个 A2A 客户端将发送给 AISIX 的调用方 API Key。

托管部署

在 AISIX Cloud 中，可以通过 Dashboard 注册 A2A Agent 并授予 Agent 访问权限；这些配置以组织为范围，并按环境暴露。概念相同，只是管理界面不同。请参见 AISIX Cloud。

注册 A2A Agent

为上游端点创建一个 A2A Agent 资源。display_name 会成为该 Agent 暴露路径中的片段（/a2a/<display_name>），因此必须是单个 URL 路径片段，且在网关内唯一。下面示例注册一个不需要上游凭证的 Agent；其它认证方式请参见上游认证。

export AISIX_ADMIN_KEY="YOUR_ADMIN_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": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none"
  }'

你会看到类似响应：

{
  "id": "1d95ac57-7f27-46a4-b5a3-55d3c3ad0a12",
  "value": {
    "display_name": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none",
    "enabled": true
  },
  "revision": 1
}

如果后续需要更新、查看或删除该 Agent，请复制高亮的 id。

关键字段如下：

字段	说明
`display_name`	Agent 暴露路径中的片段（`/a2a/<display_name>`）。必须非空、不能包含 `/`，且在网关内唯一。重复名称会以 `409` 拒绝。
`url`	上游 Agent 的 A2A 服务端点，通过 HTTP 和 JSON-RPC 2.0 访问。
`protocol_version`	AISIX 为该 Agent 固定的 A2A 传输格式：`1.0`（默认）表示 protobuf-JSON 封装，`0.3` 表示带 `kind` 区分的 JSON-RPC 封装。
`auth_type`	AISIX 认证到上游 Agent 的方式：`none`（默认）、`bearer` 或 `api_key`。详见上游认证。
`secret`	所选 `auth_type` 的上游凭证。凭证保留在网关侧，不会发送给调用方客户端。
`timeout_ms`	单次上游操作超时时间，单位毫秒。默认 `30000`（30 秒）。
`enabled`	是否提供该 Agent。默认 `true`；设置为 `false` 时会保留注册，但 `/a2a/<display_name>` 返回 `404`。

授予 Agent 访问权限

调用方使用 AISIX 调用方 API Key 访问 Agent，而不是使用 Admin Key。访问需要显式授权：没有 allowed_agents 的 Key 不能访问任何 Agent。

创建调用方 API Key 时，指定它可以访问的 Agent。创建资源前，请先对明文调用方 Key 计算哈希：

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="sk-demo-caller"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

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"]
  }'

["invoice-processor"] 会授予该 Key 访问一个 Agent 的权限。使用 ["*"] 可以授权访问所有 Agent。如果该 Key 只用于 A2A 流量，可以把模型允许列表设为空。完整匹配规则请参见按 Key 控制 Agent 访问。

如果后续需要更新该调用方 API Key，请保存返回的 id。

通过网关访问 Agent

把 A2A JSON-RPC 请求发送到代理监听器上的 /a2a/<display_name>，并在 Authorization 请求头中携带调用方 API Key。AISIX 会认证该 Key、检查 allowed_agents、应用限流和预算、把请求转发给上游 Agent，并记录一条用量事件。

请求体必须使用该 Agent 固定 protocol_version 对应的 A2A JSON-RPC 封装。下面示例使用的是上面注册 Agent 时指定的 0.3 格式：

export AISIX_API_KEY="sk-demo-caller"

curl -sS -X POST "http://127.0.0.1:3000/a2a/invoice-processor" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Review this vendor invoice."}],
        "messageId": "msg-1"
      }
    }
  }'

预期结果： AISIX 原样返回上游 Agent 的 JSON-RPC 响应。缺失或无效的调用方 API Key 会收到 401；有效但 allowed_agents 未包含目标 Agent 的 Key 会收到 403；未知或已禁用的 Agent 会返回 404。

AISIX 会通过这一条受治理路径转发所有 A2A JSON-RPC 方法，不只是 message/send。同一端点也接受 message/stream、tasks/get、tasks/cancel、tasks/resubscribe 以及推送通知配置相关方法。对于每个方法，AISIX 都会认证调用方 Key、检查 allowed_agents、应用限流和预算、原样转发请求体，并记录带有被调用方法标签的用量事件。它不会特殊处理某个方法，也不会修改请求或响应体。

如果网关无法访问上游 Agent，或上游返回非成功状态，AISIX 会返回 HTTP 502 和 JSON-RPC 错误封装（error.code 为 -32000）。错误信息会描述失败原因，包括上游有响应时的上游状态码，但不会把上游响应体透传给调用方。

发现 Agent Card

AISIX 会在 Agent 下的 well-known 路径提供上游 Agent card，并把其中声明的服务 url 重写为网关地址，让客户端后续请求继续经过 AISIX：

curl -sS "http://127.0.0.1:3000/a2a/invoice-processor/.well-known/agent-card.json" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

AISIX 会从上游 URL 的 origin 下 well-known 路径获取 card（https://<upstream-host>/.well-known/agent-card.json）。它会根据请求的 Host 头把 url 字段重写为 http(s)://<your-gateway-host>/a2a/invoice-processor，并保留其它所有 card 字段（skills、capabilities、version、security schemes）不变。

应用流量控制

A2A 调用与模型请求共用同一个调用方 API Key 边界，因此可以应用相同的控制能力：

限流和预算。 调用方 API Key 的请求速率限制和并发限制会作用于每个 /a2a/<agent> 调用；在托管部署中，AISIX Cloud 预算检查也会生效。被拒绝的调用会在 AISIX 联系上游 Agent 之前返回。详见限流与预算。
访问控制。 调用方 API Key 的 allowed_agents 列表控制该 Key 可以访问哪些 Agent。详见按 Key 控制 Agent 访问。
遥测。 每个调用都会产生用量事件，记录调用方 Key、Agent 名称和 JSON-RPC 方法。Token 和成本字段为零，因为该路径不计量模型 Token。详见可观测性。

当前行为与限制

Agent 网关目前支持上述流程。以下能力暂不可用：

备注

协议绑定。 AISIX 代理的是 POST /a2a/<agent> 的 A2A JSON-RPC binding，以及 Agent card 的 GET。REST/HTTP binding 中基于路径的方法，例如 POST .../v1/message:send 或 GET .../v1/tasks/{id}，目前不会被单独路由。
上游认证 目前仅支持 none、bearer 和 api_key。资源中可以接受 oauth2 作为向前兼容字段，但运行时尚未获取 Token；调用 oauth2 Agent 会返回 501。详见上游认证。
安全护栏 尚不会扫描 A2A 消息内容。当前已支持访问控制、限流、预算和用量统计；面向 A2A 的内容治理仍在规划中。与此同时，安全护栏可检查模型流量和 MCP 流量。
流式响应。 message/stream 响应会被缓冲后作为一个完整响应返回，而不是逐块流式返回。
协议转换 不会在 A2A 0.3 和 1.0 之间进行，AISIX 也不会从客户端信号中推断版本。它只会提供并转发该 Agent 注册时固定的版本，因此调用方必须发送该版本。
Agent card 重写 只覆盖 card 顶层服务 url。card 中声明的其它端点，例如 additionalInterfaces，会原样保留并继续指向上游 Agent。
托管平台 Agent 暂不能作为注册选项，例如托管在 Amazon Bedrock AgentCore、Azure AI Foundry 或 Vertex AI Agent Engine 等云端 Agent Runtime 中的 Agent。请使用 A2A HTTP URL 注册 Agent。

下一步

上游认证：为每个上游 Agent 配置 none、bearer 或 api_key。
按 Key 控制 Agent 访问：把调用方限定到特定 Agent 或全部 Agent。
限流与预算：在调用方 API Key 上限制和治理 A2A 调用。
可观测性：查看 A2A 调用产生的用量事件和指标。
调用方 API Key：管理调用方凭证及其 allowed_agents 列表。

Agent 网关如何工作​

准备工作​

注册 A2A Agent​

授予 Agent 访问权限​

通过网关访问 Agent​

发现 Agent Card​

应用流量控制​

当前行为与限制​

下一步​