Agent Lightning TypeScript SDK

TypeScript SDK for interacting with Agent Lightning server.

🎯 Building agents with Mastra? Check out our Mastra Integration Guide for seamless RL training of your TypeScript agents!

What is Agent Lightning?

Agent Lightning is a Python-based framework for training and optimizing AI agents using Reinforcement Learning (RL), Automatic Prompt Optimization (APO), and other algorithms. It works with ANY agent framework (LangChain, AutoGen, CrewAI, OpenAI Agents, etc.) with minimal code changes.

Architecture Overview

Agent Lightning follows a client-server architecture:

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   Your Agent    │────────▶│ LightningStore   │◀────────│   Algorithm     │
│  (Python/TS)    │  sends  │     Server       │  reads  │    (Python)     │
│                 │  traces │   (Port 4747)    │  spans  │                 │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │   Persistent    │
                            │     Store       │
                            │ (Memory/MongoDB)│
                            └─────────────────┘

Key Components:

1. LightningStore Server - Central hub that manages:

   • Rollouts (tasks to execute)
   • Attempts (execution tries with retries)
   • Spans (telemetry/traces from agent execution)
   • Resources (prompts, model configs, etc.)
   • Workers (agent runners)

2. Agents - Your AI agents (can be Python or TypeScript) that:

   • Fetch tasks from the store
   • Execute the tasks
   • Report traces/spans back to the store

3. Algorithms - Python-based training algorithms that:

   • Read spans from completed rollouts
   • Learn from the data
   • Update resources (e.g., improved prompts)

How to Start the Server

The LightningStore server is part of the Python agentlightning package. You need to install and run it separately.

Option 1: In-Memory Store (Development)

# Install Agent Lightning (Python)
pip install agentlightning

# Start the server
agl store --host 0.0.0.0 --port 4747

This starts an in-memory server at http://localhost:4747 - perfect for development and testing!

Option 2: MongoDB Backend (Production)

For production use with persistence:

# Install with MongoDB support
pip install agentlightning[mongo]

# Start MongoDB with replica set
# (Agent Lightning requires replica set for transactions)
mongod --replSet rs0

# Initialize the replica set (first time only)
mongosh --eval "rs.initiate()"

# Start the server with MongoDB backend
agl store --backend mongo --mongo-uri "mongodb://localhost:27017/?replicaSet=rs0"

Server Options

agl store --help

Options:
  --host HOST              Host to bind (default: 0.0.0.0)
  --port PORT              Port number (default: 4747)
  --backend {memory,mongo} Storage backend (default: memory)
  --mongo-uri URI          MongoDB connection string
  --cors-origin ORIGIN     Allow CORS from origin (repeat for multiple)
  --prometheus             Enable Prometheus metrics
  --n-workers N            Number of workers (for multi-process mode)

Self-Hosted vs Cloud

Agent Lightning is 100% self-hosted - there is no cloud version. You run everything on your own infrastructure:

• ✅ Full control over your data
• ✅ No external dependencies or API keys needed
• ✅ On-premise deployment supported
• ✅ Open source (MIT License)

You can deploy the LightningStore server on:

• Local machine (development)
• Docker containers
• Kubernetes clusters
• Cloud VMs (AWS, Azure, GCP)
• On-premise servers

When to Use This TypeScript SDK

Use this SDK when you want to:

1. Build TypeScript/JavaScript agents that participate in Agent Lightning training
2. Query rollout data from a TypeScript application
3. Monitor training progress via a custom dashboard
4. Integrate with Node.js services that need to submit tasks or read results

Example Use Cases

• Building a TypeScript agent that gets trained via RL
• Creating a Next.js dashboard to visualize training metrics
• Building a Node.js service that submits evaluation tasks
• Integrating TypeScript automation tools with Agent Lightning

Installation

npm install
npm run build

Quick Start

1. Start the LightningStore Server (Python)

First, you need to have the Agent Lightning server running:

# In a separate terminal
pip install agentlightning
agl store --host 0.0.0.0 --port 4747

You should see:

INFO:     Serving the lightning store at http://0.0.0.0:4747, accessible at http://0.0.0.0:4747
INFO:     Lightning store server started in X.XX seconds

2. Use the TypeScript SDK

import { LightningStoreClient } from "agent-lightning-sdk";

