How to wrap OpenAI calls and capture full agent traces

Learn how to initialize TracePilot AI, start a trace, and wrap OpenAI chat completions to capture inputs, outputs, tokens, and latency automatically.

TracePilot AI instruments your OpenAI calls with a single wrapper function. Every call you wrap becomes a structured span in the dashboard — capturing the prompt, the completion, token usage, latency, and any errors — without changing how the rest of your code reads the response.

Prerequisites

Install the SDK and make sure you have an OpenAI API key ready.

npm install tracepilot-sdk openai

Get your TracePilot API key by signing in at tracepilotai.com with GitHub or Google. Your key looks like tp_live_xxxxxxxxxxxxxxxx.

Wrap your first call

1. Import and initialize

   Import TracePilot alongside the OpenAI client and create instances of both.

   import { TracePilot } from 'tracepilot-sdk';
   import OpenAI from 'openai';
   
   const tp = new TracePilot('tp_live_YOUR_KEY');
   const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
   
2. Start a trace

   Call tp.startTrace once at the beginning of each agent run. Pass a name that identifies this agent or workflow — it appears as the trace label in the dashboard.

   await tp.startTrace('customer-support-agent');
   
3. Wrap the OpenAI call

   Replace a bare openai.chat.completions.create call with tp.wrapOpenAI. Pass the call as a function and include the messages array as the second argument.

   const messages = [
     { role: 'user', content: 'How do I reset my password?' }
   ];
   
   const { result, spanId } = await tp.wrapOpenAI(
     () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
     messages
   );
   
   console.log(result.choices[0].message.content);
   

wrapOpenAI returns the original OpenAI response object unchanged. Any code that reads result.choices[0].message.content or any other field on the completion response continues to work without modification.

Full working example

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

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

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

  const messages = [
    { role: 'user', content: 'How do I reset my password?' }
  ];

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

  console.log(result.choices[0].message.content);
  // Open tracepilotai.com/dashboard — your trace is already there.
}

runAgent();

After the function runs, open tracepilotai.com/dashboard. The trace appears immediately with no additional configuration.

Optional parameters

wrapOpenAI accepts two additional parameters that become useful once your agent has multiple steps.

parentSpanId

Pass the spanId returned by a previous wrapOpenAI or wrapToolCall call to link the current span as a child of that span. This builds a parent-child execution tree in the dashboard.

// Step 1 — no parent, this is the root span
const { result: plan, spanId: planSpanId } = await tp.wrapOpenAI(
  () => openai.chat.completions.create({ model: 'gpt-4o', messages }),
  messages
);

// Step 2 — linked to the root span
const followUpMessages = [...messages, plan.choices[0].message];
const { result: answer, spanId: answerSpanId } = await tp.wrapOpenAI(
  () => openai.chat.completions.create({ model: 'gpt-4o', messages: followUpMessages }),
  followUpMessages,
  planSpanId  // parentSpanId — makes this a child of step 1
);

stepOrder

Pass a number to control the order in which spans are displayed within the same parent. Without stepOrder, the dashboard sorts spans by arrival time, which can be inconsistent under concurrency.

const { result, spanId } = await tp.wrapOpenAI(
  () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
  messages,
  parentSpanId,
  1  // stepOrder — this span appears first in the tree
);

Using a custom ingest endpoint

If you are self-hosting the TracePilot backend, pass your endpoint as the second argument to the constructor.

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

All other methods work identically.

Error handling

If the OpenAI call throws, wrapOpenAI captures the error as a failed span in the dashboard and re-throws the original error. Your existing try/catch blocks remain effective.

try {
  const { result, spanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
    messages
  );
} catch (err) {
  // The error is already recorded in the dashboard.
  // Handle it here as you normally would.
  console.error(err);
}