Client SDK Overview
Octavus provides two packages for frontend integration:
| Package | Purpose | Use When |
|---|---|---|
@octavus/react | React hooks and bindings | Building React applications |
@octavus/client-sdk | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |
Most users should install @octavus/react — it includes everything from @octavus/client-sdk plus React-specific hooks.
Installation
React Applications
Current version: 2.20.0
Other Frameworks
Current version: 2.20.0
Transport Pattern
The Client SDK uses a transport abstraction to handle communication with your backend. This gives you flexibility in how events are delivered:
| Transport | Use Case | Docs |
|---|---|---|
createHttpTransport | HTTP/SSE (Next.js, Express, etc.) | HTTP Transport |
createSocketTransport | WebSocket, SockJS, or other socket protocols | Socket Transport |
When the transport changes (e.g., when sessionId changes), the useOctavusChat hook automatically reinitializes with the new transport.
Recommendation: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).
React Usage
The useOctavusChat hook provides state management and streaming for React applications:
Framework-Agnostic Usage
The OctavusChat class can be used with any framework or vanilla JavaScript:
Key Features
Unified Send Function
The send function handles both user message display and agent triggering in one call:
Message Parts
Messages contain ordered parts for rich content:
Status Tracking
Stop Streaming
Retry Last Trigger
Re-execute the last trigger from the same starting point. Messages are rolled back to the state before the trigger, the user message is re-added (if any), and the agent re-executes. Already-uploaded files are reused without re-uploading.
canRetry is true when a trigger has been sent and the chat is not currently streaming or awaiting input.
Hook Reference (React)
useOctavusChat
useAutoScroll
Smart auto-scroll for chat containers. Scrolls to bottom when content updates, but pauses if the user has scrolled up. See Streaming — Auto-Scroll for full usage.
Transport Reference
createHttpTransport
Creates an HTTP/SSE transport using native fetch():
createSocketTransport
Creates a WebSocket/SockJS transport for real-time connections:
Socket transport provides additional connection management:
For detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see Socket Transport.
Class Reference (Framework-Agnostic)
OctavusChat
Next Steps
- HTTP Transport — HTTP/SSE integration (recommended)
- Socket Transport — WebSocket and SockJS integration
- Messages — Working with message state
- Streaming — Building streaming UIs
- Client Tools — Interactive browser-side tool handling
- Operations — Showing agent progress
- Error Handling — Handling errors with type guards
- File Uploads — Uploading images and documents
- Examples — Complete working examples