Vercel AI SDK

Integrate the Vercel AI SDK with LangWatch for TypeScript-based tracing, token tracking, and real-time agent testing.

Quick setup? Instead of following these steps manually, copy a prompt into your coding agent and it will set this up for you automatically.

The LangWatch library integrates your TypeScript application with LangWatch. The library syncs the messages in the background, so it doesn’t intercept or block your LLM calls.

Protip: wanna to get started even faster? Copy our llms.txt and ask an AI to do this integration

Prerequisites

• Create an API key from Settings → API Keys. See the API Keys guide for details.

Installation

npm install langwatch

Configuration

Ensure LANGWATCH_API_KEY is set:

Environment variable

.env

LANGWATCH_API_KEY='your_api_key_here'
LANGWATCH_PROJECT_ID='your_project_id_here'

Client parameters

import { LangWatch } from 'langwatch';

const langwatch = new LangWatch({
  apiKey: 'your_api_key_here',
  projectId: 'your_project_id_here',
});

If you are using a service API key (e.g. for CI/CD or multi-project setups), you must also set LANGWATCH_PROJECT_ID so the SDK knows which project to send traces to. You can find the project ID in your project settings. Project API keys obtained via npx langwatch login or from the project settings page already have the project context built in.

Basic Concepts

• Each message triggering your LLM pipeline as a whole is captured with a Trace.
• A Trace contains multiple Spans, which are the steps inside your pipeline.
  • A span can be an LLM call, a database query for a RAG retrieval, or a simple function transformation.
  • Different types of Spans capture different parameters.
  • Spans can be nested to capture the pipeline structure.
• Traces can be grouped together on LangWatch Dashboard by having the same thread_id in their metadata, making the individual messages become part of a conversation.
  • It is also recommended to provide the user_id metadata to track user analytics.

Installation

npm

npm i langwatch ai @ai-sdk/openai

Usage

The LangWatch API key is configured by default via the LANGWATCH_API_KEY environment variable.

Set up observability and enable telemetry on your Vercel AI SDK calls:

import { setupObservability } from "langwatch/observability/node";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

setupObservability({ serviceName: "<project_name>" });

async function main(message: string): Promise<string> {
  const response = await generateText({
    model: openai("gpt-5-mini"),
    prompt: message,
    experimental_telemetry: { isEnabled: true },
  });
  return response.text;
}

console.log(await main("Hey, tell me a joke"));

The Vercel AI SDK automatically sends traces to LangWatch when experimental_telemetry.isEnabled is set to true. For Next.js applications, configure OpenTelemetry in your instrumentation.ts file using LangWatchExporter.

Metadata

Pass experimental_telemetry.metadata to tag the call. LangWatch reads these keys from it:

Key	What it does
labels	An array of labels. Filter the trace list by them.
thread_id	Groups the call into a conversation with every other call that sends the same id.
user_id	The end user the call belongs to.
customer_id	The customer or tenant the call belongs to.

Any other key becomes custom metadata on the trace, filterable by its own name.

const response = await generateText({
  model: openai("gpt-5-mini"),
  prompt: message,
  experimental_telemetry: {
    isEnabled: true,
    metadata: {
      labels: ["checkout", "beta"],
      thread_id: "conversation-8f21",
      user_id: "user-42",
      tenant: "eu-west",
    },
  },
});

experimental_telemetry is the AI SDK’s own experimental API, and its shape can change between AI SDK versions.

It accepts strings, numbers, booleans and arrays of them as metadata values. It does not accept a nested object, so flatten anything deeper into separate keys. A null inside a labels array is dropped.

A thread_id, user_id, customer_id or metadata.<key> you also set as a span attribute wins over the one you pass here. Labels are the exception: the two sets are combined, so the trace keeps both. See Capturing Metadata and Attributes for the attribute names.

Related

• Capturing RAG - Learn how to capture RAG data from retrievers and tools
• Capturing Metadata and Attributes - Add custom metadata and attributes to your traces and spans
• Capturing Evaluations & Guardrails - Log evaluations and implement guardrails in your Vercel AI SDK applications