Vercel AI SDK Integration

Use Sentrial’s wrapped functions at the point where your application already calls the AI SDK. Keep your existing model, tools, prompts and provider configuration.

Install

npm install @sentrial/sdk@0.6.0

Keep the ai and provider packages already used by your application. Sentrial’s declared compatibility window is ai >=3 <8; that range does not make every framework option interchangeable between versions.

Connect an existing call

This module accepts the same options your existing generateText call uses. Import runAgent at that call site and pass those options unchanged.

import { SentrialClient, wrapAISDK } from '@sentrial/sdk';
import * as ai from 'ai';

const client = new SentrialClient({
  apiKey: process.env.SENTRIAL_API_KEY,
  apiUrl: process.env.SENTRIAL_API_URL,
});
const trackedAI = wrapAISDK(ai, { client, defaultAgent: 'my-agent' });

export async function runAgent(options: Parameters<typeof ai.generateText>[0]) {
  try {
    return await trackedAI.generateText(options);
  } finally {
    await client.flush();
  }
}

Only calls made through the returned wrappers are instrumented. Other imports of generateText or streamText remain unchanged. The wrapper records the available model output, usage, tool results and errors; a successful agent response alone does not prove telemetry delivery. configureVercel({ apiKey, apiUrl, defaultAgent }) is also available for process-wide defaults. The explicit client above lets the application drain its telemetry queue. Do not put request-specific identity into mutable process-wide configuration.

User and conversation identity

Resolve authentication in your request handler first, then pass the resulting strings to a per-request wrapper. Keep using your application’s authorization checks for conversation access.

export async function runForRequest(
  options: Parameters<typeof ai.generateText>[0],
  identity: { userId: string; convoId?: string },
) {
  const tracked = wrapAISDK(ai, {
    client,
    defaultAgent: 'my-agent',
    userId: identity.userId,
    convoId: identity.convoId,
  });
  try {
    return await tracked.generateText(options);
  } finally {
    await client.flush();
  }
}

Identity callbacks, when used, must synchronously return a string or undefined. Await asynchronous authentication before constructing the wrapper; an async callback returns a promise instead of a user ID. Sentrial’s convoId groups telemetry and does not provide conversation memory to the model.

Tools and multi-step agents

Pass the existing tools, stopping conditions and callbacks unchanged. Sentrial wraps tool execution and observes model steps; it does not select your tools or change the agent’s stopping policy. For AI SDK 5, tools use inputSchema and multi-step stopping uses stopWhen. Older applications may use parameters and maxSteps. Follow the API for the version installed in your project rather than mixing those forms. See the official AI SDK 5 migration guide. Preserve structured tool results, including receipt IDs and pending/rejected states. Converting every tool result to a success string removes the evidence a signal needs to distinguish completed work from an attempted action.

Streaming

Keep the stream alive through consumption. For a command-line application, consume the stream and flush afterward:

export async function streamAgent(options: Parameters<typeof ai.streamText>[0]) {
  const result = trackedAI.streamText(options);
  try {
    for await (const text of result.textStream) {
      process.stdout.write(text);
    }
  } finally {
    await client.flush();
  }
}

In an HTTP application, return the response helper supported by your installed AI SDK and frontend protocol. Attach telemetry draining to the host’s supported request/stream completion lifecycle; flushing immediately after obtaining a stream object is too early. Keep your existing onFinish, onError and abort behavior. A disconnected, cancelled or unfinished stream is not proof of a completed business action. For a short-lived process, call await client.shutdown() after all its agent work finishes. Do not shut down a shared client after every request.

Structured output and providers

wrapAISDK(ai) also wraps generateObject and streamObject when those functions exist in your installed version. Keep your existing provider/model and output schema. Model availability comes from the provider; recognition in a Sentrial pricing table does not mean a retired model can still be called. Usage and cost depend on the metadata the framework returns and Sentrial’s model pricing coverage. Missing usage or an unknown price must not be interpreted as a free call. Review captured content and your PII configuration before sending sensitive inputs.

Verify the integration

Run an existing agent request through the wrapper, using a test tool result you can recognize.
Open Telemetry, inspect that run, and compare its final answer, tool inputs/results and completion state with your application.
Use the published CLI’s readback command for that session:

npx --yes --package @sentrial/sdk@0.6.0 sentrial doctor --session <session-id> --json

Use the same workspace and API URL as the agent; Doctor requires read access. Delivery checks do not establish signal accuracy. To evaluate a failure, follow signal diagnosis and review.

Document agent walkthrough

Inspect recorded model responses and source evidence from an AI SDK agent.

TypeScript SDK reference

Client options, sessions and event APIs.

Getting Started

Core Concepts

SDKs

Integrations

API Reference

Vercel AI SDK Integration

Install

Connect an existing call

User and conversation identity

Tools and multi-step agents

Streaming

Structured output and providers

Verify the integration

Document agent walkthrough

TypeScript SDK reference

​Install

​Connect an existing call

​User and conversation identity

​Tools and multi-step agents

​Streaming

​Structured output and providers

​Verify the integration

Document agent walkthrough

TypeScript SDK reference

Install

Connect an existing call

User and conversation identity

Tools and multi-step agents

Streaming

Structured output and providers

Verify the integration