# A2A 流式传输与 Agent Card 发现

[Agent 网关设置指南](https://docs.apiseven.com/ai-gateway/agent-gateway/setup.md)使用官方 A2A Go SDK 客户端，通过 AISIX 发送非流式消息。本指南在已验证的路径上继续接收流式任务，并解析 AISIX 为客户端重写的 Agent Card。

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

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

[]()

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始之前，请完成[设置 Agent 网关](https://docs.apiseven.com/ai-gateway/agent-gateway/setup.md)，并保留以下资源：

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

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

[]()

## 验证流式传输[​](#verify-streaming "验证流式传输的直接链接")

设置指南保留了 `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 发现[​](#verify-agent-card-discovery "验证 Agent Card 发现的直接链接")

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

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

AISIX 从 `Host` 确定公布的主机和端口，从 `X-Forwarded-Proto` 确定 URL 协议；未提供转发协议时，默认使用 `https`。AISIX 读取逗号分隔列表的第一个值，不区分大小写，并忽略 `http` 和 `https` 以外的值，此时同样使用 `https`。因此，通过纯 HTTP 直接访问的网关会公布 `https`，除非调用方发送 `X-Forwarded-Proto: http`。如果由可信反向代理终止 TLS，请配置该代理，使其提供网关公开的 `Host` 和 `X-Forwarded-Proto` 值。返回的顶层 `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 或凭证。

[]()

## 流式传输与发现故障排查[​](#troubleshoot-streaming-and-discovery "流式传输与发现故障排查的直接链接")

| 现象                                                     | 检查项                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 直接调用时收到 `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` 值。未提供转发协议，或其值既不是 `http` 也不是 `https` 时，AISIX 默认使用 `https`。 |
| 非流式消息成功，但流式传输失败                           | 确认上游卡片声明支持流式传输，并在网关和上游 Agent 日志中检查 `SendStreamingMessage` 请求。                                                                                                                                                                               |

[]()

## 下一步[​](#next-steps "下一步的直接链接")

* [控制 Agent 访问](https://docs.apiseven.com/ai-gateway/agent-gateway/agent-access-control.md)：授权具体 Agent 名称、名称模式或所有已注册 Agent。
* [上游身份认证](https://docs.apiseven.com/ai-gateway/agent-gateway/upstream-authentication.md)：在 AISIX 中保存上游 Bearer Token 和 API Key。
* [可观测性](https://docs.apiseven.com/ai-gateway/agent-gateway/observability.md)：检查 A2A 请求、任务结果和流式传输故障。
