跳到主要内容

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 1.0 请求。两种管理方式配置的是相同的网关运行时和 A2A 端点。

客户端连接​

A2A 客户端通过 AISIX 代理监听器调用已注册的 Agent：

设置值
Agent URL<gateway-origin>/a2a/<agent-name>
协议通过 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 获取 Authority。请配置信任的反向代理，将这些请求头设置为网关的公共地址。如果没有 X-Forwarded-Proto，AISIX 使用 https。

上游 Card 当前必须包含 A2A 0.3 使用的顶级 url 字段。对于 A2A 1.0 Agent，请发布同时包含 url 和 supportedInterfaces 的兼容 Card。AISIX 会重写 Card 中的每个服务 URL。

AISIX 首先检查注册路径下的 agent-card.json，然后检查其 Origin 下的同名文件。如果两个位置均未返回可用 Card，AISIX 会对较早的 agent.json 文件名重复上述检查。

治理 A2A 调用​

A2A 调用与模型请求使用相同的调用方 API Key 边界，无需为 Agent 流量配置单独的策略栈。

可以使用以下指南优化 A2A 路径：

  • 上游身份认证：配置 AISIX 如何向上游 Agent 进行身份认证。
  • 控制 Agent 访问权限：将每个调用方 API Key 的权限范围限定为精确的 Agent 名称、名称模式或所有 Agent。
  • 限流和预算：应用调用方请求和并发限制，并使用 AISIX Cloud 预算。
  • 可观测性：查看 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 消息内容。访问控制、请求和并发限制、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 信封。

有关端点级行为，请参阅代理 API 参考。有关错误响应详情，请参阅请求头和错误代码。

后续步骤​

可以通过以下指南配置 A2A 流量的处理方式：