Skip to main content

Vercel AI SDK

@caesura-io/ai-sdk adds conversation analysis and guidance through language model middleware. It supports AI SDK majors 5, 6, and 7, including streaming.

Install and use​

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

Set CAESURA_API_KEY and OPENAI_API_KEY on the server.

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: 'Can you help me?' }],
  providerOptions: { caesura: {
    conversationId,
    turn: { id: 'customer-1', origin: 'customer' },
  } },
});
console.log(result.text);

Reuse the middleware and backend conversation ID across turns. Supply growing dialogue history, including actual replies, and a distinct ID for each customer message. streamText uses the same model and options. Pass abortSignal to propagate cancellation.

sync waits for guidance for the current call. The default, async, runs analysis in the background. Await middleware.caesura.flush() before a short-lived process exits; use shutdown() when disposing the integration.

Customer dialogue and tools​

Only new customer turns trigger analysis. Reuse the customer turn ID during tool continuations. If your provider input includes retrieval or other application-generated user messages, supply trusted participant dialogue through providerOptions.caesura.dialogue; use turn.origin: 'internal' for a call with no new customer turn.

The SDK adds guidance as separate messages after the analyzed dialogue and adds instructions for interpreting it to the system prompt. Keep SDK-injected requests out of your application transcript.

Saving and observability​

persist: true saves customer messages, their analyses, and completed agent replies to CaesuraO. Consume streams to completion to save their replies. Use persistMessages to also store your own copy. The default guidance store is in memory.

  • onCreditUsage receives reported analysis credits; createCreditMeter().record can collect them.
  • onError receives analysis/storage errors. Use failurePolicy: 'throw' with sync when guidance must succeed before generation.
  • onProviderEvent observes finalized provider requests and outcomes. persistProviderRequest is an awaited hook when saving the final request is required.

See Configuration, Conversations & Persistence, and the Next.js example. Durable storage and auditing are covered under Advanced integrations.