Streaming events

POST /execute returns Server-Sent Events. The events fall into four families: lifecycle, content, tool calls, and human-in-the-loop. This page catalogs them. Each event has the shape:

event: <type>
data: <json>

A blank line terminates each event. The data payload’s exact shape depends on the event type.

Lifecycle

`thread_lifecycle`

Emitted at the start and end of every turn.

{
  "phase": "started" | "completed" | "errored",
  "task_id": "demo-001",
  "turn_id": "...",
  "timestamp": "2026-04-27T12:34:56.000Z"
}

A turn always opens with a started event and closes with completed or errored.

`error`

Emitted when execution fails mid-stream. After this event, no more events will arrive on the current call.

{
  "error": "LLM_PROVIDER_ERROR",
  "message": "Upstream model returned 500.",
  "details": { /* optional */ }
}

Content

`text_delta`

A chunk of model output text. Concatenate all text_delta events in order to get the full response.

{
  "text": "Hello, "
}

`thinking_delta`

A chunk of the model’s internal reasoning when extended thinking is on. Treat the same way as text_delta but render in a separate UI region (or hide entirely if you don’t surface thinking to users).

{
  "text": "Let me think about this..."
}

`content_block_start` / `content_block_stop`

Emitted around content blocks (text, thinking, tool use). Useful when you need to track block boundaries — for example, to emit a UI separator.

{
  "block_index": 0,
  "block_type": "text" | "thinking" | "tool_use"
}

Tool execution

`tool_call`

The model has decided to call a tool. The input field contains whatever the model provided as arguments.

{
  "tool": "bash",
  "tool_call_id": "...",
  "input": {
    "command": "ls -la"
  }
}

`tool_result`

The tool finished. output holds whatever the tool returned. May include an error field if the call failed.

{
  "tool": "bash",
  "tool_call_id": "...",
  "output": "drwxr-xr-x  6 ...",
  "error": null
}

Human-in-the-loop

`hitl_request`

The agent has paused and needs your answer. Reply with POST /hitl/respond using the request_id. Until you reply, the stream will continue to emit other events (heartbeats) but will not proceed.

{
  "request_id": "hitl-...",
  "kind": "question" | "permission",
  "question": "Should I delete the file foo.txt?",
  "context": { /* the agent's view of why it's asking */ },
  "options": ["yes", "no"]
}

`hitl_resolved`

Emitted after POST /hitl/respond to signal that the loop has resumed.

{
  "request_id": "hitl-...",
  "answer": "yes"
}

Memory and context

`working_memory_update`

Emitted when the agent writes to working memory.

{
  "entry_type": "note" | "observation" | "summary",
  "content": "..."
}

`compaction_event`

Emitted when the compaction orchestrator collapses earlier turns.

{
  "before_tokens": 24000,
  "after_tokens": 8500,
  "strategy": "summary" | "structured_extraction"
}

Diagnostic

`heartbeat`

Periodic. Use to detect dead connections client-side.

{
  "now": "2026-04-27T12:34:56.000Z"
}

`usage`

Token usage so far for the turn.

{
  "input_tokens": 1240,
  "output_tokens": 312,
  "cache_hit_tokens": 980
}

Notes for client implementers

Missing event: lines. Some clients omit the event: line and only send data:. The Engine always emits event:. Use it to route.
Reordering. Events are emitted in execution order. Don’t try to reorder them.
Multiple text streams. A single turn can emit text from multiple tool calls and thinking blocks. Use content_block_start / content_block_stop to separate them.
Disconnections. If your client disconnects mid-stream, use GET /execute/replay?after=<ts> to fetch missed events.

Get started

Capabilities

Build with the Engine

Agents and tools

Test and evaluate

API reference

Guides

Resources

Streaming events

Lifecycle

`thread_lifecycle`

`error`

Content

`text_delta`

`thinking_delta`

`content_block_start` / `content_block_stop`

Tool execution

`tool_call`

`tool_result`

Human-in-the-loop

`hitl_request`

`hitl_resolved`

Memory and context

`working_memory_update`

`compaction_event`

Diagnostic

`heartbeat`

`usage`

Notes for client implementers

See also

​Lifecycle

​thread_lifecycle

​error

​Content

​text_delta

​thinking_delta

​content_block_start / content_block_stop

​Tool execution

​tool_call

​tool_result

​Human-in-the-loop

​hitl_request

​hitl_resolved

​Memory and context

​working_memory_update

​compaction_event

​Diagnostic

​heartbeat

​usage

​Notes for client implementers

​See also

Lifecycle

`thread_lifecycle`

`error`

Content

`text_delta`

`thinking_delta`

`content_block_start` / `content_block_stop`

Tool execution

`tool_call`

`tool_result`

Human-in-the-loop

`hitl_request`

`hitl_resolved`

Memory and context

`working_memory_update`

`compaction_event`

Diagnostic

`heartbeat`

`usage`

Notes for client implementers

See also