Start
Lilium
Guides
Instrument

Instrument an OpenAI agent

Record OpenAI model and tool calls inside one Lilium trace without replacing your existing client.

August 4, 2026Beginner10 minutes

Before you start

  • Node.js 20 or newer
  • An Lilium project API key
  • An existing agent built on the OpenAI SDK

This guide takes an existing OpenAI agent and produces a complete trace: one session for the run, with model and tool spans nested beneath it.

#Install the SDK

  1. Add the package to your project.

    npm install @lilium/tracing openai
  2. Set your project key. Keep it server side.

    LILIUM_API_KEY=lil_v1_xxx
    LILIUM_OTLP_URL=https://api.lilium.ai/v1/traces

#Keep your OpenAI client

The native tracing API works alongside the official client. No global telemetry provider is required.

import OpenAI from 'openai'
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

#Group calls into a run

A run is the unit an operator reviews. Create one session per ticket, chat turn, job, or other logical unit of work, then record the model call inside it.

import { startSession } from '@lilium/tracing'
 
export async function handleTicket(ticketId: string, question: string) {
  const session = startSession({
    name: 'handle-ticket',
    agentId: 'support.ticket-handler',
    userId: ticketId,
    environment: process.env.NODE_ENV,
  })
 
  try {
    const answer = await session.run(async () => {
      const modelSpan = session.startSpan({
        type: 'llm_call',
        name: 'openai.chat.completions.create',
        provider: 'openai',
        model: 'gpt-5-mini',
        input: { question },
      })
 
      try {
        const response = await openai.chat.completions.create({
          model: 'gpt-5-mini',
          messages: [{ role: 'user', content: question }],
        })
 
        const output = response.choices[0]?.message?.content ?? ''
        modelSpan.end({
          output,
          promptTokens: response.usage?.prompt_tokens,
          completionTokens: response.usage?.completion_tokens,
        })
        return output
      } catch (error) {
        modelSpan.end({ status: 'error', error })
        throw error
      }
    })
 
    await session.end({ output: answer })
    return answer
  } catch (error) {
    await session.end({ status: 'error', error })
    throw error
  }
}

Use metadata on individual spans for dimensions you will want to filter later, such as the channel, feature, or workflow version.

#Record your own tool calls

Tools that are not model calls still belong in the trace. traceToolCall records timing, inputs, outputs, and errors for anything you wrap.

const account = await session.traceToolCall(
  'lookup-account',
  () => billing.getAccount(ticketId),
  { input: { ticketId }, metadata: { channel: 'email' } },
)

#Verify the trace

Run your agent once, then open the dashboard. A correct trace shows one root span with the model and tool calls nested beneath it, each carrying duration and token cost.

If spans arrive flat instead of nested, confirm the tool and model spans were created from the same session and that asynchronous helpers run inside session.run().

#Where to go next

Read Traces and spans for the full data model, or Replay to turn one of these traces into a repeatable experiment.

Common questions

Recording spans is in memory. session.end waits for export after the agent work finishes, so model and tool calls are not blocked on telemetry.

Tracing defaults to a no-op. If you explicitly pass enabled: true without a key, session creation fails immediately so a configured integration cannot fail silently.

Yes. Redact or omit sensitive fields before passing input or output to a Lilium span. The native tracing package exports only the payloads you attach.

Yes. Keep the model span open until the stream completes, then end it with the final output and usage.