WebSocket API

Overview

The WebSocket API provides real-time bidirectional communication between clients and NarraNexus agents. It is the primary interface for interactive conversations, delivering streaming responses, typing indicators, and tool execution updates as they happen.

Connection

Connect to the WebSocket endpoint at:

ws://localhost:8000/ws/{conversation_id}

Authentication is performed during the WebSocket handshake using a token query parameter or cookie. Once connected, messages are exchanged as JSON frames.

Message Format

All WebSocket messages follow a consistent envelope format:

{
  "type": "message|typing|tool_call|error",
  "data": {},
  "timestamp": "2025-01-01T00:00:00Z"
}

Client-to-server message types: message (send user input), ping (keep-alive).

Server-to-client message types: message (agent response), typing (agent is processing), tool_call (module tool invoked), tool_result (tool execution completed), error (processing error).

Streaming Responses

Agent responses are streamed token-by-token as they are generated by the LLM. Each streaming frame contains a partial response that the client appends to the display. A final message frame with "complete": true signals the end of the response. This enables low-latency conversational experiences even with large responses.

Connection Management

The WebSocket connection includes automatic reconnection logic on the client side. The server sends periodic ping frames to detect stale connections. If a connection drops during agent processing, the response is persisted and can be retrieved via the REST API's message history endpoint.