Skip to main content
API7.ai Logo

A2A Streaming and Agent-Card Discovery

The Agent Gateway setup 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​

Before starting, complete Set Up Agent Gateway 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​

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​

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. 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​

SymptomCheck
The direct client returns 401Confirm --auth contains Bearer followed by the AISIX caller API key.
The direct client returns 403Confirm the caller key's allowed_agents grant includes echo-agent.
Discovery returns 404 or 405Pass 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 connectInspect 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.
Streaming fails after a non-streaming message succeedsConfirm the upstream card advertises streaming and inspect the gateway and upstream agent logs for the SendStreamingMessage request.

Next Steps​