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

# TracePilot class: constructor and methods reference

> Constructor reference for the TracePilot class. Pass your API key and an optional custom ingest endpoint to initialize the SDK for your agent.

The `TracePilot` class is the single entry point for the TracePilot SDK. You instantiate it once per process, passing your API key, and then use the returned instance to start traces and wrap LLM or tool calls throughout your agent.

## Constructor

```typescript theme={null}
new TracePilot(apiKey: string, endpoint?: string): TracePilot
```

<ParamField path="apiKey" type="string" required>
  Your TracePilot API key. All keys start with `tp_live_`. Retrieve yours from the [TracePilot dashboard](https://tracepilotai.com/dashboard).
</ParamField>

<ParamField path="endpoint" type="string">
  Optional custom ingest endpoint URL. Use this when you run a self-hosted TracePilot server. Omit this parameter to send data to the default TracePilot cloud ingest endpoint.
</ParamField>

## Usage

<CodeGroup>
  ```typescript Standard (cloud) theme={null}
  import { TracePilot } from 'tracepilot-sdk';

  const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);
  ```

  ```typescript Self-hosted endpoint theme={null}
  import { TracePilot } from 'tracepilot-sdk';

  const tp = new TracePilot(
    process.env.TRACEPILOT_API_KEY!,
    'https://your-server.com/api/ingest'
  );
  ```
</CodeGroup>

<Note>
  API keys always begin with `tp_live_`. If your key does not match this format, generate a new one from the dashboard. Never commit API keys to source control — see [Configure the TracePilot AI SDK](/reference/configuration) for the recommended environment-variable pattern.
</Note>

## Method summary

After constructing a `TracePilot` instance, use these methods to instrument your agent:

| Method                                           | Description                                                  |
| ------------------------------------------------ | ------------------------------------------------------------ |
| [`tp.startTrace(agentName)`](#starttrace)        | Starts a new trace session. Call once per agent run.         |
| [`tp.wrapOpenAI()`](/reference/wrap-openai)      | Wraps an OpenAI chat completion call and captures the span.  |
| [`tp.wrapToolCall()`](/reference/wrap-tool-call) | Wraps any async tool or function call and captures the span. |

## `startTrace`

Starts a new trace session. Call this once at the beginning of each agent run, before any `wrapOpenAI` or `wrapToolCall` calls.

```typescript theme={null}
await tp.startTrace(agentName: string): Promise<void>
```

<ParamField path="agentName" type="string" required>
  A display name for this agent run. Appears as the trace root in the dashboard.
</ParamField>

```typescript theme={null}
const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);

async function runAgent() {
  await tp.startTrace('customer-support-agent');
  // ... your agent logic
}
```