Skip to main content

OpenAI SDK

@caesura-io/openai wraps OpenAI Chat Completions and Responses, including streaming. Supported OpenAI Node versions are >=4.87.3 <8.

Install and use​

npm install @caesura-io/openai "openai@>=4.87.3 <8"

Set OPENAI_API_KEY and CAESURA_API_KEY on the server.

import OpenAI from 'openai';
import { createCaesura } from '@caesura-io/openai';

const client = createCaesura(new OpenAI(), { mode: 'sync' });
const conversationId = await client.createConversation({ name: 'Support session' });
if (!conversationId) throw new Error('Could not create a saved conversation.');

const response = await client.responses.create(
  { model: 'gpt-5.4-mini', input: 'Can you help me?' },
  { caesura: { conversationId, turn: { id: 'customer-1', origin: 'customer' } } },
);
console.log(response.output_text);

For Chat Completions, use client.chat.completions.create({ model, messages }, { caesura: { conversationId, turn } }). Pass CaesuraO options in the second argument, separately from the provider body. Both APIs support stream: true.

Create once, retain the returned ID, and send growing dialogue history on later calls. Give each new customer message a distinct turn ID and reuse it for retries/tool continuations. If input includes user-role retrieval text, select trusted dialogue with caesura.dialogue. Use turn.origin: 'internal' when no new customer turn exists.

Lifecycle​

mode: 'sync' waits for current-call guidance. The default, async, makes completed guidance available to later calls. Await client.caesura.flush() to finish background analysis and client.caesura.shutdown() when disposing the integration.

Pass the OpenAI request option signal to propagate cancellation. The default failurePolicy: 'continue' allows generation after analysis/storage failures; use 'throw' with sync when analysis is required.

HTTP persistence saves customer messages, their analyses, and completed agent replies. Consume streams to completion to save their replies. Use persistMessages to also maintain an application-owned archive. See Conversations & Persistence.

Observability​

Use onCreditUsage for reported analysis credits and onError for analysis failures. onProviderEvent observes finalized requests and provider outcomes; persistProviderRequest is an awaited hook for required request storage.

Configuration · Runnable backend example · Advanced integrations