agentlens/packages/sdk-ts/README.md

agentlens-sdk

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

Install

npm install agentlens-sdk

Quick Start

First, create an account at agentlens.vectry.tech/register and generate an API key in Settings > API Keys in the dashboard.

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

// Initialize with the API key from Settings > API Keys
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. Create at Settings > API Keys in the dashboard.
  endpoint: "https://...",      // API endpoint. Defaults to AgentLens cloud.
  maxBatchSize: 100,            // Max items per batch before auto-flush.
  flushInterval: 5000,          // Auto-flush interval in milliseconds.
});

You can also set the API key via the AGENTLENS_API_KEY environment variable instead of passing it directly.

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.

Billing

Each trace counts as one session for billing. AgentLens cloud offers three tiers:

Plan	Price	Sessions
Free	$0	20 sessions/day
Starter	$5/month	1,000 sessions/month
Pro	$20/month	100,000 sessions/month

Manage your subscription in Settings > Billing. Self-hosted instances have no session limits.

Documentation

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

License

MIT