> ## 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: send your first trace with TracePilot AI

> Install the TracePilot SDK, get your API key, wrap your first agent, and see a live trace in the dashboard — all in under five minutes.

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.

<Steps>
  <Step title="Install the SDK">
    Install `tracepilot-sdk` from npm. TracePilot is a standard TypeScript package with no peer dependencies beyond your existing OpenAI SDK.

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

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

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

  <Step title="Get your API key">
    Sign in at [tracepilotai.com](https://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
    ```

    <Warning>
      Keep your API key secret. Store it in an environment variable — never commit it to source control. See [Authentication](/authentication) for best practices.
    </Warning>
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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.
  </Step>

  <Step title="View your trace in the dashboard">
    Open [tracepilotai.com/dashboard](https://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

    <Note>
      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.
    </Note>
  </Step>
</Steps>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Understand API key formats, environment variables, and custom endpoints.
  </Card>

  <Card title="Tracing tool calls" icon="wrench" href="/guides/tracing-tool-calls">
    Use `wrapToolCall` to trace database queries, web searches, and other tools.
  </Card>

  <Card title="Multi-step agents" icon="diagram-project" href="/guides/multi-step-agents">
    Link spans into an execution tree with `parentSpanId` and `stepOrder`.
  </Card>

  <Card title="Time-travel debugging" icon="clock-rotate-left" href="/concepts/time-travel-debugging">
    Learn how to fork a failing span and re-run it with edited inputs.
  </Card>
</CardGroup>