async function main() {
  // Connect to the server
  const client = new LightningStoreClient("http://localhost:4747");

  // Check if server is healthy
  const health = await client.health();
  console.log("Server status:", health); // { status: "ok" }

  // Enqueue a task
  const rollout = await client.enqueueRollout({
    prompt: "Write a function to calculate fibonacci numbers"
  });
  console.log("Rollout ID:", rollout.rollout_id);

  // Query rollouts
  const rollouts = await client.queryRollouts({ limit: 10 });
  console.log("Total rollouts:", rollouts.total);
}

main();

3. Full Example: Agent Runner

Here's a complete example of a TypeScript agent that processes tasks:

import { LightningStoreClient } from "agent-lightning-sdk";

const client = new LightningStoreClient("http://localhost:4747");

async function runAgent() {
  // Register as a worker
  const workerId = "ts-worker-1";
  
  while (true) {
    // Dequeue the next task
    const attemptedRollout = await client.dequeueRollout(workerId);
    
    if (!attemptedRollout) {
      console.log("No tasks available, waiting...");
      await new Promise(resolve => setTimeout(resolve, 5000));
      continue;
    }

    console.log(`Processing rollout: ${attemptedRollout.rollout_id}`);
    
    try {
      // Your agent logic here
      const result = await processTask(attemptedRollout.input);
      
      // Report success
      await client.updateAttempt(
        attemptedRollout.rollout_id,
        attemptedRollout.attempt.attempt_id,
        { status: "succeeded" }
      );
      
      await client.updateRollout(
        attemptedRollout.rollout_id,
        { status: "succeeded" }
      );
      
    } catch (error) {
      // Report failure
      await client.updateAttempt(
        attemptedRollout.rollout_id,
        attemptedRollout.attempt.attempt_id,
        { status: "failed" }
      );
    }
  }
}

async function processTask(input: any) {
  // Your agent implementation
  return { result: "Task completed" };
}

runAgent();

Usage

import { LightningStoreClient } from "agent-lightning-sdk";

// Create a client instance
const client = new LightningStoreClient("http://localhost:4747");

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

// Enqueue a rollout
const rollout = await client.enqueueRollout(
  { prompt: "Hello, world!" },
  "train",
  undefined,
  { max_attempts: 3 }
);

// Query rollouts
const rollouts = await client.queryRollouts({
  status_in: ["queuing", "running"],
  limit: 10
});

// Get latest resources
const resources = await client.getLatestResources();

// Update worker heartbeat
await client.updateWorker("worker-1", {
  heartbeat_stats: { memory_usage: 512 }
});

API Reference

Rollout Operations

• enqueueRollout(input, mode?, resourcesId?, config?, metadata?) - Enqueue a new rollout
• dequeueRollout(workerId?) - Dequeue the next available rollout
• startRollout(input, mode?, resourcesId?, config?, metadata?) - Start a rollout immediately
• queryRollouts(params?) - Query rollouts with filters
• getRolloutById(rolloutId) - Get a specific rollout
• updateRollout(rolloutId, updates) - Update rollout metadata
• waitForRollouts(rolloutIds, timeout?) - Wait for rollouts to complete

Attempt Operations

• startAttempt(rolloutId) - Create a new attempt for a rollout
• updateAttempt(rolloutId, attemptId, updates) - Update attempt status
• queryAttempts(rolloutId, params?) - Query attempts for a rollout
• getLatestAttempt(rolloutId) - Get the most recent attempt

Worker Operations

• queryWorkers(params?) - Query workers with filters
• getWorkerById(workerId) - Get a specific worker
• updateWorker(workerId, updates) - Update worker heartbeat

Resource Operations

• queryResources(params?) - Query resources with filters
• addResources(resources) - Add new resources
• getLatestResources() - Get the latest resources
• updateResources(resourcesId, resources) - Update existing resources
• getResourcesById(resourcesId) - Get specific resources by ID

Span Operations

• addSpan(span) - Add a telemetry span
• querySpans(params) - Query spans with filters
• getNextSpanSequenceId(rolloutId, attemptId) - Get the next sequence ID for a span

Other Operations

• health() - Check server health
• getStatistics() - Get server statistics

Types

All types are exported from the SDK:

import {
  Rollout,
  AttemptedRollout,
  Attempt,
  Worker,
  ResourcesUpdate,
  Span,
  PaginatedResult
} from "agent-lightning-sdk";

Development

Build

npm run build

Test

npm test

License

MIT