TypeScript SDK

The AgentLens TypeScript SDK provides a builder-based API for constructing and sending traces from Node.js and edge runtimes.

npm install agentlens-sdk

API Reference

init()

init({ apiKey, endpoint, flushInterval?, maxBatchSize?, enabled? })

Initialize the SDK. Must be called once before creating any traces.

Options

Property	Type	Default	Description
apiKey	string	required	Your AgentLens API key
endpoint	string	required	AgentLens server URL
flushInterval	number	5000	Milliseconds between flushes
maxBatchSize	number	100	Max traces per batch
enabled	boolean	true	Toggle tracing on/off

init.ts

import { init } from "agentlens-sdk";

init({
  apiKey: process.env.AGENTLENS_API_KEY!,
  endpoint: "https://agentlens.vectry.tech",
  flushInterval: 10000,
});

TraceBuilder

new TraceBuilder(name, options?)

Builder for constructing a trace incrementally. Add spans, decision points, and events, then call end() to finalize and send.

Constructor options

Property	Type	Description
tags	string[]	Tags for this trace
sessionId	string	Group traces into a session
metadata	Record<string, unknown>	Arbitrary metadata

Methods

addSpan(span: SpanInput): string

Add a span to the trace. Returns the generated span ID. Pass parentSpanId to nest spans.

addDecision(decision: DecisionInput): string

Add a decision point. Returns the generated decision ID.

addEvent(event: EventInput): string

Add an event to the trace. Returns the generated event ID.

end(status?: "COMPLETED" | "ERROR"): Promise<void>

Finalize and send the trace. Defaults to COMPLETED.

trace-builder.ts

import { TraceBuilder } from "agentlens-sdk";

const trace = new TraceBuilder("customer-support", {
  tags: ["support", "v2"],
  sessionId: "session-abc",
});

const agentSpan = trace.addSpan({
  name: "classify-intent",
  type: "LLM_CALL",
  input: { messages: [{ role: "user", content: "I need a refund" }] },
  output: { intent: "refund", confidence: 0.95 },
  status: "COMPLETED",
  tokenCount: 150,
  costUsd: 0.002,
  durationMs: 340,
});

trace.addDecision({
  type: "ROUTING",
  chosen: { handler: "refund-flow" },
  alternatives: [{ handler: "faq-flow" }, { handler: "escalate" }],
  reasoning: "High confidence refund intent",
  parentSpanId: agentSpan,
});

trace.addSpan({
  name: "process-refund",
  type: "TOOL_CALL",
  input: { orderId: "ord-123" },
  output: { success: true },
  status: "COMPLETED",
  parentSpanId: agentSpan,
});

await trace.end();

createDecision()

createDecision(type, chosen, alternatives, options?)

Standalone helper to create a decision point outside of a TraceBuilder. Useful when building traces from raw data.

standalone.ts

import { createDecision } from "agentlens-sdk";

const decision = createDecision(
  "TOOL_SELECTION",
  { tool: "calculator", confidence: 0.88 },
  [
    { tool: "web_search", confidence: 0.52 },
    { tool: "code_exec", confidence: 0.34 },
  ],
  { reasoning: "Math expression detected in input" }
);

shutdown()

shutdown(timeout?: number): Promise<void>

Flush all pending traces and tear down the background sender. Default timeout is 10 seconds.

shutdown.ts

import { shutdown } from "agentlens-sdk";

process.on("SIGTERM", async () => {
  await shutdown(30000);
  process.exit(0);
});

Environment Variables

Variable	Description
AGENTLENS_API_KEY	API key (overrides init param)
AGENTLENS_ENDPOINT	Server URL (overrides init param)
AGENTLENS_ENABLED	Set to "false" to disable