Vercel

Vercel AI SDK tracing

Braintrust traces Vercel AI SDK text generation, object generation, embeddings, reranking, streaming, tool calls, and agent calls from the Vercel AI SDK.

Setup

Install the Braintrust SDK alongside the Vercel AI SDK. The Braintrust SDK supports Vercel AI SDK v3, v4, v5, v6, and v7.

pnpm add braintrust ai zod

npm install braintrust ai zod

Starting with Braintrust SDK v2.0.0, zod is a peer dependency and must be installed separately when using the Vercel AI SDK integration.

Auto-instrumentation

To trace Vercel AI SDK calls without wrapping individual functions, initialize Braintrust normally, then run your app with Braintrust’s import hook. The hook patches AI SDK calls at runtime, including AI SDK v7 telemetry dispatchers.

Initialize Braintrust and call the AI SDK

trace-vercel-ai-sdk-auto.js

import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My AI Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

async function main() {
  const { text } = await generateText({
    model: openai("gpt-5-mini"),
    prompt: "What is the capital of France?",
  });
  console.log(text);
}

main().catch(console.error);

Run with the import hook

node --import braintrust/hook.mjs trace-vercel-ai-sdk-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

For Next.js apps, wrap your Next.js config with wrapNextjsConfigWithBraintrust instead of using the Node.js import hook directly. Braintrust uses the wrapper to apply the right instrumentation for the active Next.js build, including webpack and Turbopack builds.

next.config.mjs

import { wrapNextjsConfigWithBraintrust } from "braintrust/next";

const nextConfig = {};

export default wrapNextjsConfigWithBraintrust(nextConfig);

Manual instrumentation (telemetry registration)

For AI SDK v7, call ai.registerTelemetry(braintrustAISDKTelemetry()) once at startup before making AI SDK calls. Use this path when you cannot run with the import hook or need to instrument a specific call path yourself.

trace-vercel-ai-sdk-v7.ts

import * as ai from "ai";
import { openai } from "@ai-sdk/openai";
import { braintrustAISDKTelemetry, initLogger } from "braintrust";

