TypeScript SDK
API reference for @lilium/tracing sessions, spans, tools, sub-agents, and export behavior.
npm install @lilium/tracing#startSession(options)
Creates one trace for one logical agent run.
| Option | Type | Default | Notes |
|---|---|---|---|
apiKey | string | undefined | LILIUM_API_KEY | Missing configuration defaults to no-op |
endpoint | string | LILIUM_OTLP_URL | Defaults to the hosted trace endpoint |
agentId | string | none | Stable, path-safe identity used to group runs |
agentRole | string | none | Optional classification shared by related agents |
name | string | agentId | Human-readable name for the root span |
userId | string | none | Enables per-user filtering and attribution |
environment | string | 'production' | Separates production from development |
strict | boolean | false | Rethrows 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.