> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vercel
> Trace Vercel AI SDK calls and collect Vercel Marketplace traces in Braintrust
If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.
Braintrust integrates with [Vercel](https://vercel.com) 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](https://sdk.vercel.ai/docs/ai-sdk-core) 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.
```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add braintrust ai zod
```
```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.
```javascript title="trace-vercel-ai-sdk-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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);
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/instrument/trace-llm-calls#auto-instrumentation) 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.
```javascript title="next.config.mjs" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.
```typescript title="trace-vercel-ai-sdk-v7.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.
```typescript title="trace-vercel-ai-sdk.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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);
```
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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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,
},
},
});
```
To trace streaming tool responses, pass your tools to `streamText`. Braintrust creates `doStream` child spans for streaming LLM calls.
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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);
}
```
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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/integrations/sdk-integrations/opentelemetry#vercel-ai-sdk) for details.
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`) 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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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?",
});
```
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](/instrument/advanced-tracing#flush-logs-manually) 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** (``), with tool inputs, outputs, and errors.
* **Agent spans** (`Agent.generate`, `Agent.stream`, `ToolLoopAgent.generate`, and `ToolLoopAgent.stream`), with agent inputs, outputs, model-call child spans, and time-to-first-token for streaming agent calls.
Vercel AI SDK tracing resources
* [Vercel AI SDK documentation](https://sdk.vercel.ai/docs)
* [Braintrust TypeScript SDK reference](/sdks/typescript/versions/latest)
* [Braintrust package on npm](https://www.npmjs.com/package/braintrust)
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.
Visit the [Vercel Marketplace listing](https://vercel.com/integrations/braintrust) and select **Install**.
Create a Braintrust account or link your existing account.
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](/plans-and-limits) for a full comparison.
Select **Add Drain** to configure trace collection.
Choose which trace data Vercel sends to Braintrust and which projects the drain covers.
In the **Add Drain** panel, select **Traces** and **Next**.
Choose which Vercel projects to trace (**All Projects** or specific projects).
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
* [Vercel Marketplace integration](https://vercel.com/integrations/braintrust)
* [Vercel OpenTelemetry docs](https://vercel.com/docs/otel)