Core Concepts
Server-Sent Events (SSE) Protocol
The standardized real-time event protocol for Omni agent streaming sessions.
Omni streams agent execution output using standard Server-Sent Events (text/event-stream). The stream exposes the agent's internal reasoning, tool calls, and final responses.
Event Sequence
During an agent session, events arrive in a strictly ordered sequence:
event: thought
data: {"text": "Searching the knowledge base for project release dates..."}
event: tool_call
data: {"tool": "search_memories", "call_id": "call_123", "args": {"query": "Project Phoenix"}}
event: tool_result
data: {"call_id": "call_123", "result": "Found 1 memory: Launch is September 1st, 2026."}
event: message
data: {"delta": "Project Phoenix is scheduled to launch on "}
event: message
data: {"delta": "September 1st, 2026."}
event: done
data: {"run_id": "run_01jze9m2", "total_tokens": 342, "status": "completed"}Event Types
| Event Name | Payload Schema | Description |
|---|---|---|
thought | { "text": string } | Internal chain-of-thought or reasoning step produced before tool execution. |
tool_call | { "tool": string, "call_id": string, "args": object } | Invocations of external MCP tools or internal functions. |
tool_result | { "call_id": string, "result": any } | The output or return value from the executed tool. |
message | { "delta": string } | Incremental tokens of the user-facing response. |
error | { "code": string, "message": string } | Emitted when an unrecoverable failure occurs mid-stream. |
done | { "run_id": string, "total_tokens": number, "status": string } | Terminal completion signal closing the HTTP stream. |
Dumb Client Parsing Rules
- Zero Execution Logic: Clients must never execute tools or generate prompt injections. All tools run on the server.
- Sequential Display: Render
thoughtblocks distinctly (e.g., in expandable callouts or muted text), and appendmessagedeltas directly to the chat viewport. - Completion Detection: Close connection handlers only upon receiving the
doneevent or EOF.