Skip to main content
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.
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:
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.
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.