跳到主要内容

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 网关，并演示如何通过自托管网关注册和调用 Agent。

Agent 网关如何工作​

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

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

注册并调用 Agent​

下面的示例会注册一个上游 A2A Agent，授予调用方 API Key 访问权限，并通过网关发送请求。

前提条件​

请先准备以下内容：

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

在托管部署中，可以通过控制面工作流注册 A2A Agent 并授予 Agent 访问权限；概念相同，只是管理界面不同。该工作流适用于 AISIX Cloud 和 AISIX Cloud On-Premises。

注册 A2A Agent​

下面的示例注册一个使用 A2A 0.3 传输格式且不需要凭证的上游 Agent。为上游端点创建 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
}

❶ display_name 会成为 AISIX 暴露 Agent 的路径片段，例如 /a2a/invoice-processor。它必须唯一且不能包含 /。

❷ url 是 AISIX 转发 A2A JSON-RPC 请求的上游 Agent 端点。

❸ protocol_version: "0.3" 将该 Agent 配置为接收 A2A 0.3 请求体。AISIX 不会在 A2A 版本之间转换。

❹ auth_type: "none" 表示上游 Agent 不要求 AISIX 发送凭证。

如果后续需要更新、查看或删除该 Agent，请保存返回的 id。

上游凭证选项请参见上游认证。完整请求和响应结构请参见 Admin API 参考中的 Create A2A Agent。

授予 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" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }
EOF

❶ 当该 Key 仅用于 A2A 流量时，请使用空的模型允许列表。

❷ ["invoice-processor"] 会授予该 Key 访问一个 Agent 的权限；使用 ["*"] 可以授权访问所有 Agent。完整匹配规则请参见控制 Agent 访问。

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

验证通过 AISIX 的 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"
      }
    }
  }'

❶ message/send 会向上游 Agent 发送消息。

❷ 消息结构遵循注册 Agent时配置的 A2A 0.3 版本。

成功请求会原样返回上游 Agent 的 JSON-RPC 响应。

对于通过 Agent 查找和访问检查的调用，AISIX 会应用限流和预算、将请求转发到上游 Agent，并记录用量事件。A2A 调用不计量模型 Token，因此 Token 和成本字段为零。

同一端点也接受 message/stream、tasks/get、tasks/cancel、tasks/resubscribe 以及推送通知配置方法。每个方法都使用相同的调用方认证、Agent 访问检查、流量控制、请求转发和用量事件记录流程。

如果请求在 AISIX 联系上游 Agent 前被拒绝，请检查状态码：

  • 401：调用方 API Key 缺失或无效。
  • 403：调用方 API Key 有效，但其 allowed_agents 不包含该 Agent。
  • 404：该 Agent 未知或已禁用。

如果 AISIX 无法访问上游 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 会从上游源站的 well-known 路径获取 card：

https://<upstream-host>/.well-known/agent-card.json

返回 card 前，AISIX 会根据请求的 Host 头把服务 url 重写为网关路径，让客户端的后续调用继续经过 AISIX。其它 card 字段（包括 skills、capabilities、version、security schemes 和其它公布的端点）保持不变。

当前行为与限制​

Agent 网关仍在持续开发。以下限制会影响当前可依赖的 Agent 端点和控制能力：

  • 协议绑定。 AISIX 通过 /a2a/<agent> 提供 A2A JSON-RPC 调用。REST/HTTP binding 中基于路径的方法，例如 POST .../v1/message:send 或 GET .../v1/tasks/{id}，目前不会被单独路由。
  • 上游认证 不支持 OAuth 2.0。请使用上游认证中的 none、bearer 或 api_key 模式。
  • 安全护栏 尚不会扫描 A2A 消息内容。当前已支持访问控制、限流、预算和用量统计；面向 A2A 的内容治理仍在规划中。与此同时，安全护栏可检查模型流量和 MCP 流量。
  • 流式响应。 message/stream 响应会被缓冲后作为一个完整响应返回，而不是逐块流式返回。
  • 托管平台 Agent 暂不能作为注册选项，例如托管在 Amazon Bedrock AgentCore、Azure AI Foundry 或 Vertex AI Agent Engine 等云端 Agent Runtime 中的 Agent。请使用 A2A HTTP URL 注册 Agent。

下一步​

你现在已经了解如何注册 A2A Agent、授予调用方访问权限、通过 AISIX 调用 Agent，以及发现其 Agent Card。请使用以下指南进一步完善 A2A 流量的处理方式：