Skip to main content

​
SSE Overview

Server-Sent Events (SSE) provide a one-directional stream from server to client over a single HTTP connection. When you call a streaming endpoint (e.g. /api/agents/{id}/run/stream), the response is a text/event-stream with individual events sent as they occur. Each event is a JSON object prefixed with ‘data: ’ on a single line, separated by blank lines.

​
Agent Streaming Events

EventKey FieldsDescription
startrun_id, session_idAgent run has started — save session_id for multi-turn
step_startedstepAgent is beginning a new reasoning step
content_deltadeltaA per-token piece of the agent’s text response. Accumulated server-side into the persisted run; the platform forwards each delta as it arrives.
chunkcontentTerminal text event with the final assembled response — emitted at the end of a non-ReAct (sync-style) generation
tool_calltool_name, argumentsAgent is calling a tool with the given arguments
tool_resulttool_name, resultTool execution completed with this result
reasoning_deltadeltaPer-token piece of the model’s reasoning trace (only when reasoning_requested=true). Forwarded but NOT persisted — use reasoning for the persisted trace.
reasoningtextPersisted reasoning segment — the canonical “what the model thought” event for replay
reasoning_summarysummaryFinal summarised reasoning trace at the end of the step
step_completedstepAgent finished a reasoning step
approval_requestedtool_name, tool_inputTool call paused — waiting for approval via the approve endpoint
context_handler_createdcontext_handler_idA context handler was created mid-run (e.g. by a knowledge_search tool call). Lets you display the citation panel for the run.
completerun_id, content, usageAgent run finished
errormessageAn error occurred during execution

​
Keepalive

If no event has been emitted for 30 seconds, the stream sends : keepalive\n\n (an SSE comment line). Most SSE clients ignore comment lines automatically — if you’re rolling your own parser, drop any line that starts with :.

​
Persisted vs. forwarded-only

The platform distinguishes events that get written to the run record from events that are forwarded for UI ergonomics but not persisted:
  • Forwarded only: content_delta, reasoning_delta — these are per-token deltas; the assembled content / reasoning is persisted as one piece on complete.
  • Persisted + forwarded: everything else.
If you replay a run via GET /api/agents/runs/{run_id}, you’ll see the assembled content but not the individual deltas.

​
Consuming SSE in Python

import requests
import json

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "What can you help me with?"},
    stream=True,
)

for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        event = json.loads(text[6:])
        event_type = event["event"]

        if event_type == "start":
            print(f"Session: {event['session_id']}")
        elif event_type == "chunk":
            print(event["content"], end="", flush=True)
        elif event_type == "tool_call":
            print(f"\n[Calling {event['tool_name']}...]")
        elif event_type == "tool_result":
            print(f"[Tool returned result]")
        elif event_type == "error":
            print(f"\nError: {event['message']}")
        elif event_type == "complete":
            print("\nDone.")

​
Orchestration Events

Orchestration streaming extends the agent event model with delegation events. You see the coordinator reasoning, delegating to entity agents, each entity’s response, and the coordinator’s final synthesis. Events like delegation_start and entity_chunk let you show which agent is currently working.

​
Workflow Streaming

Workflow streaming sends per-block events as the engine traverses the DAG. The agent-block and orchestration-block streams interleave their own content_delta / reasoning_delta events directly into the workflow stream (so a downstream client can render the agent’s tokens live while still seeing block-level structure):
EventKey FieldsWhen
workflow_startexecution_idThe workflow execution has begun
block_startedblock_id, block_typeThe engine is about to execute a block
block_chunkblock_id, deltaA streaming block (agent / orchestration) produced output
content_delta / reasoning_deltablock_id, deltaForwarded from an agent/orchestration block inside the workflow — lets the UI render tokens live
block_outputblock_id, outputA block finished with this output, which downstream blocks may reference
block_completedblock_idA block has fully finished (including any post-processing)
block_errorblock_id, errorA block failed — by default, the workflow short-circuits unless the next block is in an error-handler position
workflow_completeexecution_id, resultThe whole execution finished
workflow_errorexecution_id, errorThe execution failed at the top level
The block-level events let you build a step indicator that updates as the DAG advances; the forwarded content/reasoning deltas let you stream the agent’s response within the same UI surface.
Buffer handlingSSE data may arrive in partial chunks — a single read() call might contain half an event or multiple events. Always buffer incoming data and split on newlines to ensure you process complete events.

​
Next Steps

Streaming Responses Guide

Hands-on guide to consuming streaming events.

Build an Agent

Create an agent with streaming support.

Agents API Reference

Streaming endpoint documentation.