141 lines
4.3 KiB
Markdown
141 lines
4.3 KiB
Markdown
# agentlens-sdk
|
|
|
|
TypeScript SDK for AgentLens — Agent observability that traces decisions, not just API calls.
|
|
|
|
[](https://www.npmjs.com/package/agentlens-sdk)
|
|
[](https://github.com/repi/agentlens/blob/main/LICENSE)
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install agentlens-sdk
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
|
|
|
|
```typescript
|
|
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.
|
|
|
|
```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. 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](https://agentlens.vectry.tech/docs/typescript-sdk)
|
|
|
|
## License
|
|
|
|
MIT
|