Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tracepilot.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

tp.wrapOpenAI() intercepts an OpenAI chat completion call, records the input messages, output, token usage, latency, and any errors as a structured span, and then returns the original ChatCompletion object without modification. You can use the returned spanId to attach child spans and build a nested execution tree that is visible in the dashboard.

​
Signature

tp.wrapOpenAI(
  call: () => Promise<ChatCompletion>,
  messages: ChatCompletionMessageParam[],
  parentSpanId?: string,
  stepOrder?: number
): Promise<{ result: ChatCompletion; spanId: string }>

​
Parameters

​
call
() => Promise<ChatCompletion>
required
A zero-argument function that calls openai.chat.completions.create(...) and returns a Promise<ChatCompletion>. Wrap your call in an arrow function so TracePilot can time it and catch errors.
​
messages
ChatCompletionMessageParam[]
required
The messages array you pass to the completion. TracePilot records these as the span input so you can inspect and edit them in the dashboard’s Fork & Rerun flow.
​
parentSpanId
string
The spanId of a parent span. Providing this value links the current span as a child of the parent, building a hierarchical execution tree in the dashboard. Omit for root-level LLM calls.
​
stepOrder
number
An integer indicating this span’s position in the execution sequence. Used to order sibling spans in the dashboard when multiple spans share the same parent.

​
Return value

​
result
ChatCompletion
The original OpenAI ChatCompletion response, returned unchanged. Your agent code can use this exactly as it would without TracePilot.
​
spanId
string
The ID of the span created for this call. Pass this as parentSpanId to subsequent wrapOpenAI or wrapToolCall calls to nest them under this span.

​
Examples

import { TracePilot } from 'tracepilot-sdk';
import OpenAI from 'openai';

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runAgent() {
  await tp.startTrace('my-agent');

  const messages = [{ role: 'user', content: 'Summarise this document.' }];

  const { result, spanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
    messages
  );

  console.log(result.choices[0].message.content);
}

​
Building span trees

Every wrapOpenAI call returns a spanId. Passing that spanId as parentSpanId in a later call creates a parent-child relationship between the two spans. The dashboard renders these relationships as an indented execution tree, making it easy to see which LLM call triggered which downstream steps. 
// Step 1 — initial reasoning
const { spanId: step1Id } = await tp.wrapOpenAI(call1, messages1, undefined, 1);

// Step 2 — tool call triggered by step 1
const { spanId: step2Id } = await tp.wrapToolCall('web-search', search, step1Id, 2);

// Step 3 — synthesis based on tool output
const { spanId: step3Id } = await tp.wrapOpenAI(call3, messages3, step2Id, 3);
When a span in the tree fails, you can open the dashboard, select that span, and use Fork & Rerun to edit its input and re-execute from that exact point — without redeploying your agent.