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.

This page walks you through everything you need to send your first trace to TracePilot AI. By the end, you’ll have a working agent instrumented with TracePilot and a live trace visible in your dashboard.
1

Install the SDK

Install tracepilot-sdk from npm. TracePilot is a standard TypeScript package with no peer dependencies beyond your existing OpenAI SDK.
npm install tracepilot-sdk
2

Get your API key

Sign in at tracepilotai.com with GitHub or Google. Once you’re signed in, your API key is shown in your account settings. It looks like this:
tp_live_xxxxxxxxxxxxxxxx
Keep your API key secret. Store it in an environment variable — never commit it to source control. See Authentication for best practices.
3

Wrap your first agent

Create a TracePilot instance with your API key, then use tp.startTrace() and tp.wrapOpenAI() to instrument your agent. TracePilot wraps your existing OpenAI calls and returns the original result untouched, so your agent logic doesn’t change.
import { TracePilot } from 'tracepilot-sdk';
import OpenAI from 'openai';

const tp = new TracePilot('tp_live_YOUR_KEY');
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runAgent() {
  await tp.startTrace('customer-support-agent');

  const messages = [
    { role: 'user', content: 'How do I reset my password?' }
  ];

  // One wrapper. Full visibility.
  const { result, spanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
    messages
  );

  console.log(result.choices[0].message.content);
  // → Open your dashboard. You'll see the full trace.
}

runAgent();
tp.wrapOpenAI() returns both the original result from OpenAI and a spanId you can use to build parent-child span trees in multi-step agents.
4

View your trace in the dashboard

Open tracepilotai.com/dashboard. Your trace is already there — TracePilot sends it in the background as your agent runs.In the dashboard you can:
  • Inspect every span’s input, output, token count, and latency
  • Click Fork & Rerun on any span to edit the prompt and replay from that exact step
  • Track token usage and estimated cost per span in real time
Traces appear in the dashboard within seconds of your agent finishing. If you don’t see your trace, double-check that your API key is correct and that tp.startTrace() was called before any wrapOpenAI calls.

​
Next steps

Now that you have your first trace running, explore the rest of TracePilot’s capabilities.

Authentication

Understand API key formats, environment variables, and custom endpoints.

Tracing tool calls

Use wrapToolCall to trace database queries, web searches, and other tools.

Multi-step agents

Link spans into an execution tree with parentSpanId and stepOrder.

Time-travel debugging

Learn how to fork a failing span and re-run it with edited inputs.