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
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.
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, callai.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, usewrapAISDK 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: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 theNodeSDK directly. Here, it’s more straightforward
to use the BraintrustSpanProcessor.First, install the necessary dependencies:Trace tool calls
To trace tool calls, add tools to the same instrumentedgenerateText 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 tostreamText. 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 usingtraced. Auto-instrumentation and wrapAISDK create child spans for AI SDK calls, and you attach your metadata to the parent span.TypeScript
- 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, orstreamObjectrepresents the overall operation. - Child spans:
doGenerateordoStreamrepresent each individual LLM call during the operation. - Tool spans: Tool executions appear as separate spans showing inputs and outputs.
- 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
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 withstartAISDKBatchTrace() 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+ tracesexperimental_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
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’swaitUntil 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, andstreamObject), with prompt-like inputs, final outputs, provider and model metadata, and operation metadata. - Provider call spans (
doGenerateanddoStream), with model-call inputs, provider outputs, token metrics, and time-to-first-token for streaming calls. - Embedding spans (
embed,embedMany, anddoEmbed), with input values, embedding counts or dimensions, and token metrics when the provider reports them. - Rerank spans (
rerankanddoRerank), 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 definestoModelOutput, 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 withstartAISDKBatchTrace()andcompleteAISDKBatchTrace(). Each request gets a childai.batch.requestspan 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, andHarnessAgent.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.
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 aninstrumentation.ts file and call registerOtel to emit traces to the marketplace drain.