Skip to main content

Quickstart

Add CaesuraO analysis to a model call using the Vercel AI SDK. For other integrations, see the JavaScript and Python SDK guides.

Install​

npm install @caesura-io/ai-sdk "ai@>=5 <8" @ai-sdk/openai

Set CAESURA_API_KEY and OPENAI_API_KEY on your server. The CaesuraO endpoint defaults to https://api.caesurao.com.

Create a conversation and generate a reply​

import { generateText, wrapLanguageModel } from 'ai';
import { openai } from '@ai-sdk/openai';
import { caesuraMiddleware } from '@caesura-io/ai-sdk';

const middleware = caesuraMiddleware({ mode: 'sync' });
const conversationId = await middleware.createConversation({ name: 'Support session' });
if (!conversationId) throw new Error('Could not create a saved conversation.');
const model = wrapLanguageModel({ model: openai('gpt-5.4-mini'), middleware });

const result = await generateText({
  model,
  messages: [{ role: 'user', content: 'I need help setting up my account.' }],
  providerOptions: { caesura: {
    conversationId,
    turn: { id: 'customer-message-1', origin: 'customer' },
  } },
});

console.log(result.text);
await middleware.caesura.shutdown(); // When this application instance is finished.

mode: 'sync' waits for analysis so the first reply can use its guidance. The default, async, makes completed guidance available to a later call.

For the next turn, reuse the conversation ID and middleware, append the actual reply and new customer message to your history, and give the new customer message a new turn ID. Create another conversation only when starting an independent chat. An ID does not load history for you.

By default, CaesuraO saves new customer messages, completed agent replies, and analyses. Customer turns are saved even when analysis cadence skips them. Record application-provided greetings explicitly; earlier history is not imported automatically. See Conversations & Persistence and Configuration for saving, failures, and background work.

Runnable JavaScript examples · Runnable Python examples