Start
Lilium
SDKs

TypeScript SDK

API reference for @lilium/tracing sessions, spans, tools, sub-agents, and export behavior.

Updated August 4, 2026
npm install @lilium/tracing

#startSession(options)

Creates one trace for one logical agent run.

OptionTypeDefaultNotes
apiKeystring | undefinedLILIUM_API_KEYMissing configuration defaults to no-op
endpointstringLILIUM_OTLP_URLDefaults to the hosted trace endpoint
agentIdstringnoneStable, path-safe identity used to group runs
agentRolestringnoneOptional classification shared by related agents
namestringagentIdHuman-readable name for the root span
userIdstringnoneEnables per-user filtering and attribution
environmentstring'production'Separates production from development
strictbooleanfalseRethrows export failures, useful for CI and smoke tests

#session.run(callback)

Runs work inside the session root so nested helper methods inherit the active parent.

import { startSession } from '@lilium/tracing'
 
const session = startSession({ agentId: 'support.answerer', userId })
 
const output = await session.run(async () => {
  // tool and sub-agent helpers called here inherit this trace
})
await session.end({ output })

#session.startSpan(options)

Creates a child span for an LLM call, tool call, memory operation, retrieval, sub-agent, or custom operation. End it in both success and failure paths.

const span = session.startSpan({
  type: 'llm_call',
  name: 'draft-reply',
  provider: 'openai',
  model: 'gpt-5-mini',
  input: { messages },
})
 
try {
  const reply = await callModel(messages)
  span.end({ output: reply, promptTokens: 120, completionTokens: 34 })
} catch (error) {
  span.end({ status: 'error', error })
  throw error
}

type accepts llm_call, tool_call, memory_read, memory_write, sub_agent, retrieval, or custom. See traces and spans for how these render.

#Tool and sub-agent helpers

The helpers record outputs and errors automatically while preserving parent context.

const account = await session.traceToolCall(
  'lookup-account',
  () => billing.getAccount(id),
  { input: { id } },
)
 
const research = await session.traceSubagent(
  { agentId: 'support.researcher', name: 'research-account' },
  () => researchAccount(account),
)

#End and flush

session.end() closes the root span and waits for the trace export. Call it once in every terminal path. session.flush() can export the current snapshot without closing the session.

await session.end({ output })

For a drop-in OpenAI client, use @lilium/openai. For frameworks that already emit OpenTelemetry, use @lilium/otel and keep their native instrumentation.

#Failure behavior

Export failures are reported through onDiagnostic and do not throw unless strict: true. Explicitly enabling tracing without an API key does throw during session creation, which prevents a configured integration from failing silently.