​
Overview

The Lucidic TypeScript SDK provides a comprehensive set of functions to track, monitor, and analyze AI agent workflows. These functions handle session management, step tracking, event logging, and integration with various LLM providers.

​
Installation

npm install lucidicai

​
Quick Start

import * as lai from 'lucidicai';
import OpenAI from 'openai';

// Initialize a session (manual instrumentation recommended for ESM)
await lai.init({
  sessionName: "My AI Agent",
  instrumentModules: { OpenAI }
});

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// Create a step  
await lai.createStep();

// Your AI operations are automatically tracked
// ...

// End the step and session when appropriate
await lai.endStep();
await lai.endSession();

​
Session Management

init

Initialize the SDK and optionally create a session

Session Context

Async-safe session context for concurrent backends

updateSession

Update session metadata

endSession

End the current session

​
Step Management

createStep

Create a new step in the workflow

updateStep

Update an existing step

endStep

End the current step

​
Event Management

createEvent

Create a new event within a step

updateEvent

Update an existing event

​
Advanced Features

getPrompt

Retrieve prompts from the platform

​
Function Categories

​
Session Lifecycle

  1. Initialization: Use init() to initialize SDK and optionally start a session
  2. Continuation: To resume an existing session, call init({ sessionId })
  3. Updates: Modify session data with updateSession()
  4. Completion: End with endSession() including success status

​
Step Management

  1. Creation: Use createStep() to begin tracking a unit of work
  2. Updates: Update step data with updateStep()
  3. Completion: Finish with endStep() including evaluation
  4. Self-contained tasks: Prefer withLucidic for workflows that should end automatically (see Session Context)

​
Event Tracking

  1. Automatic: LLM calls through instrumented providers create events automatically
  2. Manual: Use createEvent() for custom events
  3. Updates: Modify events with updateEvent()

​
Utilities

  1. Prompts: Centralized prompt management with getPrompt()
  2. Context: Async-safe session scoping via withSession, withLucidic, setActiveSession, clearActiveSession

​
Provider Support

The SDK instruments providers via instrumentModules in init():
  • OpenAI - instrumentModules: { OpenAI }
  • Anthropic - instrumentModules: { anthropic: Anthropic }
  • LangChain - instrumentModules: { langchain: LangChain }

​
Key Differences from Python SDK

  1. Async by Default: All functions return Promises and must be awaited
  2. Import Order: Providers must be imported AFTER init() for instrumentation
  3. Named Parameters: Functions use object parameters for better TypeScript support
  4. No Decorators: Function-based API only (decorators exist but not recommended)

​
Best Practices

  1. Prefer withLucidic for self-sufficient workflows: It handles init → context → end automatically
  2. Always Initialize First: Call await lai.init() before any other operations
  3. Import Order Matters: Import LLM providers AFTER initialization
  4. Use Named Parameters: TypeScript’s object syntax provides better IDE support
  5. Handle Promises: Always await async operations or handle Promise chains
  6. Type Safety: Leverage TypeScript’s type system for better development experience

​
Error Handling

import { APIError } from 'lucidicai';

try {
  await lai.init({ sessionName: "My Session" });
} catch (error) {
  if (error instanceof APIError) {
    console.error("API key verification failed:", error.message);
  }
}

​
Environment Variables

  • LUCIDIC_API_KEY - Your API key for authentication
  • LUCIDIC_AGENT_ID - Your agent identifier

​
See Also