Next.js Chat Example

This example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.

What You're Building

A chat interface that:

• Creates sessions server-side
• Streams AI responses in real-time
• Handles tool calls on your server
• Shows typing status during streaming

Architecture

Prerequisites

• Next.js 14+ with App Router
• Octavus account with API key
• An agent configured in Octavus

Step 1: Install Dependencies

Step 2: Configure Environment

Step 3: Create the Octavus Client

Step 4: Create Session Endpoint

Sessions hold conversation state. Create one when the user opens the chat:

Protocol Note: The input object contains variables defined in your agent's protocol. For example, if your agent has COMPANY_NAME as an input variable:

Step 5: Create Trigger Endpoint

Triggers execute agent actions. The user-message trigger is the most common:

Protocol Note: Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.

Step 6: Build the Chat Component

Step 7: Create the Page

Protocol Integration

Your agent's protocol defines the triggers and tools. Here's how the code maps to protocol:

Triggers

The send() call maps directly:

Tools

Tool handlers receive the parameters as args:

Next Steps

• Protocol Overview — Define agent behavior
• Messages — Rich message rendering
• Streaming — Advanced streaming UI