Agent 网关概述
AISIX 在 /a2a/<agent> 上公开已注册的 Agent-to-Agent（A2A）Agent，为 A2A 客户端和其他 Agent 提供一条需要身份认证的统一访问路径。调用方提供 AISIX 调用方 API Key；网关会检查该 API Key 是否可以访问目标，并在不暴露上游凭证的情况下转发 A2A JSON-RPC 请求。
因此，Agent 流量与模型和 MCP 流量使用相同的身份认证、访问控制、流量控制和遥测边界。同一个调用方 API Key 可以管理调用方能够使用的模型、MCP 工具和 A2A Agent。
每个 A2A Agent 资源代表一个通过 HTTP 使用 JSON-RPC 2.0 A2A 协议的上游 Agent。
Agent 网关的工作原理
每个上游 Agent 都有一个 name。AISIX 会在代理监听器的 /a2a/<name> 上 公开该 Agent。在 AISIX Cloud 中，Agent 在组织级注册，并公开给所选环境。在开源 AISIX 网关中，Agent 通常在 resources.yaml 中声明。
AISIX 会原样转发请求正文。每个 Agent 资源固定使用 A2A 1.0 或 0.3，调用方必须采用为该 Agent 配置的格式。AISIX 不会在协议版本之间转换。
当 Agent 调用通过身份认证和访问检查后，网关会应用请求和并发限制、使用已配置的上游凭证联系 Agent，并记录 A2A 用量遥测。AISIX Cloud 还可以应用涵盖调用方 API Key 的预算。
开始使用
按照配置 Agent 网关运行 A2A Echo Agent，通过 AISIX Cloud 或 resources.yaml 注册该 Agent，并授予调用方访问权限。随后使用官方 A2A Go SDK 客户端，通过网关发送 A2A 1.0 消息。继续阅读 A2A 流式传输与 Agent Card 发现，接收流式任务事件。网关具备公共源地址后，还可以按照同一指南验证面向客户端的 Agent Card 解析。两种管理方式配置的是相同的网关运行时和 A2A 端点。
客户端连接
A2A 客户端通过 AISIX 代理监听器调用已注册的 Agent：
| 设置 | 值 |
|---|---|
| Agent URL | <gateway-origin>/a2a/<agent-name> |
| Agent Card URL | <gateway-origin>/a2a/<agent-name>/.well-known/agent-card.json |
| 协议 | 通过 HTTP 使用 JSON-RPC 2.0 的 A2A 1.0 或 0.3 |
| 请求头 | Authorization: Bearer <caller-api-key> |
调用方 API Key 控制客户端可以访问哪些 Agent。客户端只连接 AISIX，不会收到上游凭证。
该端点接受 Agent 所配置 A2A 版本定义的 JSON-RPC 方法，包括消息、任务、流式传输和推送通知配置方法。流式方法返回 text/event-stream，AISIX 会在上游 Agent 发出事件时逐个中继。
Agent Card
客户端可以通过 AISIX 请求已注册 Agent 的发现文档：
GET /a2a/<agent-name>/.well-known/agent-card.json
该请求使用与 A2A 调用相同的调用方身份认证和 Agent 访问检查。AISIX 使用 Agent 已配置的上游凭证获取上游 Card，然后将其中公布的所有服务 URL 重写为网关路径。其他 Card 字段保持不变。
AISIX 从 X-Forwarded-Proto 获取公布的协议，从 Host 获取主机与端口。请配置信任的反向代理，将这些请求头设置为网关的公共地址。如果没有 X-Forwarded-Proto，AISIX 使用 https。
上游 Card 当前必须包含 A2A 0.3 使用的顶级 url 字段。对于 A2A 1.0 Agent，请发布同时包含 url 和 supportedInterfaces 的兼容 Card。AISIX 会重写 Card 中的每个服务 URL。
AISIX 首先检查注册路径下的 agent-card.json，然后检查其源地址下的同名文件。如果两个位置均未返回可用 Card，AISIX 会对较早的 agent.json 文件名重复上述检查。
治理 A2A 调用
A2A 调用与模型请求使用相同的调用方 API Key 边界，无需为 Agent 流量配置单独的策略栈。
可以使用以下指南优化 A2A 路径：
- 上游身份认证：配置 AISIX 如何向上游 Agent 进行身份认证。
- 控制 Agent 访问权限：将每个调用方 API Key 的权限范围限定为精确的 Agent 名称、名称模式或所有 Agent。
- 限流和预算：应用调用方请求和并发限制，并使用 AISIX Cloud 预算。
- 安全护栏行为：在输入检查位置扫描 A2A 消息文本。环境、调用方 API Key 和团队挂载可以覆盖 A2A 调用；模型和 MCP 服务器挂载不能覆盖。
- 可观测性：查看 A2A 调用生成的用量事件和指标。
当前限制
以下限制会影响 AISIX 公开的 Agent 接口和控制能力：
- AISIX 通过
/a2a/<agent>提供 A2A JSON-RPC 调用，不公开基于 A2A REST 路径的端点，例如POST .../v1/message:send或GET .../v1/tasks/{id}。 - 不支持 OAuth 2.0 上游身份认证。请按照上游身份认证中的说明使用
none、bearer或api_key。 - 输入安全护栏会在转发前扫描 A2A 请求中的消息文本，适用环境、调用方 API Key 和团队作用域；挂载到模型或 MCP 服务器作用域的安全护栏不适用于 A2A。目前尚未接入针对 Agent 响应的输出安全护栏检查。访问控制、请求和并发限制、AISIX Cloud 预算以及用量遥测仍然适用。
- 请使用 A2A HTTP URL 注册 Agent。目前不支持直接注册 Amazon Bedrock AgentCore、Azure AI Foundry 或 Vertex AI Agent Engine 等云 Agent 运行时资源。
排查 Agent 调用问题
如果调用方无法访问 Agent，请检查以下项目：
- A2A Agent 资源已启用，并且网关可以访问该资源。
- 在 AISIX Cloud 中，
allowed_environments包含调用方 API Key 所属环境。 - 调用方 API Key 的
allowed_agents授权涵盖已注册的 Agent 名称。 - 请求正文和方法使用该 Agent 配置的 A2A 协议版本。
- 已配置的上游身份认证与 Agent 的要求相符。
缺少调用方 API Key 或 API Key 无效时返回 401。已知但不在 API Key 授权范围内的 Agent 返回 403，未知或已禁用的 Agent 返回 404。对于 JSON-RPC 调用，上游不可访问或上游 HTTP 状态不成功时，会返回 502 及 JSON-RPC 错误信封；AISIX 不会公开上游响应正文。Agent Card 获取失败时也会返回 502，但使用普通 HTTP 错误，而不是 JSON-RPC 信封。