> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracepilotai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npm install tracepilot-vercel
```

```bash yarn theme={null}
yarn add tracepilot-vercel
```

## Environment variables

```bash .env.local theme={null}
TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx
```

<Warning>
  Never commit your API key. Use `.env.local` for local development and Vercel environment variables for production deployments.
</Warning>

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

```typescript theme={null}
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.

```typescript theme={null}
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);
}
```

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

## Wrapper instrumentation for multi-tool pipelines

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

```typescript theme={null}
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:**

<Steps>
  <Step title="Open the trace">
    Go to [tracepilotai.com/dashboard](https://tracepilotai.com/dashboard) and find the failing trace. Traces are sorted by recency and filterable by status.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Deploy the fix">
    Once you've confirmed the fix works in replay, apply the change to your codebase and ship.
  </Step>
</Steps>

<Tip>
  Screenshot pending: TracePilot dashboard showing a forked Vercel AI SDK trace with side-by-side comparison.
</Tip>

## Vercel AI SDK observability checklist

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart: tracepilot-vercel" icon="bolt" href="/quickstart-vercel">
    Go from install to live trace in under 5 minutes.
  </Card>

  <Card title="Time-travel debugging" icon="clock-rotate-left" href="/concepts/time-travel-debugging">
    Learn the full Fork & Rerun flow for fixing broken spans.
  </Card>

  <Card title="Multi-step agents" icon="diagram-project" href="/guides/multi-step-agents">
    Build nested span trees across complex pipelines.
  </Card>

  <Card title="Cost tracking" icon="circle-dollar-to-slot" href="/concepts/cost-tracking">
    Monitor token spend per span across all your AI SDK calls.
  </Card>
</CardGroup>