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

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

apiKey · string · required

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

endpoint · 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

Standard (cloud)

import { TracePilot } from 'tracepilot-sdk';

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

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>

agentName · 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
}