Octavus Docs

Quick Start

This guide will walk you through integrating Octavus into your application in under 10 minutes.

Prerequisites

  • Node.js 18+
  • An Octavus account with API key
  • A Next.js application (or any Node.js backend)

Test Your Agent First

Before integrating with SDKs, use Agent Preview to test your agent directly in the platform:

  1. Open your agent in the platform at octavus.ai/agents/[agentId]
  2. Click the Preview tab
  3. Configure session inputs and tool mock responses
  4. Start a conversation to test agent behavior

Agent Preview supports all trigger types, file attachments, tool mocking, and real-time streaming. This is the fastest way to iterate on your agent logic before writing any integration code.

Installation

Install the Octavus SDKs in your project:

bash

Backend Setup

1. Initialize the Client

Create an Octavus client instance in your backend:

typescript

2. Create a Session Endpoint

Create an API endpoint that creates sessions and returns the session ID:

typescript

Getting Your Agent ID

There are two ways to create and manage agents:

Option 1: Platform UI (Recommended for getting started)

  1. Go to octavus.ai and create an agent in the web editor
  2. Copy the agent ID from the URL (e.g., octavus.ai/agents/clxyz123abc456)
  3. Add it to your .env.local: OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456

Option 2: Local Development with CLI

For version-controlled agent definitions, use the Octavus CLI:

bash

The CLI approach is better for teams and CI/CD pipelines where you want agent definitions in your repository.

3. Create a Trigger Endpoint

Create an endpoint that handles triggers and streams responses:

typescript

Frontend Setup

1. Create a Chat Component

Use the useOctavusChat hook with the HTTP transport:

tsx

2. Create Session and Render Chat

tsx

Environment Variables

Add these to your .env.local:

bash

What's Next?

Now that you have a basic integration working: