A2A 流式传输与 Agent Card 发现

Agent 网关设置指南使用官方 A2A Go SDK 客户端，通过 AISIX 发送非流式消息。本指南在已验证的路径上继续接收流式任务，并解析 AISIX 为客户端重写的 Agent Card。

这两项测试验证直接 JSON-RPC 请求之外的客户端行为。SDK 解释每个流式任务事件，并在发现过程中从返回的卡片中选择网关服务 URL，无需获知上游 Agent 的 URL 或凭证。

流式传输测试可在本地快速入门网络中运行。端到端的 Agent Card 解析需要客户端可访问的网关源地址；本指南使用公共 HTTPS 源地址。如果尚未配置该地址，请先完成流式传输测试，待部署后再返回发现部分。

前置条件

开始之前，请完成设置 Agent 网关，并保留以下资源：

• AISIX 网关、aisix-a2a-echo 容器和 aisix-a2a Docker 网络。
• AISIX_GATEWAY_CONTAINER、AISIX_A2A_URL 和 AISIX_A2A_KEY 环境变量。
• echo-agent 注册信息和调用方授权。

设置过程会在 echo-agent 容器中下载并编译固定的 SDK 版本。客户端命令复用同一个版本及容器构建缓存。

验证流式传输

设置指南保留了 AISIX_A2A_URL，客户端容器通过该地址访问网关。通过此端点发送流式消息：

docker exec aisix-a2a-echo \
  go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
  send "$AISIX_A2A_URL" "Stream through AISIX" \
  --transport jsonrpc \
  --stream \
  --auth "Bearer $AISIX_A2A_KEY" \
  --output json

客户端在事件到达时逐个输出。echo Agent 依次生成以下事件：

1. 已提交的任务。
2. 正在处理的状态更新。
3. 包含 Stream through AISIX 的产物更新。
4. 已完成的状态更新。

这验证了 AISIX 会中继 A2A 事件流，而非将其缓冲为一个响应。

验证 Agent Card 发现

设置指南启动的 echo 服务器会发布同时兼容 A2A 0.3 和 1.0 的卡片。AISIX 在以下路径提供面向客户端的版本：

<gateway-origin>/a2a/echo-agent/.well-known/agent-card.json

AISIX 从 Host 获取公布的主机信息，从 X-Forwarded-Proto 获取协议；未提供转发协议时，默认使用 https。如果由可信反向代理终止 TLS，请配置该代理，使其提供网关的公共值。返回的顶层 url 和 supportedInterfaces 中的每个条目都应指回客户端可访问的 AISIX /a2a/echo-agent 端点。

网关具备客户端可访问的公共源地址后，使用完整的卡片 URL 运行发现：

export AISIX_A2A_CARD_URL="https://gateway.example.com/a2a/echo-agent/.well-known/agent-card.json"

docker exec aisix-a2a-echo \
  go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
  discover "$AISIX_A2A_CARD_URL" \
  --auth "Bearer $AISIX_A2A_KEY" \
  --output json

请提供完整的嵌套卡片 URL。A2A Go SDK 会将带有非根路径的 URL 视为完整卡片 URL，因此仅传入 Agent 服务 URL 会将发现请求发送到 /a2a/echo-agent，并返回 405。仅传入网关源地址会让 SDK 请求 /.well-known/agent-card.json，由于 AISIX 在已注册 Agent 的路径下提供卡片，此请求会返回 404。

要一起验证卡片解析及由此得到的服务 URL，请将相同卡片 URL 传给 send，并省略 --transport：

docker exec aisix-a2a-echo \
  go run github.com/a2aproject/a2a-go/v2/cmd/a2a@v2.5.0 \
  send "$AISIX_A2A_CARD_URL" "Discover and call through AISIX" \
  --auth "Bearer $AISIX_A2A_KEY" \
  --output json

客户端通过 AISIX 获取卡片，选择其 JSON-RPC 1.0 接口，并将消息发送到重写后的网关 URL。客户端不会收到上游 Agent 的 URL 或凭证。

流式传输与发现故障排查

现象	检查项
直接调用的客户端返回 401	确认 --auth 包含 Bearer，其后为 AISIX 调用方 API Key。
直接调用的客户端返回 403	确认调用方密钥的 allowed_agents 授权包含 echo-agent。
发现请求返回 404 或 405	传入完整的 /a2a/echo-agent/.well-known/agent-card.json URL。仅包含源地址的 URL 会解析到不存在的源地址级卡片路径并返回 404；Agent 服务 URL 则会被当作卡片获取，并返回 405。
卡片公布了错误的 URL，或客户端绕过 AISIX、无法连接	检查顶层 url 和 supportedInterfaces[].url；它们均应使用客户端可访问的 AISIX 源地址及 /a2a/echo-agent 路径。如果由可信反向代理终止 TLS，请配置公共 Host 和 X-Forwarded-Proto 值。未提供转发协议时，AISIX 默认使用 https。
非流式消息成功，但流式传输失败	确认上游卡片声明支持流式传输，并在网关和上游 Agent 日志中检查 SendStreamingMessage 请求。

下一步

• 控制 Agent 访问：授权具体 Agent 名称、名称模式或所有已注册 Agent。
• 上游身份认证：在 AISIX 中保存上游 Bearer Token 和 API Key。
• 可观测性：检查 A2A 请求、任务结果和流式传输故障。