Documentation Index
Fetch the complete documentation index at: https://docs.nadoo.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
Next Steps
WebSocket API
Bidirectional real-time communication for interactive workflows
Error Handling
API error codes, streaming errors, and best practices
Chat Streaming
Full streaming guide with frontend integration
AI Agent Strategies
Agent modes that produce different event patterns