Trace Events
Trace events give real-time visibility into task execution over the WebSocket stream. Each event represents an action, state change, or milestone during a run.
Event Structure
{
"id": "unique_event_id",
"event_type": "step_start_dag",
"scope": "step",
"action": "start",
"category": "dag",
"timestamp": 1234567890.123,
"task_id": "task_123",
"step_id": "step_456",
"data": { "step_name": "Web Search" },
"parent_id": "parent_event_id"
}Fields
| Field | Description |
|---|---|
id | Unique event identifier. |
event_type | Specific event, e.g. step_start_dag, action_end_llm. |
scope | task, step, action, or system. |
action | start, end, error, info, or update. |
category | dag, react, general, tool, llm, memory, visualization, compact (context-compaction events). |
timestamp | Unix timestamp with milliseconds. |
task_id / step_id | Associated task and step. |
data | Event-specific payload. |
parent_id | Parent event id for hierarchical events. |
Scopes
| Scope | Covers |
|---|---|
task | Whole-task milestones — DAG/ReAct start and end, task errors. |
step | Individual execution steps within a task. |
action | Atomic actions within a step — tool calls, LLM calls, memory ops. |
system | System-level info, including visualization (DAG) updates. |
Categories & Actions
Combine scope + action + category to route events. For example, an action/end/llm event reports token usage, while a step/start/dag event announces a new step. Actions are start, end, error, info, and update.
ws.onmessage = (event) => {
const e = JSON.parse(event.data);
switch (e.scope) {
case "task": handleTaskEvent(e); break;
case "step": handleStepEvent(e); break;
case "action": handleActionEvent(e); break;
case "system": handleSystemEvent(e); break;
}
};