Vercel AI SDK integration

Converra turns Vercel AI SDK conversations into tested behavior fixes. Connect your agent, diagnose a failing turn, compare a proposed fix against the current prompt in simulation, and approve what goes live. Each fix gets a production verdict: verified, not fixed, or confounded.

Install

npm install @converra/ai-sdk-middleware ai@7 @ai-sdk/openai@4

Use these aligned major versions for a new project. Existing AI SDK 4, 5, and 6 projects use OpenAI provider majors 1, 2, and 3 respectively. Keep your provider API key and CONVERRA_API_KEY in your server environment. Never expose them to the browser.

Capture model calls

This example is for a long-running Node.js service. Set OPENAI_MODEL to the model your agent already uses.

import { createConverraMiddleware } from '@converra/ai-sdk-middleware';
import { createOpenAI } from '@ai-sdk/openai';
import { generateText, wrapLanguageModel } from 'ai';

const apiKey = process.env.CONVERRA_API_KEY;
const modelId = process.env.OPENAI_MODEL;
if (!apiKey || !modelId) throw new Error('Set CONVERRA_API_KEY and OPENAI_MODEL');

const openai = createOpenAI();
const model = wrapLanguageModel({
  model: openai(modelId),
  middleware: createConverraMiddleware({
    apiKey,
    promptName: 'Refund support',
    batchSize: 1,
  }),
});

const result = await generateText({
  model,
  system: 'Ask for an order number before discussing refund eligibility.',
  messages: [{ role: 'user', content: 'Can I get a refund?' }],
  providerOptions: { converra: { sessionId: 'support-session-123' } },
});

console.log(result.text);

Use the wrapped model with streamText too. Streaming capture occurs when the stream finishes, so consume or forward the entire stream. The middleware captures each model call separately; a session ID groups calls but does not turn them into one transcript.

Capture sends asynchronously. The standalone middleware has no public flush method, so a process that exits or freezes immediately can lose a trace. For serverless handlers or short scripts, use the Node.js SDK and await converra.send() with the completed messages before the request ends. Do not instrument the same call through both paths.

From a wrong refund answer to a fix

If the agent promises a refund without an order number, use the captured conversation to identify the failing step. Converra generates a prompt or configuration change, tests it against the baseline on shared personas, and checks scenarios the baseline already handles. Approve the winning change before applying it to your application.

The capture middleware records evidence; it does not replace your application prompt. To serve approved prompt variants through the SDK, see the separate converra/ai-sdk middleware in the SDK integration guide. Keep the system prompt configured in Converra aligned with the one your service actually runs.

Use from a coding agent

Connect Claude Code, Codex, or Cursor to Converra. Start with get_account and list_agents, inspect a failed turn with get_run_step_diagnosis, then use the optimization and simulation tools before approval. After applying the fix, query get_deployment_impact and get_verification_evidence. A better simulation score alone does not establish that production behavior improved.

See how production verdicts are decided for evidence thresholds and confounding limits.

Source and compatibility

Example checked on 2026-10-15 against @converra/ai-sdk-middleware 0.2.3: createConverraMiddleware, promptName, and per-call providerOptions.converra.sessionId. See the published package and Vercel middleware reference.