# agentlens-sdk

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

[![npm version](https://img.shields.io/npm/v/agentlens-sdk.svg)](https://www.npmjs.com/package/agentlens-sdk)
[![license](https://img.shields.io/npm/l/agentlens-sdk.svg)](https://github.com/repi/agentlens/blob/main/LICENSE)

## Install

```bash
npm install agentlens-sdk
```

## Quick Start

```typescript
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.

```typescript
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()`:

```typescript
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](https://agentlens.vectry.tech/docs/typescript-sdk)

## License

MIT