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

# Quickstart: tracepilot-vercel

> Instrument Vercel AI SDK with full observability in under 5 minutes. Trace generateText, streamText, and tool calls — then replay failures from the dashboard.

Go from install to live trace in under 5 minutes. This guide covers everything you need to add TracePilot observability to a Vercel AI SDK project.

## Prerequisites

* A Next.js or Node.js project using the Vercel AI SDK (`ai` package)
* An OpenAI API key (or any AI SDK-compatible provider)
* Node.js 18+

## 1. Install

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

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

  ```bash pnpm theme={null}
  pnpm add tracepilot-vercel
  ```
</CodeGroup>

## 2. Add your API key

Get your key from [tracepilotai.com](https://tracepilotai.com) → Account Settings. It looks like `tp_live_xxxxxxxxxxxxxxxx`.

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

For production, add this in your **Vercel project settings → Environment Variables**. Never commit it to source control.

## 3. Initialize

Create a single TracePilot instance and reuse it across your app.

```typescript lib/tracepilot.ts theme={null}
import { TracePilotVercel } from 'tracepilot-vercel';

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

## 4. Trace `generateText`

```typescript app/api/generate/route.ts theme={null}
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { tp } from '@/lib/tracepilot';

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

  await tp.startTrace('generate-route');

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

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

## 5. Trace `streamText`

```typescript app/api/chat/route.ts theme={null}
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { StreamingTextResponse } from 'ai';
import { tp } from '@/lib/tracepilot';

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

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

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

  // Stream is returned to the client unchanged.
  // TracePilot captures it in the background.
  return new StreamingTextResponse(stream);
}
```

<Note>
  `wrapStream` does not buffer or delay the stream. Time-to-first-token is unaffected.
</Note>

## Expected trace output

After running your app, open [tracepilotai.com/dashboard](https://tracepilotai.com/dashboard). You should see:

```text theme={null}
└─ generate-route                        [trace]
   └─ Span 1 — generateText               1.2s  ✓
         model: gpt-4o
         prompt_tokens: 48
         completion_tokens: 120
         cost: $0.0018
```

For streaming:

```text theme={null}
└─ chat-route                            [trace]
   └─ Span 1 — streamText                 0.8s ✓
         model: gpt-4o
         first_token_latency: 230ms
         prompt_tokens: 112
         completion_tokens: 88
```

<Tip>
  Screenshot pending: Live trace in the TracePilot dashboard after a streamText call.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Trace not appearing in dashboard">
    * Confirm `TRACEPILOT_API_KEY` is set. Run `console.log(process.env.TRACEPILOT_API_KEY)` to verify it's loaded.
    * Make sure `tp.startTrace()` is called **before** any `wrapGenerate` or `wrapStream` call.
    * Check that you're not using `.env` instead of `.env.local` for local dev.
  </Accordion>

  <Accordion title="streamText span shows empty output">
    Pass the wrapped `stream` (returned by `tp.wrapStream`) to `StreamingTextResponse` — not the raw result from `streamText`. TracePilot reads from the stream tap; passing the raw stream skips the instrumentation.
  </Accordion>

  <Accordion title="TypeError: Cannot read properties of undefined (reading 'startTrace')">
    The `TracePilotVercel` instance is `undefined`. This usually means `TRACEPILOT_API_KEY` is not set. The constructor receives `undefined` and throws lazily. Add a startup assertion:

    ```typescript theme={null}
    if (!process.env.TRACEPILOT_API_KEY) throw new Error('TRACEPILOT_API_KEY is not set');
    ```
  </Accordion>

  <Accordion title="Spans appear in dashboard but no cost data">
    Cost tracking requires the model name to be recognized. Ensure you're passing a standard OpenAI model string (`gpt-4o`, `gpt-4o-mini`, etc.). Custom fine-tuned model names are not mapped automatically.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Debugging Vercel AI SDK" icon="bug" href="/guides/debugging-vercel-ai-sdk">
    Step-by-step guide to debugging generateText, streamText, and tool calls in production.
  </Card>

  <Card title="Multi-step agents" icon="diagram-project" href="/guides/multi-step-agents">
    Chain spans with parentSpanId to trace complex pipelines.
  </Card>

  <Card title="Time-travel debugging" icon="clock-rotate-left" href="/concepts/time-travel-debugging">
    Fork any failing span and replay it without redeploying.
  </Card>

  <Card title="Cost tracking" icon="circle-dollar-to-slot" href="/concepts/cost-tracking">
    Monitor token spend across every AI SDK call.
  </Card>
</CardGroup>