Streaming & SSE

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

Event	Key Fields	Description
`start`	`run_id`, `session_id`	Agent run has started — save `session_id` for multi-turn
`step_started`	`step`	Agent is beginning a new reasoning step
`content_delta`	`delta`	A per-token piece of the agent’s text response. Accumulated server-side into the persisted run; the platform forwards each delta as it arrives.
`chunk`	`content`	Terminal text event with the final assembled response — emitted at the end of a non-ReAct (sync-style) generation
`tool_call`	`tool_name`, `arguments`	Agent is calling a tool with the given arguments
`tool_result`	`tool_name`, `result`	Tool execution completed with this result
`reasoning_delta`	`delta`	Per-token piece of the model’s reasoning trace (only when `reasoning_requested=true`). Forwarded but NOT persisted — use `reasoning` for the persisted trace.
`reasoning`	`text`	Persisted reasoning segment — the canonical “what the model thought” event for replay
`reasoning_summary`	`summary`	Final summarised reasoning trace at the end of the step
`step_completed`	`step`	Agent finished a reasoning step
`approval_requested`	`tool_name`, `tool_input`	Tool call paused — waiting for approval via the approve endpoint
`context_handler_created`	`context_handler_id`	A context handler was created mid-run (e.g. by a knowledge_search tool call). Lets you display the citation panel for the run.
`complete`	`run_id`, `content`, `usage`	Agent run finished
`error`	`message`	An 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.")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "What can you help me with?" }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  const lines = buffer.split("\n");
  buffer = lines.pop() || "";

  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      switch (event.event) {
        case "start":
          console.log("Session:", event.session_id);
          break;
        case "chunk":
          process.stdout.write(event.content);
          break;
        case "tool_call":
          console.log(`\n[Calling ${event.tool_name}...]`);
          break;
        case "complete":
          console.log("\nDone.");
          break;
      }
    }
  }
}

# Stream events to terminal (each line is a JSON event)
curl -N -X POST '{BASE_URL}/api/agents/{agent_id}/run/stream' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "What can you help me with?"}'

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:

Event	Key Fields	When
`workflow_start`	`execution_id`	The workflow execution has begun
`block_started`	`block_id`, `block_type`	The engine is about to execute a block
`block_chunk`	`block_id`, `delta`	A streaming block (agent / orchestration) produced output
`content_delta` / `reasoning_delta`	`block_id`, `delta`	Forwarded from an agent/orchestration block inside the workflow — lets the UI render tokens live
`block_output`	`block_id`, `output`	A block finished with this output, which downstream blocks may reference
`block_completed`	`block_id`	A block has fully finished (including any post-processing)
`block_error`	`block_id`, `error`	A block failed — by default, the workflow short-circuits unless the next block is in an error-handler position
`workflow_complete`	`execution_id`, `result`	The whole execution finished
`workflow_error`	`execution_id`, `error`	The execution failed at the top level

The block-level events let you build a step indicator that updates as the DAG advances, and 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.

Getting Started

Concepts

Guides

API Reference

SSE Overview

Agent Streaming Events

Keepalive

Persisted vs. forwarded-only

Consuming SSE in Python

Orchestration Events

Workflow Streaming

Next Steps

Streaming Responses Guide

Build an Agent

Agents API Reference

​SSE Overview

​Agent Streaming Events

​Keepalive

​Persisted vs. forwarded-only

​Consuming SSE in Python

​Orchestration Events

​Workflow Streaming

​Next Steps

Streaming Responses Guide

Build an Agent

Agents API Reference

SSE Overview

Agent Streaming Events

Keepalive

Persisted vs. forwarded-only

Consuming SSE in Python

Orchestration Events

Workflow Streaming

Next Steps