message/stream

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

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"

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)

string

Request ID (matches the request ID)

Examples

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"
      }
    }
  }'

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: submittedThe request has been received and queued for processing.

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

2. Processing Updates

State: workingThe 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: completedThe 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

API Documentation

A2A Protocol Endpoints

message/stream

Overview

Request

Headers

Path Parameters

Body Parameters

Response

Server-Sent Events Stream

Event Format

Event Data Structure

Examples

Stream Lifecycle

Error Handling

Stream Errors

Connection Management

Best Practices

Comparison with message/send

API Documentation

A2A Protocol Endpoints

​Overview

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Server-Sent Events Stream

​Event Format

​Event Data Structure

​Examples

​Stream Lifecycle

​Error Handling

​Stream Errors

​Connection Management

​Best Practices

​Comparison with message/send

Overview

Request

Headers

Path Parameters

Body Parameters

Response

Server-Sent Events Stream

Event Format

Event Data Structure

Examples

Stream Lifecycle

Error Handling

Stream Errors

Connection Management

Best Practices

Comparison with message/send