agentlens/packages/sdk-ts

agentlens-sdk

TypeScript SDK for AgentLens — Agent observability that traces decisions, not just API calls.

Install

npm install agentlens-sdk

Quick Start

import { init, TraceBuilder, shutdown } from "agentlens-sdk";

// Initialize the SDK
init({
  apiKey: "your-api-key",
  endpoint: "https://agentlens.vectry.tech/api",
});

// Create a trace
const trace = new TraceBuilder("agent-run-123", "My Agent Task");

// Add a span (tool call, LLM call, etc.)
trace.addSpan({
  name: "search-documents",
  type: "tool",
  input: { query: "quarterly report" },
  output: { results: 5 },
});

// Record a decision point
trace.addDecision({
  name: "select-tool",
  type: "tool_selection",
  options: ["search", "calculate", "summarize"],
  selected: "search",
  reasoning: "User asked for document lookup",
});

// Finalize and send
await trace.end();

// Flush remaining data before exit
await shutdown();

API Reference

Core Functions

Function	Description
init(options)	Initialize the SDK with your API key and configuration.
shutdown()	Flush pending data and shut down the transport.
flush()	Manually flush the current batch without shutting down.
getClient()	Return the initialized client instance.

TraceBuilder

The primary interface for constructing traces.

const trace = new TraceBuilder(traceId: string, name: string);

trace.addSpan(span: SpanPayload);       // Add a span to the trace
trace.addDecision(decision: DecisionPointPayload); // Record a decision point
trace.end(): Promise<void>;             // Finalize and send the trace

Standalone Helpers

Function	Description
createDecision(decision)	Create and send a standalone decision point outside a trace.

Types

Core payload types used throughout the SDK:

• TracePayload — Top-level trace structure containing spans and metadata.
• SpanPayload — Individual unit of work (tool call, LLM request, retrieval, etc.).
• DecisionPointPayload — A recorded decision: what options existed, what was chosen, and why.
• EventPayload — Discrete event within a span or trace.
• JsonValue — Flexible JSON-compatible value type for inputs/outputs.

Enums

Enum	Values
TraceStatus	Status of the overall trace (e.g., running, completed, failed).
SpanType	Category of span (e.g., tool, llm, retrieval).
SpanStatus	Status of an individual span.
DecisionType	Category of decision (e.g., tool_selection, routing).
EventType	Category of event within a span.

Configuration

Pass InitOptions to init():

init({
  apiKey: "your-api-key",       // Required. Your AgentLens API key.
  endpoint: "https://...",      // API endpoint. Defaults to AgentLens cloud.
  maxBatchSize: 100,            // Max items per batch before auto-flush.
  flushInterval: 5000,          // Auto-flush interval in milliseconds.
});

Transport

The SDK ships with BatchTransport, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by init() — you typically do not need to instantiate it directly.

Documentation

Full documentation: agentlens.vectry.tech/docs/typescript-sdk

License

MIT