a2a-streaming

A2A Streaming (SSE)

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for the streaming section
2. Web-search site:github.com a2aproject A2A streaming SSE message/stream for streaming protocol details
3. Web-search site:github.com a2aproject a2a-samples streaming for streaming implementation examples
4. Fetch SDK docs for streaming server/client classes and event types

Conceptual Architecture

What A2A Streaming Is

A2A streaming uses Server-Sent Events (SSE) to deliver real-time task updates from server to client. Instead of waiting for the entire task to complete (message/send), the client receives incremental updates as the agent works (message/stream).

When to Use Streaming

• Long-running tasks — Keep the client informed of progress
• Incremental results — Deliver partial artifacts as they're generated
• Interactive UX — Show real-time agent activity to end users
• Token streaming — Stream LLM output tokens as they're generated

How It Works

1. Client sends message/stream (same payload as message/send)
2. Server responds with Content-Type: text/event-stream
3. Server sends SSE events as the task progresses
4. Final event contains a terminal task state
5. Connection closes after the terminal event

SSE Event Types

Event Type	Purpose	When Sent
TaskStatusUpdateEvent	Task state changed	On every state transition
TaskArtifactUpdateEvent	New artifact data	When agent produces output

Event Format

SSE events follow the standard format:

event: <event-type>
data: <JSON payload>

Each event's data field contains a JSON object with:

• taskId — Which task this event belongs to
• type — Event type discriminator
• Type-specific fields (status update, artifact data, message content)

Re-subscription

If the SSE connection drops, the client can re-subscribe:

• Call tasks/resubscribe with the taskId
• Server resumes sending events from the current state
• Events that were sent before the reconnection are NOT replayed (unless the server implements replay)

Server-Side Implementation

The server must:

1. Declare streaming: true in the Agent Card capabilities
2. Handle message/stream method
3. Keep the HTTP connection open
4. Send SSE events as the agent processes
5. Send a final event with a terminal state
6. Close the connection cleanly

Client-Side Implementation

The client must:

1. Check Agent Card for streaming capability
2. Send message/stream instead of message/send
3. Parse SSE events (use an SSE client library)
4. Handle each event type appropriately
5. Handle connection drops and re-subscribe if needed

Backpressure and Buffering

• Servers should buffer events if the client can't consume fast enough
• Set reasonable connection timeouts
• Send periodic keepalive comments (:keepalive\n\n) to prevent proxy timeouts
• Clients should process events asynchronously to avoid blocking the stream

Best Practices

• Always send a terminal event before closing the stream
• Include the full task status in TaskStatusUpdateEvent (not just the state name)
• Use TaskArtifactUpdateEvent for incremental delivery of large results
• Implement heartbeat/keepalive to prevent connection timeouts
• Handle client disconnection gracefully on the server side
• Test with slow clients to verify backpressure handling
• Set appropriate timeouts on both client and server

Fetch the specification for exact SSE event schemas, event naming conventions, and re-subscription protocol before implementing.