--- title: "Vercel AI SDK Tracing" description: "Automatically trace Vercel AI SDK agent executions, tool calls, and multi-step workflows." sidebar: label: "Vercel AI SDK" seo: title: "Vercel AI SDK Tracing with Judgment | Agent Framework Integration Docs" description: "Trace Vercel AI SDK agent executions with Judgment, including tool calls, handoffs, spans, and behavior for production agent monitoring." --- **Vercel AI SDK integration** captures traces from your Vercel AI SDK applications, including agent execution flow, tool invocations, and multi-step reasoning processes. This integration is designed for TypeScript applications. > **Info** > > Refer to the Judgeval [Tracer](/sdk-reference/typescript/trace/tracer) documentation > for more information on how to instrument your application. ## AI SDK 7 {/* @test-flow id: integration-vercel-ai-sdk lang: typescript env: JUDGMENT_API_KEY, JUDGMENT_ORG_ID, OPENAI_API_KEY */} ### Quickstart AI SDK 7 registers telemetry once at startup with `@ai-sdk/otel`. After that, AI SDK calls emit OpenTelemetry spans through the registered integration. 1. #### Install Dependencies **npm** ```bash npm install ai@^7 @ai-sdk/openai@^4 @ai-sdk/otel judgeval zod ``` **yarn** ```bash yarn add ai@^7 @ai-sdk/openai@^4 @ai-sdk/otel judgeval zod ``` **pnpm** ```bash pnpm add ai@^7 @ai-sdk/openai@^4 @ai-sdk/otel judgeval zod ``` **bun** ```bash bun add ai@^7 @ai-sdk/openai@^4 @ai-sdk/otel judgeval zod ``` 2. #### Initialize Tracer Create an instrumentation file that initializes the Judgment tracer and registers AI SDK OpenTelemetry globally: ```typescript title="instrumentation.ts" import { OpenTelemetry } from "@ai-sdk/otel"; import { registerTelemetry } from "ai"; import { Tracer } from "judgeval"; await Tracer.init({ projectName: "AI SDK Weather Agent", }); registerTelemetry( new OpenTelemetry({ tracer: Tracer.getOTELTracer(), }), ); ``` 3. #### Run Your Agent Import the instrumentation file before your AI SDK calls. ```typescript title="weatherAgent.ts" import "./instrumentation"; // [!code ++] import { openai } from "@ai-sdk/openai"; import { generateText, tool } from "ai"; import * as z from "zod/v4"; import { Tracer } from "judgeval"; // [!code ++] async function main() { const result = await generateText({ model: openai("gpt-5.2"), tools: { weather: tool({ description: "Get the weather in a location", inputSchema: z.object({ location: z.string().describe("The location to get the weather for"), }), execute: async ({ location }) => ({ location, temperature: 72 + Math.floor(Math.random() * 21) - 10, }), }), }, prompt: "What is the weather in San Francisco?", }); return result; } await main().catch(console.error); await Tracer.shutdown(); // [!code ++] ``` > **Info** > > If you are using Open Router as your model provider, make sure to enable [OpenRouter Usage Accounting](https://openrouter.ai/docs/use-cases/usage-accounting) to enable cost tracking. ![Vercel AI SDK Trace](/blume-assets/content/docs/images/platform/vercel_ai_sdk_light.png) ### Example: Math Agent with Multi-Step Reasoning Install `mathjs` for this example: **npm** ```bash npm install mathjs ``` **yarn** ```bash yarn add mathjs ``` **pnpm** ```bash pnpm add mathjs ``` **bun** ```bash bun add mathjs ``` ```typescript title="instrumentation.ts" import { OpenTelemetry } from "@ai-sdk/otel"; import { registerTelemetry } from "ai"; import { Tracer } from "judgeval"; await Tracer.init({ projectName: "AI SDK Math Agent", }); registerTelemetry( new OpenTelemetry({ tracer: Tracer.getOTELTracer(), }), ); ``` ```typescript title="mathAgent.ts" import "./instrumentation"; import { openai } from "@ai-sdk/openai"; import { generateText, stepCountIs, tool } from "ai"; import * as mathjs from "mathjs"; import * as z from "zod/v4"; import { Tracer } from "judgeval"; async function main() { return await generateText({ model: openai("gpt-5.2"), tools: { calculate: tool({ description: "A tool for evaluating mathematical expressions. Example expressions: " + "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.", inputSchema: z.object({ expression: z.string() }), execute: async ({ expression }) => mathjs.evaluate(expression), }), }, stopWhen: stepCountIs(10), system: "You are solving math problems. " + "Reason step by step. " + "Use the calculator when necessary. " + "The calculator can only do simple additions, subtractions, multiplications, and divisions. " + "When you give the final answer, provide an explanation for how you got it.", prompt: "A taxi driver earns $9461 per 1-hour work. " + "If he works 12 hours a day and in 1 hour he uses 14-liters petrol with price $134 for 1-liter. " + "How much money does he earn in one day?", }); } await Tracer.observe(main)().catch(console.error); await Tracer.shutdown(); ``` ## AI SDK 6 and older ### Quickstart AI SDK 6 and older enables telemetry on each AI SDK call with `experimental_telemetry`. 1. #### Install Dependencies **npm** ```bash npm install ai @ai-sdk/openai judgeval zod ``` **yarn** ```bash yarn add ai @ai-sdk/openai judgeval zod ``` **pnpm** ```bash pnpm add ai @ai-sdk/openai judgeval zod ``` **bun** ```bash bun add ai @ai-sdk/openai judgeval zod ``` 2. #### Initialize Tracer ```typescript title="instrumentation.ts" import { Tracer } from "judgeval"; await Tracer.init({ projectName: "AI SDK Weather Agent", }); ``` 3. #### Enable Telemetry Enable `experimental_telemetry` and pass the Judgment OpenTelemetry tracer. ```typescript title="weatherAgent.ts" import "./instrumentation"; // [!code ++] import { openai } from "@ai-sdk/openai"; import { generateText, tool } from "ai"; import { z } from "zod"; import { Tracer } from "judgeval"; // [!code ++] async function main() { const result = await generateText({ model: openai("gpt-5.2"), tools: { weather: tool({ description: "Get the weather in a location", inputSchema: z.object({ location: z.string().describe("The location to get the weather for"), }), execute: async ({ location }) => ({ location, temperature: 72 + Math.floor(Math.random() * 21) - 10, }), }), }, experimental_telemetry: { // [!code ++] isEnabled: true, // [!code ++] tracer: Tracer.getOTELTracer(), // [!code ++] }, // [!code ++] prompt: "What is the weather in San Francisco?", }); return result; } await main().catch(console.error); await Tracer.shutdown(); // [!code ++] ``` > **Warning** > > **For Quick Scripts**: The `Tracer.shutdown()` call is essential for short-lived scripts to ensure all traces are exported before the process exits. For long-running servers (e.g., Express, Next.js), this is not necessary as the tracer will export spans continuously throughout the application lifecycle. > > If you need additional time for async operations to complete before shutdown: > > **Node.js / Express:** > > ```typescript > await main().catch(console.error); > await new Promise((resolve) => setTimeout(resolve, 10000)); // Give time for traces to export > await Tracer.shutdown(); > ``` > > **Bun:** > > ```typescript > await main().catch(console.error); > await Bun.sleep(10000); // Give time for traces to export > await Tracer.shutdown(); > ``` ## Next Steps - [Trace conventions](/documentation/reference/trace-conventions) - Understand Judgment's OpenTelemetry boundaries, context, and span semantics. - [Monitor a behavior](/documentation/monitoring) - Monitor your Vercel AI SDK agents in production with behavioral scoring. - [Instrument your agent](/documentation/tracing/instrumentation) - Configure and verify Judgment tracing beyond this integration.