Overview
Nadoo AI uses Server-Sent Events (SSE) as the primary protocol for streaming real-time data from the server to the client. As an AI agent generates tokens, calls tools, retrieves documents, and reasons through steps, each action is emitted as a typed event that clients render incrementally. This provides a transparent, responsive experience where users see the agent’s work as it happens. SSE is a standard HTTP-based protocol where the client opens a single long-lived connection and the server pushes a sequence of typed events. It is simpler than WebSocket, reconnects automatically, and works reliably through HTTP proxies and load balancers.Connecting to the SSE Stream
Chat Streaming
Workflow Execution Streaming
text/event-stream response. Each event follows the SSE format:
Set
"stream": true in the chat completions request body to receive an SSE stream. Without this flag, the endpoint returns a standard JSON response after the full completion is generated.Event Types Reference
Nadoo AI defines 19 SSE event types organized into four categories. Each event carries a JSON payload with context-specific data.Workflow Events
Emitted during workflow execution to mark the lifecycle of the entire workflow run. These events are only present when the application is a Workflow App.workflow_start
workflow_start
Emitted when a workflow execution begins.
| Field | Type | Description |
|---|---|---|
workflow_id | string | The workflow being executed |
execution_id | string | Unique ID for this execution run |
workflow_end
workflow_end
Emitted when a workflow execution completes successfully.
| Field | Type | Description |
|---|---|---|
execution_id | string | The execution run ID |
duration_ms | integer | Total execution time in milliseconds |
workflow_error
workflow_error
Emitted when a workflow execution fails with an error.
| Field | Type | Description |
|---|---|---|
execution_id | string | The execution run ID |
error | string | Human-readable error description |
Node Events
Emitted as individual nodes within a workflow execute. Each node (AI Agent, Condition, Search Knowledge, etc.) produces start, end, and optionally error events.node_start
node_start
Emitted when a node begins execution.
| Field | Type | Description |
|---|---|---|
node_id | string | Unique node identifier within the workflow |
node_type | string | The node type (e.g., ai_agent, condition, search_knowledge) |
node_name | string | Human-readable node label |
node_end
node_end
Emitted when a node finishes execution successfully.
| Field | Type | Description |
|---|---|---|
node_id | string | The node that completed |
output | object | The node’s output data |
duration_ms | integer | Node execution time in milliseconds |
node_error
node_error
Emitted when a node encounters an error during execution.
| Field | Type | Description |
|---|---|---|
node_id | string | The node that failed |
error | string | Error description |
Agent Events
Emitted by the AI Agent node to provide visibility into the agent’s reasoning process, tool usage, and self-reflection behavior. These events are essential for building transparent AI interfaces.agent_iteration
agent_iteration
Emitted at the start of each reasoning iteration in ReAct, Reflection, or Tree of Thoughts modes. Tracks how many iterations the agent has performed.
| Field | Type | Description |
|---|---|---|
iteration | integer | Current iteration number (1-based) |
max_iterations | integer | Maximum allowed iterations |
agent_tool_call
agent_tool_call
Emitted when the agent decides to invoke a tool.
| Field | Type | Description |
|---|---|---|
tool_name | string | Name of the tool being called |
arguments | object | Arguments passed to the tool |
agent_tool_result
agent_tool_result
Emitted when a tool returns its result to the agent.
| Field | Type | Description |
|---|---|---|
tool_name | string | Name of the tool that completed |
result | string | The tool’s output |
agent_reflection
agent_reflection
Emitted in Reflection mode when the agent critiques and refines its own output.
| Field | Type | Description |
|---|---|---|
critique | string | The agent’s self-critique |
refinement | string | The planned improvement |
agent_thinking
agent_thinking
Emitted when the agent enters a reasoning phase, providing visibility into its thought process.
| Field | Type | Description |
|---|---|---|
content | string | The agent’s reasoning text |
cot_step
cot_step
Emitted in Chain of Thought mode for each discrete reasoning step.
| Field | Type | Description |
|---|---|---|
step | integer | Step number (1-based) |
thought | string | The reasoning content for this step |
System Events
Emitted to provide metadata, resource usage information, and system-level error reporting throughout the streaming session.token_usage
token_usage
Reports token consumption for the current LLM call or response.
| Field | Type | Description |
|---|---|---|
prompt_tokens | integer | Tokens in the input prompt |
completion_tokens | integer | Tokens in the generated response |
total_tokens | integer | Sum of prompt and completion tokens |
cost_update
cost_update
Reports the estimated monetary cost for the current response based on the model’s pricing.
| Field | Type | Description |
|---|---|---|
cost_usd | float | Estimated cost in USD |
model | string | The model used for this call |
context_trimmed
context_trimmed
Emitted when the conversation context was trimmed to fit within the model’s context window.
| Field | Type | Description |
|---|---|---|
original_tokens | integer | Token count before trimming |
trimmed_tokens | integer | Token count after trimming |
Context trimming uses the strategy configured on the application:
truncate (drop oldest messages), summarize (condense history), or error (fail if context exceeds limit). The default strategy is truncate with a 4096-token limit.llm_call_start
llm_call_start
Emitted when an LLM API call is initiated.
| Field | Type | Description |
|---|---|---|
model | string | The model being called |
provider | string | The AI provider (openai, anthropic, google, etc.) |
llm_call_end
llm_call_end
Emitted when an LLM API call completes.
| Field | Type | Description |
|---|---|---|
model | string | The model that was called |
latency_ms | integer | Round-trip latency in milliseconds |
memory_update
memory_update
Emitted when the conversation memory is updated (e.g., messages trimmed from the buffer, summary regenerated).
| Field | Type | Description |
|---|---|---|
type | string | Memory type: buffer, summary, or knowledge_graph |
messages_retained | integer | Number of messages kept in memory |
error
error
Emitted when a system-level error occurs during streaming.
See the Error Handling page for the full list of error codes.
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code |
message | string | Human-readable error description |
Event Summary Table
| # | Event | Category | Description |
|---|---|---|---|
| 1 | workflow_start | Workflow | Workflow execution has begun |
| 2 | workflow_end | Workflow | Workflow completed successfully |
| 3 | workflow_error | Workflow | Workflow failed with an error |
| 4 | node_start | Node | A node has started executing |
| 5 | node_end | Node | A node has finished executing |
| 6 | node_error | Node | A node encountered an error |
| 7 | agent_iteration | Agent | An agent reasoning iteration occurred |
| 8 | agent_tool_call | Agent | The agent is invoking a tool |
| 9 | agent_tool_result | Agent | A tool returned its result |
| 10 | agent_reflection | Agent | The agent is reflecting on its output |
| 11 | agent_thinking | Agent | The agent is in a reasoning phase |
| 12 | cot_step | Agent | A chain-of-thought reasoning step |
| 13 | token_usage | System | Token consumption for the response |
| 14 | cost_update | System | Estimated cost for the response |
| 15 | context_trimmed | System | Context was trimmed to fit the model window |
| 16 | llm_call_start | System | An LLM API call has been initiated |
| 17 | llm_call_end | System | An LLM API call has completed |
| 18 | memory_update | System | Conversation memory was updated |
| 19 | error | System | A system-level error occurred |
Example SSE Stream
Below is a complete SSE stream from a Chat App with tool use and knowledge base retrieval:Client Implementation
- JavaScript
- Python
- cURL
Events by Agent Mode
Different agent modes emit different combinations of events. Use this table to understand which events to expect based on your application’s configuration.| Event | Standard | Chain of Thought | ReAct | Function Calling | Reflection | Tree of Thoughts |
|---|---|---|---|---|---|---|
agent_thinking | — | Yes | Yes | — | Yes | Yes |
cot_step | — | Yes | — | — | — | — |
agent_iteration | — | — | Yes | — | Yes | Yes |
agent_tool_call | — | — | Yes | Yes | — | — |
agent_tool_result | — | — | Yes | Yes | — | — |
agent_reflection | — | — | — | — | Yes | — |
llm_call_start/end | Yes | Yes | Yes | Yes | Yes | Yes |
token_usage | Yes | Yes | Yes | Yes | Yes | Yes |
cost_update | Yes | Yes | Yes | Yes | Yes | Yes |
Error Handling
Reconnection Strategy
SSE connections may drop due to network issues. The browser’s nativeEventSource API automatically reconnects, but when using fetch for POST-based SSE streams, implement reconnection manually:
Wait with exponential backoff
Start at 1 second and double the wait time on each retry, up to a maximum of 30 seconds.
Reconnect
Re-establish the SSE connection. If your server supports
Last-Event-ID, include it in the request header to resume from the last received event.Common Error Codes
| Code | Description | Recommended Action |
|---|---|---|
rate_limit | AI provider rate limit exceeded | Wait and retry (server may auto-retry) |
context_overflow | Input exceeded model’s context window | Reduce message history or input size |
tool_error | A tool invocation failed | Check tool configuration and inputs |
timeout | Request or LLM call timed out | Retry with a simpler prompt or lower max_tokens |
provider_error | AI provider returned an unexpected error | Check provider status; retry after a delay |
auth_error | Authentication failure mid-stream | Refresh token and reconnect |
Frontend Integration
Nadoo AI provides built-in React components for SSE integration.useAgentSSE Hook
TheuseAgentSSE hook manages the SSE connection lifecycle, parses events, and exposes reactive state:
AgentExecutionMonitor Component
For Workflow Apps, theAgentExecutionMonitor renders a visual timeline of workflow execution:
- Node execution timeline with status indicators (running, completed, failed)
- Expandable node details showing input, output, and duration
- Tool call cards with arguments and results
- Thinking/reasoning steps from CoT and ReAct strategies
- Token usage and cost per node and overall