Stream Message Workflow

Runtime contract

The generated OpenAPI operation omits the JSON request body. Send the body shown here; an empty body is not a valid request. The generated response example also does not fully reflect the current A2A envelope.

Start the example A2A server and set the same OS_SECURITY_KEY in the client terminal. These examples target reference-workflow on port 7777. On deployments using scoped bearer authorization, this operation requires workflows:run (or a matching broader grant). The authenticated principal determines user identity; X-User-ID is only anonymous attribution and cannot override it.

The outer id correlates the request and response. messageId identifies the submitted message. contextId becomes the Agno session ID; omit it to let the server create a session, or reuse a session owned by the same principal and component.

Request

curl --no-buffer -X POST "http://localhost:7777/a2a/workflows/reference-workflow/v1/message:stream" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "messageId": "message-1",
      "contextId": "workflow-session",
      "parts": [
        {
          "kind": "text",
          "text": "Hello"
        }
      ]
    }
  }
}'

Stream response

The response is text/event-stream (SSE), despite the generated NDJSON description. Parse blank-line-delimited SSE frames, then JSON-decode each data: payload. Event names include TaskStatusUpdateEvent, Message, and a final Task; these are A2A events, not raw Agno run events. A shortened status frame is:

event: TaskStatusUpdateEvent
data: {"jsonrpc":"2.0","id":"request-1","result":{"kind":"status-update","taskId":"returned-run-id","contextId":"workflow-session","status":{"state":"working"},"final":false}}

Read result.status.state on status/task payloads. The final Task carries result.id, result.contextId, and the accumulated answer in result.history[*].parts, with media optionally in result.artifacts. Do not print both message deltas and the repeated final answer.

The current A2A stream mapper can emit a final completed task after an Agno error or human-review pause event when the underlying iterator then ends normally. A terminal A2A completed value alone is therefore insufficient for reliable pause/error handling. Use native AgentOS run APIs for HITL and definitive run lifecycle handling.

POST/a2a/workflows/{id}/v1/message:stream

Stream a message to an Agno Workflow (streaming). The Workflow is identified via the path parameter '{id}'. Optional: Pass user ID via X-User-ID header (recommended) or 'userId' in params.message.metadata. Returns real-time updates as newline-delimited JSON (NDJSON).

Path Parameters

id*Id

Response Body

application/json

curl --request POST 'https://example.com/a2a/workflows/string/v1/message:stream'
null