# A2A Streaming and Agent-Card Discovery

The [Agent Gateway setup](https://docs.api7.ai/ai-gateway/agent-gateway/setup.md) uses the official A2A Go SDK client to send a non-streaming message through AISIX. This guide extends that verified path by consuming a streaming task and resolving the agent card that AISIX rewrites for clients.

Both tests exercise client behavior beyond a direct JSON-RPC request. The SDK interprets each streamed task event and, during discovery, selects the gateway service URL from the returned card without learning the upstream agent URL or credential.

The streaming test works with the local quickstart network. End-to-end agent-card resolution requires a client-reachable gateway origin; this guide uses a public HTTPS origin. If that origin is not configured yet, complete the streaming test and return to the discovery section after deployment.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before starting, complete [Set Up Agent Gateway](https://docs.api7.ai/ai-gateway/agent-gateway/setup.md) and keep these resources available:

* The AISIX gateway, `aisix-a2a-echo` container, and `aisix-a2a` Docker network.
* The `AISIX_GATEWAY_CONTAINER`, `AISIX_A2A_URL`, and `AISIX_A2A_KEY` environment variables.
* The `echo-agent` registration and caller grant.

The setup downloads and compiles the pinned SDK release in the echo-agent container. The client commands reuse the same release and container build cache.

## Verify Streaming[​](#verify-streaming "Direct link to Verify Streaming")

The setup guide retains `AISIX_A2A_URL`, which addresses the gateway from the client container. Send a streaming message through that endpoint:

```
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
```

The client prints events as they arrive. The echo agent produces this sequence:

1. A submitted task.
2. A working status update.
3. An artifact update containing `Stream through AISIX`.
4. A completed status update.

This verifies that AISIX relays the A2A event stream instead of buffering it into one response.

## Verify Agent-Card Discovery[​](#verify-agent-card-discovery "Direct link to Verify Agent-Card Discovery")

The echo server started by the setup guide publishes a dual A2A 0.3 and 1.0 compatibility card. AISIX serves its client-facing form at:

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

AISIX derives the advertised authority from `Host` and the scheme from `X-Forwarded-Proto`, defaulting to `https` when the forwarded protocol is absent. AISIX reads the first value of a comma-separated list, in any case, and ignores anything other than `http` or `https`, which also gives `https`. A gateway reached directly over plain HTTP therefore advertises `https` unless the caller sends `X-Forwarded-Proto: http`. When a trusted reverse proxy terminates TLS, configure it to supply the gateway's public values. The returned top-level `url` and every entry in `supportedInterfaces` should point back to the client-reachable AISIX `/a2a/echo-agent` endpoint.

Once the gateway has a client-reachable public origin, run discovery with the complete card 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
```

Provide the complete nested card URL. The A2A Go SDK treats a URL with a non-root path as the complete card URL, so passing only the agent service URL sends discovery to `/a2a/echo-agent` and returns `405`. Passing only the gateway origin makes the SDK request `/.well-known/agent-card.json`, which returns `404` because AISIX exposes the card under the registered agent's path.

To exercise card resolution and the resulting service URL together, pass the same card URL to `send` and omit `--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
```

The client fetches the card through AISIX, selects its JSON-RPC 1.0 interface, and sends the message to the rewritten gateway URL. It never receives the upstream agent URL or credential.

## Troubleshoot Streaming and Discovery[​](#troubleshoot-streaming-and-discovery "Direct link to Troubleshoot Streaming and Discovery")

| Symptom                                                                           | Check                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The direct client returns `401`                                                   | Confirm `--auth` contains `Bearer` followed by the AISIX caller API key.                                                                                                                                                                                                                                                                                                 |
| The direct client returns `403`                                                   | Confirm the caller key's `allowed_agents` grant includes `echo-agent`.                                                                                                                                                                                                                                                                                                   |
| Discovery returns `404` or `405`                                                  | Pass the complete `/a2a/echo-agent/.well-known/agent-card.json` URL. An origin-only URL resolves to the unavailable origin-level card path and returns `404`; the agent service URL is fetched as though it were the card and returns `405`.                                                                                                                             |
| The card advertises the wrong URL, or the client bypasses AISIX or cannot connect | Inspect the top-level `url` and `supportedInterfaces[].url`; each should use the client-reachable AISIX origin and `/a2a/echo-agent` path. If a trusted reverse proxy terminates TLS, configure it to set the public `Host` and `X-Forwarded-Proto` values. AISIX defaults the scheme to `https` when the forwarded protocol is absent or is neither `http` nor `https`. |
| Streaming fails after a non-streaming message succeeds                            | Confirm the upstream card advertises streaming and inspect the gateway and upstream agent logs for the `SendStreamingMessage` request.                                                                                                                                                                                                                                   |

## Next Steps[​](#next-steps "Direct link to Next Steps")

* [Control Agent Access](https://docs.api7.ai/ai-gateway/agent-gateway/agent-access-control.md): grant exact agent names, name patterns, or every registered agent.
* [Upstream Authentication](https://docs.api7.ai/ai-gateway/agent-gateway/upstream-authentication.md): keep upstream bearer tokens and API keys in AISIX.
* [Observability](https://docs.api7.ai/ai-gateway/agent-gateway/observability.md): inspect A2A requests, task outcomes, and stream failures.
