Debugging Vercel AI SDK Step-by-Step

Learn how to debug Vercel AI SDK workflows in production. Add full observability to generateText, streamText, and tool calls with tracepilot-vercel.

Debugging Vercel AI SDK workflows in production is painful. console.log disappears into serverless cold starts. Streaming responses have no visibility past the first token. Tool calls fail silently. npm install tracepilot-vercel gives you structured traces, replay, and full span visibility — in under five minutes.

Why traditional logs fail for Vercel AI SDK

Serverless functions on Vercel have hard limits that make conventional debugging brittle:

Problem	What you see	What you need
Cold start truncation	First log entry missing	Full execution timeline
Streaming black box	No visibility mid-stream	Per-token span capture
Silent tool failures	No error, no output	Structured error spans
Retry loops	Duplicate output, rising cost	Loop detection + replay
No request correlation	Logs scattered across invocations	Single trace per agent run

TracePilot solves all of these by wrapping your AI SDK calls and shipping structured spans to a persistent dashboard — even across serverless boundaries.

Real-world debugging scenario

You ship a RAG pipeline using generateText with two tool calls. It works in staging. In production, 12% of requests return empty outputs. No errors in Vercel logs.

With TracePilot, you open the dashboard, filter for failed traces, and immediately see:

• Span 1 (generateText) completed in 1.2s ✓
• Span 2 (fetchDocument) timed out at 3.0s ✗
• Span 3 (generateText) never fired — skipped due to empty tool output

One dashboard view. No log archaeology.

Installation

npm install tracepilot-vercel

yarn

yarn add tracepilot-vercel

Environment variables

.env.local

TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx

Never commit your API key. Use .env.local for local development and Vercel environment variables for production deployments.

Instrumenting generateText()

Wrap your generateText call with TracePilot. Your existing code stays unchanged — the wrapper captures input, output, token usage, and latency as a span.

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { TracePilotVercel } from 'tracepilot-vercel';

const tp = new TracePilotVercel(process.env.TRACEPILOT_API_KEY!);

export async function POST(req: Request) {
  const { prompt } = await req.json();

  await tp.startTrace('rag-pipeline');

  const { spanId, result } = await tp.wrapGenerate(
    () => generateText({
      model: openai('gpt-4o'),
      prompt,
    }),
    { prompt },
    undefined, // no parent span — this is the root
    1
  );

  return Response.json({ text: result.text });
}

Instrumenting streamText()

Streaming is where most Vercel AI SDK debugging tools fall short. TracePilot captures the full stream — start time, first token latency, full output, and any mid-stream errors.

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { TracePilotVercel } from 'tracepilot-vercel';
import { StreamingTextResponse } from 'ai';

const tp = new TracePilotVercel(process.env.TRACEPILOT_API_KEY!);

export async function POST(req: Request) {
  const { messages } = await req.json();

  await tp.startTrace('streaming-chat');

  const { stream, spanId } = await tp.wrapStream(
    () => streamText({
      model: openai('gpt-4o'),
      messages,
    }),
    messages,
    undefined,
    1
  );

  // Stream goes to the client. TracePilot captures it in the background.
  return new StreamingTextResponse(stream);
}

wrapStream does not buffer the stream. It taps it transparently — your time-to-first-token is unaffected.

Wrapper instrumentation for multi-tool pipelines

Chain spans with parentSpanId to build a full execution tree across multiple generateText and tool calls.

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { TracePilotVercel } from 'tracepilot-vercel';
import { z } from 'zod';

const tp = new TracePilotVercel(process.env.TRACEPILOT_API_KEY!);

export async function runPipeline(userQuery: string) {
  await tp.startTrace('research-pipeline');

  // Step 1 — planning
  const { result: plan, spanId: planSpanId } = await tp.wrapGenerate(
    () => generateText({
      model: openai('gpt-4o'),
      prompt: `Plan a research strategy for: ${userQuery}`,
    }),
    { prompt: userQuery },
    undefined,
    1
  );

  // Step 2 — document fetch (tool call)
  const { result: docs, spanId: fetchSpanId } = await tp.wrapToolCall(
    'fetch-documents',
    () => fetchRelevantDocuments(plan.text),
    planSpanId,  // child of the planning span
    2
  );

  // Step 3 — synthesis
  const { result: answer } = await tp.wrapGenerate(
    () => generateText({
      model: openai('gpt-4o'),
      prompt: `Answer "${userQuery}" using: ${docs.join('\n')}`,
    }),
    { context: docs },
    fetchSpanId, // child of the fetch span
    3
  );

  return answer.text;
}

The dashboard renders this as a three-level tree: Plan → Fetch → Answer. If Fetch fails, the failure is isolated immediately.

Replay AI execution

Once a trace is captured, you can fork any span and re-run it with modified inputs — directly from the dashboard. No redeployment. No code changes.

How to replay a failing Vercel AI SDK span:

1. Open the trace

   Go to tracepilotai.com/dashboard and find the failing trace. Traces are sorted by recency and filterable by status.

2. Select the failing span

   Click into the span where the failure occurred. You’ll see the exact input messages, model parameters, token count, and error output.

3. Fork & Rerun

   Click Fork & Rerun. Edit the prompt, adjust the model, or change tool parameters. Hit Run — TracePilot re-executes the span and shows you the new output side-by-side.

4. Deploy the fix

   Once you’ve confirmed the fix works in replay, apply the change to your codebase and ship.

Vercel AI SDK observability checklist

generateText not capturing output

Make sure you’re passing the result of tp.wrapGenerate() and not calling generateText() directly. The wrapper must intercept the call to record the span.

streamText span shows no output

wrapStream captures the full stream asynchronously. If the trace shows an empty output, the stream may have been consumed before TracePilot could read it. Ensure you’re passing the wrapped stream to StreamingTextResponse, not the raw one.

Spans not appearing in dashboard

Verify TRACEPILOT_API_KEY is set in your Vercel project environment variables — not just in .env.local. Local env files are not deployed.

Serverless function timeout before trace ships

TracePilot batches and ships spans before the function returns. If your function hits the Vercel timeout limit (default 10s), increase it in vercel.json or use Edge Runtime.

Next steps

Quickstart: tracepilot-vercel

Go from install to live trace in under 5 minutes.

Time-travel debugging

Learn the full Fork & Rerun flow for fixing broken spans.

Multi-step agents

Build nested span trees across complex pipelines.

Cost tracking

Monitor token spend per span across all your AI SDK calls.