@plott-ai/sdk-vercel-ai

Plott Analytics integration for the Vercel AI SDK. Track all your AI conversations, tool calls, and user behavior with a single line of code.

Installation

npm install @plott/sdk-vercel-ai
# or
bun add @plott/sdk-vercel-ai
# or
pnpm add @plott/sdk-vercel-ai

Quick Start

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { withPlottCallbacks } from '@plott-ai/sdk-vercel-ai';

const result = await streamText({
  model: openai('gpt-4o'),
  messages,
  ...withPlottCallbacks({ sessionId: 'user-123' }),
});

That's it! All messages, tool calls, errors, and metrics are automatically tracked.

Environment Variables

# Required
PLOTT_API_KEY=cpk_your_api_key

# Optional (defaults shown)
PLOTT_ENDPOINT=http://localhost:3001

API

withPlottCallbacks(options?)

Creates Plott tracking callbacks for streamText or generateText.

import { withPlottCallbacks } from '@plott-ai/sdk-vercel-ai';

const callbacks = withPlottCallbacks({
  // Session tracking (recommended)
  sessionId: 'user-session-123',
  conversationId: 'conv-456', // optional

  // Plott config (optional, uses env vars by default)
  apiKey: 'cpk_...',
  baseUrl: 'http://localhost:3001',
  environment: 'production',

  // Debug mode (optional)
  debug: true,

  // Chain your own callbacks (optional)
  onChunk: (event) => { /* your handler */ },
  onFinish: (event) => { /* your handler */ },
  onStepFinish: (stepResult) => { /* your handler */ },
  onError: (event) => { /* your handler */ },

  // Custom metadata (optional)
  metadata: { userId: 'user-123', feature: 'chat' },
});

PlottAIClient

For long-running services where you want to reuse the client:

import { PlottAIClient } from '@plott-ai/sdk-vercel-ai';

// Create once at startup
const plott = new PlottAIClient({
  apiKey: 'cpk_...',
  debug: true,
});

// Use for each request
const result = await streamText({
  model,
  messages,
  ...plott.createCallbacks({ sessionId }),
});

// Graceful shutdown
await plott.shutdown();

What Gets Tracked

| Event Type | Description | |------------|-------------| | MESSAGE | User and assistant messages with token counts | | CUSTOM (tool-call) | Tool invocations with name, args, and timing | | CUSTOM (tool-result) | Tool results and latency | | ERROR | Errors during generation | | RUN_EVENT | Start/end of each generation run | | STATE_SNAPSHOT | Token usage, finish reasons, step details | | CHECKPOINT | Automatic checkpoints every 5 turns |

Works With

• streamText() - Streaming text generation
• generateText() - Non-streaming text generation
• Tools and multi-step generation
• All Vercel AI SDK providers (OpenAI, Anthropic, etc.)

TypeScript

Full TypeScript support with exported types:

import type {
  PlottCallbackOptions,
  PlottCallbacks,
  OnChunkCallback,
  OnFinishCallback,
} from '@plott-ai/sdk-vercel-ai';

License

MIT