sdk

@agentkitai/agentlens-sdk

TypeScript SDK for the AgentLens observability API.

Installation

npm install @agentkitai/agentlens-sdk

Quick Start

import { AgentLensClient } from '@agentkitai/agentlens-sdk';

const client = AgentLensClient.fromEnv();

// Check server health
const health = await client.health();
console.log(health.status); // "ok"

// Query events
const { events, total } = await client.queryEvents({
  agentId: 'my-agent',
  limit: 10,
});

Configuration

fromEnv() — Zero-Config Setup

const client = AgentLensClient.fromEnv();

Reads from environment variables:

Env Var	Default	Description
AGENTLENS_SERVER_URL	http://localhost:3400	Server URL
AGENTLENS_API_KEY	—	API key

Override any value:

const client = AgentLensClient.fromEnv({
  url: 'https://api.agentlens.ai',
  apiKey: 'als_xxx',
});

Constructor Options

const client = new AgentLensClient({
  url: 'http://localhost:3400',
  apiKey: 'als_xxx',
  timeout: 30_000,
  retry: { maxRetries: 3, backoffBaseMs: 1000, backoffMaxMs: 30000 },
  failOpen: false,
  onError: (err) => console.warn(err.message),
});

Retry Configuration

Built-in exponential backoff with jitter. Retries on:

• Network errors / timeouts
• 429 Too Many Requests (respects Retry-After header)
• 503 Service Unavailable (backpressure)

Never retries: 400, 401, 402, 404.

const client = new AgentLensClient({
  url: 'http://localhost:3400',
  retry: {
    maxRetries: 5,
    backoffBaseMs: 500,
    backoffMaxMs: 60_000,
  },
});

Fail-Open Mode

When failOpen: true, all methods catch errors and return safe defaults (undefined) instead of throwing. Ideal for production where observability should never crash your app.

const client = new AgentLensClient({
  url: 'http://localhost:3400',
  failOpen: true,
  onError: (err) => myLogger.warn('AgentLens error:', err.message),
});

// This won't throw even if the server is down
const events = await client.queryEvents({ agentId: 'my-agent' });

Error Handling

All errors extend AgentLensError:

import {
  AgentLensError,
  AuthenticationError,   // 401
  NotFoundError,         // 404
  ValidationError,       // 400
  ConnectionError,       // network/timeout
  RateLimitError,        // 429 (has .retryAfter)
  QuotaExceededError,    // 402
  BackpressureError,     // 503
} from '@agentkitai/agentlens-sdk';

try {
  await client.getEvent('bad-id');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Event not found');
  } else if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter}s`);
  }
}

Drop-in instrumentation (#123)

Capture every model call with one init() — no manual logLlmCall. Each capture computes per-call cost at capture time (@agentkitai/pricing), is hash-chained via /api/events, and — when an AgentGate agentToken is supplied — carries a server-verified verifiedAgentId. Captures are fail-safe: a capture error never breaks your provider call.

import { init, shutdown } from '@agentkitai/agentlens-sdk';

init({
  url: 'http://localhost:3400',
  apiKey: process.env.AGENTLENS_API_KEY,
  agentId: 'my-agent',
  agentToken: process.env.AGENTLENS_AGENT_TOKEN, // → verified identity
});
// ... run your agent ...
await shutdown(); // flush in-flight captures before exit

OpenAI Node SDK

import OpenAI from 'openai';
import { instrumentOpenAI } from '@agentkitai/agentlens-sdk/openai';

const openai = instrumentOpenAI(new OpenAI());
await openai.chat.completions.create({ model: 'gpt-4o', messages: [...] });
// streaming is captured too (set stream_options: { include_usage: true } for token cost)

Vercel AI SDK

import { wrapLanguageModel } from 'ai';
import { openai } from '@ai-sdk/openai';
import { agentlensMiddleware } from '@agentkitai/agentlens-sdk/vercel';

const model = wrapLanguageModel({ model: openai('gpt-4o'), middleware: agentlensMiddleware() });
// generateText / streamText against `model` are captured (cost + identity)

Wrappers are duck-typed — no openai/ai peer dependency. generateText, streamText, and tool calls are captured; streams pass through unchanged.

API Reference

Events

Method	Description
queryEvents(query?)	Query events with filters and pagination
getEvent(id)	Get a single event by ID

Sessions

Method	Description
getSessions(query?)	Query sessions with filters
getSession(id)	Get a single session
getSessionTimeline(sessionId)	Full event timeline with hash chain verification

LLM Call Tracking

Method	Description
logLlmCall(sessionId, agentId, params)	Log a complete LLM call (request + response). Supports redact: true
getLlmAnalytics(params?)	Aggregate metrics by model, time, provider

const { callId } = await client.logLlmCall('session-1', 'my-agent', {
  provider: 'openai',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
  completion: 'Hi there!',
  finishReason: 'stop',
  usage: { inputTokens: 5, outputTokens: 3, totalTokens: 8 },
  costUsd: 0.001,
  latencyMs: 450,
  redact: false,
});

Recall (Semantic Search)

Method	Description
recall(query)	Semantic search over embeddings

Reflect (Pattern Analysis)

Method	Description
reflect(query)	Analyze patterns across sessions

Context

Method	Description
getContext(query)	Cross-session context for a topic

Agents & Health

Method	Description
getAgent(agentId)	Get agent details
getHealth(agentId, window?)	Health score for an agent
getHealthOverview(window?)	Health overview for all agents
getHealthHistory(agentId, days?)	Historical health snapshots

Optimization

Method	Description
getOptimizationRecommendations(options?)	Cost optimization recommendations

Guardrails

Method	Description
listGuardrails(options?)	List all guardrail rules
getGuardrail(id)	Get a guardrail rule
createGuardrail(params)	Create a guardrail rule
updateGuardrail(id, updates)	Update a guardrail rule
deleteGuardrail(id)	Delete a guardrail rule
enableGuardrail(id)	Enable a guardrail rule
disableGuardrail(id)	Disable a guardrail rule
getGuardrailHistory(options?)	Trigger history
getGuardrailStatus(id)	Status + recent triggers

Server

Method	Description
health()	Server health check (no auth)

Lessons API (Deprecated)

Lesson methods have been removed. Use lore-sdk directly.

// ❌ Old
await client.createLesson(...); // throws

// ✅ New
import { LoreClient } from 'lore-sdk';
const lore = new LoreClient();
await lore.createLesson(...);