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

> Add full observability to your OpenAI agents in under 5 minutes. Trace every completion call, tool invocation, and token spent — then replay failures from the dashboard.

Go from install to live trace in under 5 minutes. This guide gets your OpenAI agent fully instrumented with structured spans, cost tracking, and one-click replay.

## Prerequisites

* A Node.js or TypeScript project using the OpenAI SDK
* An OpenAI API key
* Node.js 18+

## 1. Install

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

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

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

## 2. Add your API key

Get your key from [tracepilotai.com](https://tracepilotai.com) → Account Settings.

```bash .env theme={null}
TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-...
```

<Warning>
  Never commit API keys. Use environment variables. In production, inject them via your platform's secret manager.
</Warning>

## 3. Initialize the OpenAI client

```typescript lib/clients.ts theme={null}
import OpenAI from 'openai';
import { TracePilotOpenAI } from 'tracepilot-openai';

export const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
export const tp = new TracePilotOpenAI(process.env.TRACEPILOT_API_KEY!);
```

Instantiate once. Import everywhere.

## 4. Wrap your first completion

```typescript agent.ts theme={null}
import { openai, tp } from './lib/clients';

async function runAgent(userMessage: string) {
  await tp.startTrace('my-agent');

  const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: userMessage },
  ];

  const { result, spanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({
      model: 'gpt-4o',
      messages,
    }),
    messages,
    undefined, // root span — no parent
    1
  );

  console.log(result.choices[0].message.content);
  // → Open your dashboard. The trace is already there.
}

runAgent('Summarise the latest AI research.');
```

Your existing code is unchanged. `tp.wrapOpenAI` returns the original `result` untouched — plus a `spanId` for chaining.

## 5. Trace a multi-step agent

```typescript agent.ts theme={null}
import { openai, tp } from './lib/clients';

async function runResearchAgent(query: string) {
  await tp.startTrace('research-agent');

  const messages = [{ role: 'user', content: query }];

  // Step 1 — planning
  const { result: plan, spanId: planSpanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o', messages }),
    messages,
    undefined,
    1
  );

  // Step 2 — web search tool call
  const { result: searchResult, spanId: searchSpanId } = await tp.wrapToolCall(
    'web-search',
    () => webSearch(plan.choices[0].message.content ?? ''),
    planSpanId, // child of the planning span
    2
  );

  // Step 3 — synthesis
  const followUp = [
    ...messages,
    plan.choices[0].message,
    { role: 'tool', content: searchResult.summary },
  ];

  const { result: answer } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o', messages: followUp }),
    followUp,
    searchSpanId, // child of the search span
    3
  );

  return answer.choices[0].message.content;
}
```

## Expected dashboard output

After running your agent, open [tracepilotai.com/dashboard](https://tracepilotai.com/dashboard):

```text theme={null}
└─ research-agent                         [trace]
   ├─ Span 1 — gpt-4o (planning)          0.9s  ✓  48 tokens  $0.00072
   │   ├─ Span 2 — web-search             0.3s  ✓
   │       └─ Span 3 — gpt-4o (answer)    1.1s  ✓  210 tokens  $0.0031
```

Every span shows: model, latency, token count, estimated cost, input messages, and output. If any span fails, it shows the error inline.

<Tip>
  Screenshot pending: TracePilot dashboard showing a 3-step OpenAI agent trace.
</Tip>

## 6. Replay a failing span

When a span fails in production, you don't need to redeploy to debug it.

<Steps>
  <Step title="Find the failing trace">
    Go to [tracepilotai.com/dashboard](https://tracepilotai.com/dashboard). Failed traces are marked with a red ✗. Click the trace.
  </Step>

  <Step title="Open the failing span">
    Expand the span tree and click the span where the failure occurred. You’ll see the exact `messages` array, model parameters, token usage, and error output.
  </Step>

  <Step title="Fork & Rerun">
    Click **Fork & Rerun**. Edit the prompt, swap the model, or adjust parameters. Click **Run**.
  </Step>

  <Step title="Ship the fix">
    Once the replay succeeds, apply the same change to your codebase and deploy.
  </Step>
</Steps>

```typescript Replay example — what TracePilot captures per span theme={null}
// TracePilot records this automatically for every wrapOpenAI call:
{
  spanId: 'span_abc123',
  model: 'gpt-4o',
  messages: [ /* exact input */ ],
  output: { /* full ChatCompletion */ },
  usage: {
    prompt_tokens: 48,
    completion_tokens: 120,
    estimated_cost_usd: 0.0018
  },
  latency_ms: 1240,
  error: null
}
// Fork & Rerun lets you edit `messages` and re-execute from this exact state.
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Trace not showing in dashboard">
    * Confirm `TRACEPILOT_API_KEY` starts with `tp_live_`.
    * `tp.startTrace()` must be called before any `wrapOpenAI` call in the same execution.
    * Check your network: TracePilot ships spans over HTTPS to `ingest.tracepilotai.com`. Ensure it's not blocked by a firewall or proxy.
  </Accordion>

  <Accordion title="spanId is undefined">
    `tp.wrapOpenAI()` always returns a `spanId`. If it's `undefined`, the call threw before TracePilot could create the span. Check for initialization errors — missing API key is the most common cause.
  </Accordion>

  <Accordion title="Tool call spans not appearing">
    Make sure `tp.wrapToolCall` receives the `parentSpanId` from the preceding `wrapOpenAI` call. A missing `parentSpanId` creates an orphaned span that may not render in the tree view.
  </Accordion>

  <Accordion title="Cost shows $0.00 for all spans">
    Cost tracking is based on the model string. Pass the exact OpenAI model name (`gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`). Custom or fine-tuned model IDs are not mapped automatically.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Debug OpenAI agent infinite loops" icon="bug" href="/guides/debug-openai-agent-infinite-loops">
    Detect, trace, and replay runaway agent loops before they drain your budget.
  </Card>

  <Card title="Tracing tool calls" icon="wrench" href="/guides/tracing-tool-calls">
    Instrument every tool, function, and external API your agent calls.
  </Card>

  <Card title="Time-travel debugging" icon="clock-rotate-left" href="/concepts/time-travel-debugging">
    Fork any span and rerun it with edited inputs — no redeployment.
  </Card>

  <Card title="Cost tracking" icon="circle-dollar-to-slot" href="/concepts/cost-tracking">
    Monitor token spend per span and catch runaway costs early.
  </Card>
</CardGroup>