Vercel AI SDK

The Vercel AI SDK (ai + @ai-sdk/*) is the de-facto choice for Next.js + Node AI apps. Trefur's patchVercelAI adapter wraps generateText, streamText, generateObject, streamObject, and the tool-execution loop, so you see every model call + tool call without modifying your route handlers.

Install

npm install @trefur/observe ai @ai-sdk/openai

Setup

import * as ai from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import { TrefurObserve, patchVercelAI } from '@trefur/observe';

// Initialise observe once at startup (e.g. in a server module).
TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: 'docs-chat', framework: 'vercel-ai' },
});
// patchVercelAI takes the imported 'ai' module namespace and the
// observe instance. Call it once, before your first generateText /
// streamText call, then invoke the SDK through the same 'ai' import.
patchVercelAI(ai, TrefurObserve.getInstance());

const lookupOrder = ai.tool({
  description: 'Look up an order by id',
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ({ status: 'shipped' }),
});

// Non-streaming
const { text, toolCalls } = await ai.generateText({
  model: openai('gpt-4o'),
  prompt: 'Where is order #12345?',
  tools: { lookupOrder },
  maxSteps: 3,
});

// Streaming (in a Next.js route handler)
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await ai.streamText({
    model: openai('gpt-4o'),
    messages,
    tools: { lookupOrder },
  });
  return result.toDataStreamResponse();
}

What gets traced

  • Each call to generateText / streamText / generateObject / streamObject creates a run.
  • Tool calls — every tool({}) invocation with args + return value.
  • Multi-step loops — when maxSteps > 1, each step (model decides → tool runs → model decides) renders as a separate step under one run.
  • Provider — extracted from the model id (openai, anthropic, google, mistral, bedrock, etc.).
  • Streaming chunks are batched into the final completion text on stream close.
  • Errors + cancellations from the underlying provider are tagged on the run.

Common use case — server-side AI route handlers

The classic Vercel-AI pattern is a Next.js POST route that returns a streaming response to useChat. Trefur captures the trace server-side. Pair with the OpenAI proxy for an additional check on raw API calls if you want belt-and-braces capture.

Common pitfalls

  • Edge runtime. The SDK works on the Edge runtime but the OS-level subprocess / fs instrumentors are unavailable. Use the SDK on Node runtime for full coverage; Edge gets LLM + tool-call telemetry only.
  • Streaming early-close. If the client disconnects mid-stream, the run is marked cancelled and the accumulated text up to the cut is captured. This is intentional.
  • useChat (client-side). Client-side React calls are not instrumented — Trefur lives server-side. The server route is where the action happens, so this is correct.

See the JavaScript SDK reference for the full adapter surface.