initLogger({
  projectName: "My AI Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

ai.registerTelemetry(braintrustAISDKTelemetry());

async function main() {
  const { text } = await ai.generateText({
    model: openai("gpt-5-mini"),
    prompt: "What is the capital of France?",
  });
  console.log(text);
}

main().catch(console.error);

For AI SDK v7, define tool schemas with inputSchema. Braintrust traces requests, streams, and tool calls, but provider-level cache metrics and deny-output overrides from the earlier provider-wrapping integration are not available through v7 telemetry.

Manual instrumentation (wrap functions)

For AI SDK v3 to v6, use wrapAISDK to wrap the Vercel AI SDK functions when you cannot run with the import hook or need to instrument a specific call path yourself.

trace-vercel-ai-sdk.ts

import { initLogger, wrapAISDK } from "braintrust";
import * as ai from "ai";
import { openai } from "@ai-sdk/openai";

initLogger({
  projectName: "My AI Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const { generateText } = wrapAISDK(ai);

async function main() {
  // This will automatically log the request, response, and metrics to Braintrust
  const { text } = await generateText({
    model: openai("gpt-5-mini"),
    prompt: "What is the capital of France?",
  });
  console.log(text);
}

main().catch(console.error);

Trace tool calls

To trace tool calls, add tools to the same instrumented generateText call from the setup above. Braintrust records the tool definitions in span metadata and traces tool execution as child spans.

TypeScript

const { text } = await generateText({
  model: openai("gpt-5-mini"),
  prompt: "What is 127 multiplied by 49?",
  tools: {
    multiply: {
      description: "Multiply two numbers",
      inputSchema: z.object({
        a: z.number(),
        b: z.number(),
      }),
      execute: async ({ a, b }: { a: number; b: number }) => a * b,
    },
  },
});

Stream tool responses

To trace streaming tool responses, pass your tools to streamText. Braintrust creates doStream child spans for streaming LLM calls.

TypeScript

const tools = {
  multiply: {
    description: "Multiply two numbers",
    inputSchema: z.object({
      a: z.number(),
      b: z.number(),
    }),
    execute: async ({ a, b }: { a: number; b: number }) => a * b,
  },
};

const result = streamText({
  model: openai("gpt-5-mini"),
  prompt: "What is 127 multiplied by 49?",
  tools,
});

for await (const delta of result.textStream) {
  process.stdout.write(delta);
}

Add metadata

To attach custom metadata to your AI SDK traces, wrap your AI calls in a parent span using traced. Auto-instrumentation and wrapAISDK create child spans for AI SDK calls, and you attach your metadata to the parent span.

TypeScript

return traced(
  async (span) => {
    const { text } = await generateText({
      model: openai("gpt-5-mini"),
      prompt,
    });

    span.log({
      input: prompt,
      output: text,
      metadata: {
        userId,
        userTier,
      },
    });

    return text;
  },
  { name: "generate-with-context", type: "function" }
);

This creates a span hierarchy where your parent span contains the metadata, and the AI SDK call appears as a child span with its own metrics and details.This approach is useful when you need to:

Add custom metadata like user IDs, session IDs, or feature flags.
Compute metadata based on async operations, such as fetching user context.
Add metadata conditionally based on the response.
Group multiple AI calls under a single parent span with shared metadata.

If you’re using the Vercel AI SDK with OpenTelemetry (not wrapAISDK), you can use the native experimental_telemetry.metadata parameter instead. See the OpenTelemetry integration guide for details.

Multi-round tool interactions

When using tools, the AI SDK often makes multiple LLM calls to complete the task. Braintrust automatically creates nested spans to give you visibility into each step:

Parent span: generateText, streamText, generateObject, or streamObject represents the overall operation.
Child spans: doGenerate or doStream represent each individual LLM call during the operation.
Tool spans: Tool executions appear as separate spans showing inputs and outputs.

This nested structure helps you understand:

How many LLM calls were needed to complete the task
What each LLM call received and returned
The complete flow of tool calls and responses

For example, a generateText call that uses tools might produce this span hierarchy:

generateText (parent)
- doGenerate (first LLM call, decides to use tool)
- multiply (tool execution)
- doGenerate (second LLM call, uses tool result to form response)

Trace agents

The AI SDK’s Agent classes (Agent, Experimental_Agent, ToolLoopAgent, and WorkflowAgent) are automatically traced when you run with the import hook. They are also wrapped and traced when using wrapAISDK.

When using AI SDK v5 or v6, individual tool calls within agentic loops are captured as separate child spans with span_type: "function", giving you full visibility into which tools were called, in what order, and with what inputs and outputs. This granular tool call tracing is specific to AI SDK v5 and v6 and is not available in v3 or v4.

TypeScript

const { Experimental_Agent: Agent } = wrapAISDK(ai);

const agent = new Agent({
  model: openai("gpt-5-mini"),
  system: "You are a helpful assistant.",
});

const result = await agent.generate({
  prompt: "What is the capital of France?",
});

Configure for serverless

Braintrust automatically uses Vercel’s waitUntil functionality when available, allowing you to use asyncFlush: true (the default) without blocking requests.The SDK automatically detects Vercel’s environment and uses waitUntil to flush logs in the background. No special configuration is needed for Vercel deployments; use initLogger as shown in the examples above.

If you’re using a serverless environment without waitUntil support (like AWS Lambda), set asyncFlush: false to ensure logs are flushed before the function terminates. See Advanced tracing patterns for more details.

What Braintrust traces

Braintrust captures the main AI SDK operation, provider calls, and nested tool or agent work as a span hierarchy:

AI SDK operation spans (generateText, streamText, generateObject, and streamObject), with prompt-like inputs, final outputs, provider and model metadata, and operation metadata.
Provider call spans (doGenerate and doStream), with model-call inputs, provider outputs, token metrics, and time-to-first-token for streaming calls.
Embedding spans (embed, embedMany, and doEmbed), with input values, embedding counts or dimensions, and token metrics when the provider reports them.
Rerank spans (rerank and doRerank), with query, documents, top-N metadata, and ranked outputs.
Tool execution spans (<tool name>), with tool inputs, outputs, and errors.
Agent spans (Agent.generate, Agent.stream, ToolLoopAgent.generate, ToolLoopAgent.stream, and WorkflowAgent.stream), with agent inputs, outputs, model-call child spans, and time-to-first-token for streaming agent calls.

AI providers

SDKs

Developer tools

Vercel AI SDK tracing

Setup

Auto-instrumentation

Manual instrumentation (telemetry registration)

Manual instrumentation (wrap functions)

Trace tool calls

Stream tool responses

Add metadata

Multi-round tool interactions

Trace agents

Configure for serverless

What Braintrust traces

Vercel AI SDK tracing resources

Vercel Marketplace tracing

Setup

Configure log drain

Enable OpenTelemetry

Vercel Marketplace resources

​Vercel AI SDK tracing

​Setup

​Auto-instrumentation

​Manual instrumentation (telemetry registration)

​Manual instrumentation (wrap functions)

​Trace tool calls

​Stream tool responses

​Add metadata

​Multi-round tool interactions

​Trace agents

​Configure for serverless

​What Braintrust traces

​Vercel AI SDK tracing resources

​Vercel Marketplace tracing

​Setup

​Configure log drain

​Enable OpenTelemetry

​Vercel Marketplace resources

Vercel AI SDK tracing

Setup

Auto-instrumentation

Manual instrumentation (telemetry registration)

Manual instrumentation (wrap functions)

Trace tool calls

Stream tool responses

Add metadata

Multi-round tool interactions

Trace agents

Configure for serverless

What Braintrust traces

Vercel AI SDK tracing resources

Vercel Marketplace tracing

Setup

Configure log drain

Enable OpenTelemetry

Vercel Marketplace resources