Skip to main content
Zeus uses Server-Sent Events (SSE) to stream the Agent’s reasoning process and tool calls to the frontend in real time. This page describes the complete streaming pipeline, event types, and chunking behavior.

​
Streaming Pipeline

The streaming pipeline uses end-to-end SSE pass-through: the Python backend generates events -> the Next.js API proxies and forwards them -> the frontend StreamProcessor consumes them.

​
Event Types

​
Core Events

Sandbox tool execution results (sandbox_exec_py, sandbox_exec_sh, etc.) are returned via the standard tool_call_result event and do not use a separate event type.

​
Event Mapping

Mapping from DeepAgents framework internal events to SSE messages:

​
Tool Call ID Queue

To correctly match on_tool_end events with their corresponding tool calls, the runtime maintains a FIFO queue (grouped by tool name, storing tool_call_id values). IDs are enqueued during on_chat_model_end and dequeued for matching during on_tool_end.

​
Frontend StreamProcessor

The frontend handleStreamMessage() consumes the SSE stream and routes events to the appropriate state management:

​
Tool Call Streaming

Tool calls support two-phase streaming: tool_call_chunk events stream the arguments in real time, then a tool_call event delivers the complete parameters.

​
Expected Event Order (Frontend)

stream-processor.ts creates/updates a streaming preview card (with streamingArgs) on each tool_call_chunk, then replaces it with the final card carrying complete parameters when the tool_call event arrives.

​
ai-backend (LangChain)

LangChain events naturally match this order:
At on_chat_model_end, the LLM has finished generating all arguments, so tc.get("args", {}) returns the fully parsed dict.

​
Video Pipeline SSE Events

When project_type === "video", the backend emits additional SSE events to drive the Video Workspace UI in real time. These events are handled by stream-processor.ts which updates videoStore (Zustand), triggering reactive UI updates in the Storyboard and Timeline panels. The projectType is propagated from the frontend’s ChatInterface through the SSE request body to the AI backend’s agent.py context, which conditionally loads the VIDEO.md prompt layer.

​
Chunking & Batching

​
Message Batching

The frontend merges rapid successive text updates, flushing UI updates in batches at approximately 60fps to avoid excessive re-rendering.

​
Virtual Scrolling

Long conversations use virtual scrolling, rendering only the message cards within the visible viewport to improve scroll performance.

​
Selective State Persistence

Only essential state is persisted (such as sessionId and messageIds); full message content is loaded on demand from the server.