TracePilot class: constructor and methods reference

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

new TracePilot(apiKey: string, endpoint?: string): TracePilot

string

required

Your TracePilot API key. All keys start with tp_live_. Retrieve yours from the TracePilot dashboard.

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.

Usage

import { TracePilot } from 'tracepilot-sdk';

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

import { TracePilot } from 'tracepilot-sdk';

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

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 for the recommended environment-variable pattern.

Method summary

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

Method	Description
`tp.startTrace(agentName)`	Starts a new trace session. Call once per agent run.
`tp.wrapOpenAI()`	Wraps an OpenAI chat completion call and captures the span.
`tp.wrapToolCall()`	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.

await tp.startTrace(agentName: string): Promise<void>

string

required

A display name for this agent run. Appears as the trace root in the dashboard.

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

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

​Constructor

​Usage

​Method summary

​startTrace

Constructor

Usage

Method summary

`startTrace`