tp.wrapOpenAI() method — TracePilot SDK reference

Wrap any OpenAI chat completion call to capture a span. Returns the original ChatCompletion result unchanged, plus a spanId for linking child spans.

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

Basic usage

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.