message/stream

Send streaming messages to A2A agents and receive real-time responses via Server-Sent Events

Overview

The message/stream method enables real-time communication with A2A agents using Server-Sent Events (SSE). This allows you to receive partial responses as the agent processes your request, providing a more interactive experience.

Streaming Communication: This method uses Server-Sent Events for real-time response streaming. The connection remains open until the agent completes the response.

Request

Headers

Content-Type · string · required

Must be application/json

Accept · string · required

Must be text/event-stream for SSE support

x-api-key · string · required

Your API key for authentication

Cache-Control · string

Recommended: no-cache for real-time streaming

Path Parameters

agent_id · string · required

Unique identifier of the target agent

Body Parameters

jsonrpc · string · required

JSON-RPC version, must be "2.0"

id · string · required

Unique identifier for this request (for response correlation)

method · string · required

Must be "message/stream"

params · object · required

Message parameters object (same structure as message/send)

Show params properties

params.message · object · required

The message to send to the agent

Show message properties

params.message.role · string · required

Message role, must be "user"

params.message.messageId · string · required

UUID v4 identifier for this message

params.message.parts · array · required

Array of message parts (text, files, etc.)

params.contextId · string

Context ID for multi-turn conversations

params.sessionId · string

Optional session identifier

Response

Server-Sent Events Stream

The response is delivered as a stream of Server-Sent Events. Each event contains a JSON object with the current state of the task.

Event Format

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","result":{"id":"task-123","status":{"state":"working"},"final":false},"id":"req-001"}

data: {"jsonrpc":"2.0","result":{"id":"task-123","status":{"state":"completed","message":{"role":"agent","parts":[{"type":"text","text":"Response content"}]}},"final":true},"id":"req-001"}

Event Data Structure

jsonrpc · string

JSON-RPC version, always "2.0"

result · object

Result object containing the current task state

Show result properties

result.id · string

Task ID for this streaming operation

result.status · object

Current status information

Show status properties

result.status.state · string

Current task state: "submitted", "working", "completed", "failed", or "canceled"

result.status.message · object

Agent’s response message (present when state is “completed”)

Show message properties

result.status.message.role · string

Message role, always "agent"

result.status.message.parts · array

Array of response parts

result.status.progress · object

Progress information (optional, during “working” state)

Show progress properties

result.status.progress.current · number

Current progress value

result.status.progress.total · number

Total progress value

result.status.progress.message · string

Progress description

result.contextId · string

Context ID for multi-turn conversations

result.final · boolean

Whether this is the final event (true when task is completed/failed/canceled)

id · string

Request ID (matches the request ID)

Examples

cURL

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: your-api-key" \
  -N \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-stream-001",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "Generate a detailed report about AI trends"
          }
        ],
        "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
      }
    }
  }'

SSE Stream Example

data: {"jsonrpc":"2.0","result":{"id":"task-789","status":{"state":"submitted"},"final":false},"id":"req-stream-001"}

data: {"jsonrpc":"2.0","result":{"id":"task-789","status":{"state":"working","progress":{"current":1,"total":5,"message":"Analyzing AI trends data"}},"final":false},"id":"req-stream-001"}

data: {"jsonrpc":"2.0","result":{"id":"task-789","status":{"state":"working","progress":{"current":3,"total":5,"message":"Generating report sections"}},"final":false},"id":"req-stream-001"}

data: {"jsonrpc":"2.0","result":{"id":"task-789","status":{"state":"completed","message":{"role":"agent","parts":[{"type":"text","text":"# AI Trends Report 2024\n\n## Executive Summary\nThe AI landscape continues to evolve rapidly with significant developments in...\n\n## Key Trends\n1. Large Language Models advancement\n2. Multimodal AI integration\n3. Edge AI deployment\n\n## Conclusion\nThese trends indicate a shift towards more accessible and integrated AI solutions."}]}},"contextId":"ctx-abc123","final":true},"id":"req-stream-001"}

Stream Lifecycle

1. Stream Initiation

State: submitted

The request has been received and queued for processing.

{
  "result": {
    "id": "task-789",
    "status": {"state": "submitted"},
    "final": false
  }
}

2. Processing Updates

State: working

The agent is actively processing the request. May include progress updates.

{
  "result": {
    "id": "task-789",
    "status": {
      "state": "working",
      "progress": {
        "current": 3,
        "total": 5,
        "message": "Generating content"
      }
    },
    "final": false
  }
}

3. Completion

State: completed

The agent has finished processing and provides the final response.

{
  "result": {
    "id": "task-789",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{"type": "text", "text": "Final response"}]
      }
    },
    "contextId": "ctx-abc123",
    "final": true
  }
}

Error Handling

Stream Errors

Errors during streaming are sent as regular JSON-RPC error responses:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Agent processing failed",
    "data": {
      "taskId": "task-789",
      "details": "Timeout exceeded"
    }
  },
  "id": "req-stream-001"
}

Connection Management

Connection Handling

• Keep-Alive: Server maintains connection until completion
• Heartbeat: Server may send ping events to keep connection alive
• Timeout: Connections timeout after 5 minutes of inactivity
• Reconnection: Clients should implement reconnection logic

Error Recovery

• Network Issues: Implement exponential backoff for reconnection
• Partial Responses: Store received data before reconnecting
• Task Continuation: Use task ID to check status after reconnection

Best Practices

Performance

• Buffer Management: Process events as they arrive, don’t buffer unnecessarily
• Connection Pooling: Reuse connections when possible
• Timeout Handling: Set appropriate timeouts for long-running tasks

Reliability

• Event Parsing: Always validate JSON before parsing
• Final Flag: Check final flag to know when stream is complete
• Error Handling: Implement proper error handling for network issues

User Experience

• Progress Indicators: Use progress information to show user feedback
• Partial Results: Display partial content as it arrives
• Cancellation: Provide ability to cancel long-running streams

Comparison with message/send

Feature	message/send	message/stream
Response Type	Single response	Multiple events
Real-time Updates	No	Yes
Progress Tracking	No	Yes
Connection	Request/Response	Persistent
Use Case	Quick queries	Long-running tasks
Complexity	Simple	Moderate