Octavus Docs

HTTP Transport

The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.

When to Use HTTP Transport

Use CaseRecommendation
Next.js, Remix, or similar frameworks✅ Use HTTP
Standard web apps without special requirements✅ Use HTTP
Serverless deployments (Vercel, etc.)✅ Use HTTP
Need custom real-time eventsConsider Socket Transport

Basic Setup

Client

tsx

Server (Next.js API Route)

typescript

Session Creation

Sessions should be created server-side before rendering the chat. There are two patterns:

Pattern 1: Create Session on Page Load

tsx

Pattern 2: Server-Side Session Creation (App Router)

tsx

This pattern is cleaner as the session is ready before the component renders.

Error Handling

Handle errors with structured error information:

tsx

See Error Handling for comprehensive error handling patterns.

Stop Streaming

Allow users to cancel ongoing streams. When stop() is called:

  1. The HTTP request is aborted via the signal
  2. Any partial content is preserved in the message
  3. Tool calls in progress are marked as cancelled
  4. Status changes to idle
tsx

Important: For stop to work end-to-end, pass the options.signal to your fetch() call and forward request.signal to session.execute() on the server.

Express Server

For non-Next.js backends:

typescript

Transport Options

typescript

The request function receives a discriminated union. Spread the request onto your payload:

typescript

Protocol

Request Format

The request function receives a discriminated union with type to identify the request kind:

Trigger Request (start a new turn):

json

Continue Request (after client tool handling):

json

Response Format

The server responds with an SSE stream:

text

If client tools are needed, the stream pauses with a client-tool-request event:

text

The client handles the tools and sends a continue request to resume.

See Streaming Events for the full list of event types.

Next Steps