Agent 网关概览

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

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

A2A Agent 是一个网关注册项，代表一个通过 HTTP 和 JSON-RPC 2.0 提供 A2A 协议的上游 Agent。本页介绍 Agent 网关，并演示如何通过连接到 AISIX Cloud 的网关注册和调用 Agent。

Agent 网关如何工作

每个上游 Agent 都以组织内唯一的 name 注册。AISIX 会在代理监听器上通过 /a2a/<name> 暴露该 Agent，并把每个 JSON-RPC 请求体原样转发给上游 Agent。

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

注册并调用 Agent

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

前提条件

下面的示例通过 AISIX Cloud Admin API 管理网关。运行示例前，请先准备以下内容：

AISIX Cloud 访问权限、一个环境、一个已挂载的网关，以及具有写权限的 Admin Token。对于本地部署，请先完成 AISIX Cloud 快速入门；如需申请混合云访问权限，请联系 API7。
一个通过 HTTP 提供 A2A 协议的上游 Agent 及其 URL。

同一工作流适用于 AISIX Cloud 的两种控制面部署方式：本地部署和混合云，仅控制面 URL 不同。

导出连接信息：

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

注册 A2A Agent

下面的示例注册一个使用 A2A 0.3 传输格式且不需要凭证的上游 Agent。A2A Agent 是组织级资源：只需创建一次，并将其开放给需要提供该 Agent 服务的环境：

curl -sS -X POST "${AISIX_CP}/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

❶ name 会成为 AISIX 暴露 Agent 的路径片段，例如 /a2a/invoice-processor。它必须在组织内唯一，可以包含字母、数字、_、. 和 -，但不能以分隔符开头或结尾。

❷ url 是 AISIX 转发 A2A JSON-RPC 请求的上游 Agent 端点。AISIX 也会相对于该 URL 发现 Agent Card，因此发布在路径前缀下的 Agent 无需额外配置即可注册。参见发现 Agent Card。

❸ protocol_version: "0.3" 是该 Agent 所使用的 A2A 线格式版本。AISIX 会在每个请求（包括获取 Agent Card 的请求）的 A2A-Version 头中向 Agent 声明该版本，并要求调用方以相同版本发送请求体。请将其设为上游 Agent 实际提供的版本：Agent 收到不支持的版本会拒绝该调用，而 AISIX 不会在 A2A 版本之间转换。

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

❺ allowed_environments 列出可以访问该 Agent 的环境。空列表表示不向任何环境开放。

你会看到类似响应：

{
  "a2a_agent": {
    "id": "1d95ac57-7f27-46a4-b5a3-55d3c3ad0a12",
    "org_id": "7b8f1c2e-0d4a-4f6b-9c3d-2e5a8b7c6d1f",
    "name": "invoice-processor",
    "url": "https://agents.example.com/invoice",
    "protocol_version": "0.3",
    "auth_type": "none",
    "enabled": true,
    "allowed_environments": ["9f2c4e6a-1b3d-4c5e-8a7f-0d2b4c6e8a1c"],
    "created_at": "2026-07-22T08:00:00Z",
    "updated_at": "2026-07-22T08:00:00Z"
  }
}

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

上游凭证选项请参见上游认证。

授予 Agent 访问权限

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

在环境中创建调用方 API Key，并指定它可以访问的 Agent。控制面会生成 Key，且只在创建响应中返回一次明文；请直接捕获该值：

export AISIX_API_KEY=$(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-demo-caller",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }' | jq -r '.plaintext')

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

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

plaintext 值只返回一次。创建响应还会返回包含 id 的 Key 资源；如需后续更新该调用方 API Key，请保存此 id。每次写入后，Agent 和 Key 都会自动投射到已挂载的网关。

验证通过 AISIX 的 Agent 调用

把 A2A JSON-RPC 请求发送到 Agent 的代理路径，并携带上面捕获的调用方 API Key。请求体必须使用该 Agent 所配置的 A2A 协议版本：

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，并记录用量事件。由于 Agent 不会上报自身用量，用量事件中的 Token 数由网关统计消息文本得出；cost_usd 保持为零，因为 Agent 如何收费不是网关能观测到的。参见可观测性。

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

流式获取长任务进度

message/stream 和 tasks/resubscribe 返回 text/event-stream 响应。上游 Agent 每产生一个事件，AISIX 就转发一个，因此调用方可以实时观察任务进展，而不必等待任务结束：

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

timeout_ms 约束的是建立流的过程，而不是流的时长：A2A 任务可能运行数分钟乃至数小时并持续上报进度，因此流一旦建立，AISIX 不会将其中断。调用方的流量控制配额会在流保持打开期间一直占用，用量事件则在流结束时记录——调用方中途断开连接的情况同样会记录。

如果 Agent 在流开始之后才失败，AISIX 已无法更改响应状态码，因此会把 JSON-RPC 错误信封作为最后一个事件转发。如果 Agent 对流式调用返回的是普通 JSON-RPC 响应而非流，AISIX 会将该响应作为单个事件转发。

如果请求在 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

Agent Card 是描述 Agent 能力和服务 URL 的 A2A 发现文档。客户端可以通过 AISIX 发现已注册 Agent，而无须直接联系上游 Agent：

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

AISIX 会先在注册的 url 自身路径下的 well-known 路径查找 card，再回落到其源站：

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

两种形态都真实存在。独占整个域名的 Agent 发布在源站，这也是 A2A 规范定义的位置；而按路径前缀区分租户的 Agent 平台，或部署在 ingress 路径之后的自建 Agent，则发布在自身路径下。AISIX 先尝试更具体的位置，再回落到源站，因此两种形态都无需额外配置即可注册。在每个位置上，都会在 agent-card.json 之后再尝试上一版规范的文件名 agent.json。

返回 card 前，AISIX 会根据请求的 Host 头，把 card 中公布的每一个服务 URL 重写为网关路径——包括顶层 url 以及 supportedInterfaces 和 additionalInterfaces 中的每一项。若只重写顶层，A2A 1.0 客户端会从 supportedInterfaces 中选取端点，从而直接调用上游 Agent，绕过访问控制、流量控制和用量记录。card 的其它字段（包括 skills、capabilities、version 和 security schemes）保持不变。

只有在能够从请求中确定自身对外地址时，AISIX 才会返回 card。若请求不携带可用的 host，AISIX 返回 HTTP 500，而不是返回一份仍然公布上游 Agent 地址的 card。

当前行为与限制

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 流量。
托管平台 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 流量的处理方式：

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

Agent 网关如何工作​

注册并调用 Agent​

前提条件​

注册 A2A Agent​

授予 Agent 访问权限​

验证通过 AISIX 的 Agent 调用​

流式获取长任务进度​

发现 Agent Card​

当前行为与限制​

下一步​