Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tracepilot.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

npm install tracepilot-openai

​
2. Add your API key

Get your key from tracepilotai.com → Account Settings.
.env
TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-...
Never commit API keys. Use environment variables. In production, inject them via your platform’s secret manager.

​
3. Initialize the OpenAI client

lib/clients.ts
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

agent.ts
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

agent.ts
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: 
└─ 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.
TracePilot OpenAI agent trace dashboard screenshot placeholder

​
6. Replay a failing span

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

Find the failing trace

Go to tracepilotai.com/dashboard. Failed traces are marked with a red ✗. Click the trace.
2

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

Fork & Rerun

Click Fork & Rerun. Edit the prompt, swap the model, or adjust parameters. Click Run.
4

Ship the fix

Once the replay succeeds, apply the same change to your codebase and deploy.
Replay example — what TracePilot captures per span
// 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

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

​
Next steps

Debug OpenAI agent infinite loops

Detect, trace, and replay runaway agent loops before they drain your budget.

Tracing tool calls

Instrument every tool, function, and external API your agent calls.

Time-travel debugging

Fork any span and rerun it with edited inputs — no redeployment.

Cost tracking

Monitor token spend per span and catch runaway costs early.