Lyzr SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for the Lyzr AI Agent Platform.

Installation

npm install @lyzr/sdk

Quick Start

import { Studio } from '@lyzr/sdk';

// Initialize SDK
const studio = new Studio({
  apiKey: 'sk-your-api-key'
  // or use LYZR_API_KEY environment variable
});

// Create an agent
const agent = await studio.createAgent({
  name: 'Assistant',
  provider: 'gpt-4o',
  role: 'Helpful assistant',
  goal: 'Answer user questions',
  instructions: 'Be concise and friendly'
});

// Run the agent
const response = await agent.run('Hello! What is machine learning?');
console.log(response.response);

// Delete when done
await agent.delete();

Features

• Smart Agents: Create and manage AI agents with custom instructions
• Knowledge Bases: Build RAG systems with multiple data sources
• Tools: Register local functions for agent execution
• Structured Outputs: Type-safe responses with Zod schemas
• Memory: Conversation context with external providers
• Streaming: Real-time agent responses
• RAI Guardrails: Safety and compliance checks
• Contexts: Global background information
• Image Models: Generate images with DALL-E, Stability AI

Supported Providers

LLM Models

• OpenAI: GPT-4o, GPT-4o-mini, O3
• Anthropic: Claude Sonnet 4.5, Claude Opus 4.5
• Google: Gemini 2.0, Gemini 2.5, Gemini 3.0
• Groq: Llama 3.1/3.3/4
• Perplexity: Sonar, Sonar Pro
• AWS Bedrock: Nova, Claude, Llama, Mistral

Vector Stores

• Qdrant
• Weaviate
• PostgreSQL (PG-Vector)
• Milvus
• Amazon Neptune

API Reference

Studio

const studio = new Studio({
  apiKey: 'sk-xxx',
  env: 'prod',          // 'prod', 'dev', 'local'
  logLevel: 'warning',  // 'debug', 'info', 'warning', 'error'
  timeout: 30000,
  retries: 3
});

// Agent methods
await studio.createAgent(config);
await studio.getAgent(agentId);
await studio.listAgents();
await studio.updateAgent(agentId, config);
await studio.deleteAgent(agentId);

// Knowledge base methods
await studio.createKnowledgeBase(config);
await studio.getKnowledgeBase(kbId);
await studio.listKnowledgeBases();
await studio.deleteKnowledgeBase(kbId);

// Context methods
await studio.createContext(name, value);
await studio.getContext(contextId);
await studio.listContexts();
await studio.deleteContext(contextId);

// RAI methods
await studio.createRAIPolicy(config);
await studio.getRAIPolicy(policyId);
await studio.listRAIPolicies();
await studio.deleteRAIPolicy(policyId);

// Memory methods
await studio.createMemoryCredential(provider, name, credentials);
await studio.listMemoryProviders();

Agent

// Core
await agent.run('message', { sessionId: 'user_1', stream: false });
await agent.update({ temperature: 0.5 });
await agent.delete();
await agent.clone('New Name');

// Tools
await agent.addTool(myFunction);
await agent.removeTool('toolName');
agent.listTools();

// Memory
agent.addMemory(30);
agent.removeMemory();
agent.hasMemory();

// Context
await agent.addContext(context);
await agent.removeContext(contextId);
await agent.listContexts();

// RAI
agent.addRaiPolicy(policy);
agent.removeRaiPolicy();
agent.hasRaiPolicy();

// File & Image Output
agent.enableFileOutput();
agent.disableFileOutput();
agent.setImageModel(config);

// Features
agent.enableReflection();
agent.enableBiasCheck();
agent.enableLLMJudge();
agent.addGroundednessFacts(['fact1', 'fact2']);

KnowledgeBase

// Training
await kb.addPdf('path/to/file.pdf');
await kb.addDocx('path/to/file.docx');
await kb.addTxt('path/to/file.txt');
await kb.addWebsite(['https://docs.example.com']);
await kb.addText('text content', 'source');

// Query
const results = await kb.query('question', { topK: 5 });

// Management
await kb.listDocuments();
await kb.deleteDocuments(['doc_id']);
await kb.reset();
await kb.delete();

Memory

const memory = await studio.createMemoryCredential(
  'mem0',
  'My Memory',
  {
    mem0_api_key: 'key',
    // ... other provider-specific fields
  }
);

await memory.validate();
await memory.getStatus();
await memory.delete();

Tools

// Define a local tool (just a function!)
function calculateSum(a: number, b: number): number {
  return a + b;
}

// Register with agent
await agent.addTool(calculateSum);

// Or create a Tool explicitly
import { Tool } from '@lyzr/sdk';

const myTool = new Tool(
  calculateSum,
  'calculate_sum',
  'Calculate the sum of two numbers'
);
await agent.addTool(myTool);

Structured Outputs with Zod

import { z } from 'zod';

const AnalysisSchema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  confidence: z.number().min(0).max(1),
  summary: z.string()
});

const agent = await studio.createAgent({
  name: 'Analyzer',
  provider: 'gpt-4o',
  role: 'Sentiment analyzer',
  goal: 'Analyze sentiment',
  instructions: 'Provide detailed analysis',
  responseModel: AnalysisSchema
});

const result = await agent.run('I love this product!');
// result is fully typed: { sentiment: 'positive', confidence: 0.95, summary: '...' }
console.log(result.sentiment);  // Full IDE autocomplete!

Error Handling

import {
  LyzrError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  APIError
} from '@lyzr/sdk';

try {
  const agent = await studio.createAgent(config);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid configuration:', error.message);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
  } else {
    throw error;
  }
}

Examples

Check the examples/ directory for comprehensive examples:

• 00-power-example.ts - Complete real-world example
• 01-quickstart.ts - Basic agent operations
• 02-structured-outputs.ts - Zod schemas
• 03-knowledge-bases.ts - RAG functionality
• 04-memory.ts - Conversation context
• 05-local-tools.ts - Function tools
• 06-complete-workflow.ts - All features
• 07-contexts.ts - Background information
• 08-file-output.ts - File generation
• 09-rai-guardrails.ts - Safety features
• 10-advanced-features.ts - Advanced patterns
• 11-streaming.ts - Streaming responses

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Format
npm run format

# Type check
npm run typecheck

Requirements

• Node.js 16+
• TypeScript 5.0+ (if using TypeScript)

Best Practices

Session Management

import { v4 as uuidv4 } from 'uuid';

// Generate unique session ID per user
const sessionId = uuidv4();

// Maintain conversation context
const response1 = await agent.run('My name is Alice', { sessionId });
const response2 = await agent.run("What's my name?", { sessionId });
// Remembers "Alice"

Streaming Responses

// Stream responses for real-time output
for await (const chunk of await agent.run('Tell a story', { stream: true })) {
  process.stdout.write(chunk.content);
}

Migration from Python

The TypeScript SDK maintains API compatibility with the Python SDK:

# Python
agent = studio.create_agent(name='Bot', provider='gpt-4o', ...)
response = agent.run('message')
agent.add_tool(my_function)

// TypeScript
const agent = await studio.createAgent({ name: 'Bot', provider: 'gpt-4o', ... });
const response = await agent.run('message');
await agent.addTool(myFunction);

Key differences:

• All methods are async in TypeScript
• Use camelCase for property names (vs snake_case in Python)
• Zod schemas instead of Pydantic models
• AsyncIterable for streaming vs Python generators

Support

• Documentation: docs.lyzr.ai
• GitHub: github.com/lyzr-ai/sdk
• Discord: discord.gg/lyzr
• Email: [email protected]

License

MIT License - see LICENSE