Skip to main content
Braintrust integrates with Vercel in two ways: trace calls from the Vercel AI SDK in your application, or collect traces through the Vercel Marketplace integration.

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.
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.
1

Initialize Braintrust and call the AI SDK

trace-vercel-ai-sdk-auto.js
2

Run with the import hook

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 and run the compiled file with the import hook, or run TypeScript directly with a TypeScript loader.
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

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
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.For experimental_evaluate() calls, use wrapAISDK() or the import hook with Braintrust v3.34.0+ and AI SDK v7.0.103 or later within v7. With Braintrust v3.38.0+, wrapAISDK() also wraps experimental_decide() (AI SDK v7.0.128 or later), and braintrustAISDKTelemetry() traces decision calls through the telemetry callbacks that AI SDK v7.0.111 and later emit. These calls produce evaluate spans with type question, which the trace view labels as Decision spans. Inline images and files in decision inputs are captured as attachments when BRAINTRUST_CAPTURE_ATTACHMENTS is enabled, and recorded as <omitted> otherwise. See Trace TypeSafe Jev with AI SDK.

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

OpenTelemetry

The Vercel AI SDK natively supports OpenTelemetry and works out of the box with Braintrust, either via Next.js or Node.js.

Next.js

If you are using Next.js, use the Braintrust exporter with @vercel/otel:
Traced LLM calls will appear under the Braintrust project or experiment provided in the parent field.When you call the AI SDK, make sure to set experimental_telemetry:
The integration supports streaming functions like streamText. Each streamed call will produce ai.streamText spans in Braintrust.

Node.js

If you are using Node.js without a framework, you must configure the NodeSDK directly. Here, it’s more straightforward to use the BraintrustSpanProcessor.First, install the necessary dependencies:
Then, set up the OpenTelemetry SDK:

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

Stream tool responses

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

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
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 setup 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, HarnessAgent) 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

Trace batch requests

To trace text batches you submit with the AI SDK’s experimental batch API, use Braintrust v3.39.0+ with AI SDK v7.0.108 or later within v7, and record them yourself with startAISDKBatchTrace() and completeAISDKBatchTrace(). The import hook and wrapAISDK don’t trace the batch functions, and these two functions don’t call the provider. Call startAISDKBatchTrace() after you submit the batch, and store the context string it returns with the batch reference and the original requests. After you collect the results, pass them to completeAISDKBatchTrace(), which can run in another process.
TypeScript
completeAISDKBatchTrace() accepts only results you’ve already collected into an array. It leaves the spans open while the batch is pending, or when a completed batch is missing results. For a failed batch, it records the batch error on requests that have no result. Pass the same requests you passed to startAISDKBatchTrace(). If their IDs or models don’t match the context, nothing is recorded. Calling it again with the same context and results updates the same spans. Without a context, it records the inputs and results together under the current span, or as a new trace if there’s no current span. Each request needs a unique id, a model, and type: "text".

Trace code mode

Braintrust v3.39.0+ traces experimental_runCodeMode() calls from @ai-sdk/code-mode v1.0.100 or later (below v2.0.0). With the import hook, calls are traced with no code changes, including calls made by tools from experimental_createCodeModeTool() and experimental_codeModeTool(). Without the hook, wrap the code mode module with wrapAISDK. The wrapper traces calls you make to experimental_runCodeMode() directly, but not calls made inside tools from experimental_createCodeModeTool() or experimental_codeModeTool(). braintrustAISDKTelemetry() alone doesn’t trace code mode.
TypeScript
Each run produces a codeMode tool span with the JavaScript source as input and the return value as output. Each tool the code calls gets a child span named after the tool. When the run happens inside an AI SDK tool call that’s already traced, the tool calls nest under that tool’s span instead of a separate codeMode span.

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.
  • Image generation spans (generateImage), with image prompt as input, generated images stored as Braintrust attachments, and model and provider metadata.
  • Tool execution spans (<tool name>), with tool inputs, outputs, and errors. For a tool that defines toModelOutput, the output is the value the model receives, both on the tool span and in the parent span’s tool results.
  • Batch spans (ai.batch), with batch ID, provider, status, and request counts, when you record batches with startAISDKBatchTrace() and completeAISDKBatchTrace(). Each request gets a child ai.batch.request span with its messages, model settings, output, finish reason, token metrics, and status.
  • Code mode spans (codeMode), with the JavaScript source as input, the return value as output, and child spans for each tool the code calls.
  • Agent spans (Agent.generate, Agent.stream, ToolLoopAgent.generate, ToolLoopAgent.stream, WorkflowAgent.stream, HarnessAgent.generate, and HarnessAgent.stream), with agent inputs, outputs, model-call child spans, and time-to-first-token for streaming agent calls.

Vercel AI SDK tracing resources

Vercel Marketplace tracing

The Vercel Marketplace integration collects traces for AI calls in your Vercel applications with minimal setup. No package installation required.

Setup

Set up the marketplace integration by installing it from Vercel, linking Braintrust, choosing a plan, and adding a drain.
1

Install the integration

Visit the Vercel Marketplace listing and select Install.
2

Create or link your account

Create a Braintrust account or link your existing account.
3

Select a plan and project

Select a plan and create a project name:
  • Starter: Free with basic limits.
  • Starter (pay-as-you-go): No monthly fee, but charges for usage beyond the free tier. Requires a payment method.
  • Pro: Higher limits with a monthly fee.
See Plans and limits for a full comparison.
4

Add a drain

Select Add Drain to configure trace collection.

Configure log drain

Choose which trace data Vercel sends to Braintrust and which projects the drain covers.
1

Select trace data

In the Add Drain panel, select Traces and Next.
2

Choose projects

Choose which Vercel projects to trace (All Projects or specific projects).
3

Set sampling

Set the sampling rate for trace collection.

Enable OpenTelemetry

In your Next.js project, create an instrumentation.ts file and call registerOtel to emit traces to the marketplace drain.

Vercel Marketplace resources