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-a2aDocker 网络。 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 依次生成以下事件：
- 已提交的任务。
- 正在处理的状态更新。
- 包含
Stream through AISIX的产物更新。 - 已完成的状态更新。
这验证了 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 请求、任务结果和流式传输故障。