API Overview - Lua CLI

Available APIs

Lua CLI provides a comprehensive set of APIs for building AI agents:

Core Classes

LuaAgent, LuaSkill, LuaTool - Agent configuration and building blocks

Automation

LuaJob, LuaWebhook - Scheduled tasks and HTTP endpoints

Message Processing

PreProcessor, PostProcessor - Filter and format messages

External Tools

LuaMCPServer - Connect MCP servers for external tool integrations

Platform APIs

AI, Agents, User, Data, CDN, Products, Baskets, Orders, Jobs, Templates, Channels - Built-in services

Environment

env() - Secure configuration management

LuaAgent, LuaJob, LuaWebhook, PreProcessor, PostProcessor, and Jobs API for comprehensive agent development.

Installation

npm install lua-cli zod

yarn add lua-cli zod

pnpm add lua-cli zod

zod is a peer dependency required for schema validation

Quick Start

Import APIs

// Core classes
import { 
  LuaAgent, 
  LuaSkill, 
  LuaTool, 
  LuaWebhook, 
  LuaJob,
  LuaMCPServer,
  PreProcessor,
  PostProcessor
} from 'lua-cli';

// Platform APIs
import { AI, Agents, User, Data, CDN, Products, Baskets, Orders, Jobs, Templates, Channels } from 'lua-cli';

// Utilities
import { env } from 'lua-cli';

// Type definitions
import { BasketStatus, OrderStatus } from 'lua-cli';

// Schema validation
import { z } from 'zod';

Create an Agent

import { LuaAgent, LuaSkill, LuaTool } from 'lua-cli';
import { z } from 'zod';

// Define a tool
class MyTool implements LuaTool {
  name = "my_tool";
  description = "What the tool does";
  inputSchema = z.object({
    param: z.string()
  });

  async execute(input: any) {
    return { result: "success" };
  }
}

// Create a skill
const skill = new LuaSkill({
  name: "my-skill",
  description: "My custom skill",
  context: "When to use this skill and its tools",
  tools: [new MyTool()]
});

// Create agent
export const agent = new LuaAgent({
  name: "my-agent",
  persona: "You are a helpful assistant...",
  skills: [skill]
});

Core Classes

Agent Configuration

LuaAgent

Unified agent configuration

new LuaAgent({
  name: "my-agent",
  persona: "...",
  skills: [...],
  webhooks: [...],
  jobs: [...]
})

Building Blocks

LuaSkill

Collection of related tools

new LuaSkill({
  name: "skill-name",
  tools: [...]
})

LuaTool

Individual function the AI can call

class MyTool implements LuaTool {
  name = "tool_name"
  execute(input) { ... }
}

Automation

LuaWebhook

HTTP endpoints for external events

new LuaWebhook({
  name: "payment-webhook",
  execute: async (event) => { ... }
})

LuaJob

Scheduled tasks

new LuaJob({
  name: "daily-report",
  schedule: { type: "cron", pattern: "0 9 * * *" },
  execute: async (job) => { ... }
})

Message Processing

PreProcessor

Filter messages before agent

new PreProcessor({
  name: "profanity-filter",
  execute: async (message, user) => { ... }
})

PostProcessor

Format responses after agent

new PostProcessor({
  name: "add-disclaimer",
  execute: async (user, message, response, channel) => { ... }
})

Platform APIs

AI API

New! Generate AI responses with custom context in your tools:

import { AI } from 'lua-cli';

const response = await AI.generate(
  'You are a helpful sales assistant.',
  [{ type: 'text', text: 'What products do you recommend?' }]
);

Use cases:

Product descriptions
Image analysis
Content summarization
Translation
Recommendations
Document Q&A

Full Documentation

Agents API

New! Invoke another agent from within your tool, webhook, job, or processor:

import { Agents } from 'lua-cli';

// Simplified — returns plain text
const reply = await Agents.invoke('support-agent', 'What is the refund policy?');

// Full options — returns structured output
const result = await Agents.invoke('legal-agent', {
  prompt: 'Review this clause.',
  threadId: 'contract-456',
});
console.log(result.text, result.usage);

Use cases:

Route requests to specialist agents
Build multi-agent pipelines
Delegate from webhooks/jobs to conversational agents

Full Documentation

User API

Access user information:

import { User } from 'lua-cli';

// Get current user (from conversation context)
const user = await User.get();

// Get specific user by ID (useful in webhooks/jobs)
const specificUser = await User.get(userId);

// Direct property access
console.log(user.name);
console.log(user.email);

Use cases:

Get current user in tools
Get specific user in webhooks (payment notifications)
Send messages to specific users in jobs
Update user profiles

Full Documentation

Data API

Custom data storage with vector search:

import { Data } from 'lua-cli';

// Create
await Data.create('collection', data, searchText);

// Search semantically
const results = await Data.search('collection', 'query', 10, 0.7);

// Get/Update/Delete
await Data.get('collection', filter);
await Data.update('collection', id, data);
await Data.delete('collection', id);

Full Documentation

CDN API

Upload and retrieve files from the CDN:

import { CDN } from 'lua-cli';

// Upload a file
const file = new File([buffer], 'image.png', { type: 'image/png' });
const fileId = await CDN.upload(file);

// Get file by ID
const retrievedFile = await CDN.get(fileId);
console.log(retrievedFile.name, retrievedFile.type);

Use cases:

Store user uploads
Image storage for AI analysis
Document management
Asset management

Full Documentation

Products API

E-commerce product catalog:

import { Products } from 'lua-cli';

// Search
const products = await Products.search('laptop');

// CRUD
await Products.create({ name, price });
await Products.update({ price }, id);
await Products.getById(id);
await Products.delete(id);

Full Documentation

Baskets API

Shopping cart management:

import { Baskets, BasketStatus } from 'lua-cli';

// Create basket
const basket = await Baskets.create({ currency: 'USD' });

// Add items
await Baskets.addItem(basket.id, {
  id: productId,
  price: 29.99,
  quantity: 2
});

// Checkout
const order = await Baskets.placeOrder(orderData, basket.id);

Full Documentation

Orders API

Order processing and tracking:

import { Orders, OrderStatus } from 'lua-cli';

// Create order
const order = await Orders.create({
  basketId,
  data: { shippingAddress, paymentMethod }
});

// Update status
await Orders.updateStatus(OrderStatus.FULFILLED, orderId);

Full Documentation

Jobs API

Dynamically create scheduled tasks from tools:

import { Jobs } from 'lua-cli';

// Create a reminder job
const job = await Jobs.create({
  name: 'user-reminder',
  metadata: { message: 'Meeting in 10 minutes' },
  schedule: {
    type: 'once',
    executeAt: new Date(Date.now() + 600000)
  },
  execute: async (jobInstance) => {
    const user = await jobInstance.user();
    await user.send([{
      type: 'text',
      text: jobInstance.metadata.message
    }]);
  }
});

Full Documentation

Templates API

Send template messages across different channels:

import { Templates } from 'lua-cli';

// List WhatsApp templates
const result = await Templates.whatsapp.list(channelId);

// Send template message
await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: ['+447551166594'],
  values: {
    body: { name: 'John', order_number: '12345' }
  }
});

Supported template types:

Templates.whatsapp - WhatsApp Business templates

Full Documentation

Channels API

Send outbound messages on any connected channel — from tools, jobs, webhooks, and triggers:

import { Channels } from 'lua-cli';

// Free-form message on a connected channel
await Channels.send({
  channel: 'whatsapp',
  to: { userId: 'user_123' },
  text: 'Your order has shipped!'
});

// Rich email
await Channels.email.send({
  to: { email: '[email protected]' },
  subject: 'Receipt',
  text: 'Thanks for your order!'
});

// Approved WhatsApp template (start or re-open a conversation)
await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+14155552671' },
  templateName: 'order_update',
  languageCode: 'en_US'
});

Use cases:

Proactive notifications and reminders (with Jobs)
Confirmations from webhooks
Agent-initiated follow-ups

Full Documentation

Environment Variables

Secure configuration management:

import { env } from 'lua-cli';

const apiKey = env('EXTERNAL_API_KEY');
const baseUrl = env('API_BASE_URL') || 'https://default.com';

Full Documentation

Type Definitions

All APIs are fully typed for TypeScript:

import { 
  LuaSkill, 
  LuaTool, 
  BasketStatus, 
  OrderStatus 
} from 'lua-cli';

// Autocomplete and type checking work everywhere
const user = await User.get();  // user is typed
const products = await Products.get(); // products is typed

Common Patterns

External API Integration

export class WeatherTool implements LuaTool {
  name = "get_weather";
  description = "Get current weather";
  inputSchema = z.object({ city: z.string() });

  async execute(input: any) {
    const response = await fetch(
      `https://api.weather.com?city=${input.city}`
    );
    return await response.json();
  }
}

Using Platform APIs

export class ShoppingTool implements LuaTool {
  async execute(input: any) {
    // Search products
    const products = await Products.search(input.query);
    
    // Create basket
    const basket = await Baskets.create({ currency: 'USD' });
    
    // Add item
    await Baskets.addItem(basket.id, {
      id: products.products[0].id,
      price: products.products[0].price,
      quantity: 1
    });
    
    return { basketId: basket.id };
  }
}

Custom Data with Search

export class CreateNoteTool implements LuaTool {
  async execute(input: any) {
    // Create with search indexing
    const note = await Data.create('notes', {
      title: input.title,
      content: input.content
    }, `${input.title} ${input.content}`);
    
    return { noteId: note.id };
  }
}

export class SearchNotesTool implements LuaTool {
  async execute(input: any) {
    // Semantic search
    const results = await Data.search(
      'notes',
      input.query,
      10,
      0.7
    );
    
    return {
      notes: results.map(entry => ({
        id: entry.id,
        title: entry.title,
        content: entry.content,
        relevance: entry.score
      }))
    };
  }
}

API Reference Pages

Core Classes

LuaAgent

Agent configuration

LuaSkill

Skill class API

LuaTool

Tool interface

LuaWebhook

HTTP webhooks

LuaJob

Scheduled tasks

LuaMCPServer

MCP external tools

PreProcessor

Message filtering

PostProcessor

Response formatting

defineDevice

Server-side device + trigger definitions

LuaVoice

Voice agent definition

Runtime APIs

Lua

Request context API

AI

AI generation API

Agents

Agent invocation API

User

User data API

Data

Custom data API

CDN

File storage API

Products

Products API

Baskets

Baskets API

Orders

Orders API

Jobs

Jobs API

Templates

Template messaging

Channels

Outbound messaging

Voice

LuaVoice

Define voices in code — STT, TTS, LLM, plus plugin & realtime engines

Utilities

Environment

Environment utilities

Best Practices

Use TypeScript

All APIs are fully typed. Use TypeScript for:

Autocomplete
Type checking
Better IDE support

Validate Inputs

Always use Zod schemas for input validation:

inputSchema = z.object({
  email: z.string().email(),
  age: z.number().min(0)
});

Handle Errors

Implement proper error handling:

try {
  const result = await api.call();
  return result;
} catch (error) {
  throw new Error(`Operation failed: ${error.message}`);
}

Use Environment Variables

Never hardcode secrets:

const apiKey = env('API_KEY');
if (!apiKey) {
  throw new Error('API_KEY not configured');
}

Next Steps

Explore Core Classes

Learn about LuaSkill and LuaTool

Study Platform APIs

Explore User, Data, Products, etc.

See Examples

Check out Tool Examples for working code

Build Something

Follow the First Skill tutorial

​Available APIs

Core Classes

Automation

Message Processing

External Tools

Platform APIs

Environment

​Installation

​Quick Start

​Import APIs

​Create an Agent

​Core Classes

​Agent Configuration

LuaAgent

​Building Blocks

LuaSkill

LuaTool

​Automation

LuaWebhook

LuaJob

​Message Processing

PreProcessor

PostProcessor

​Platform APIs

​AI API

Full Documentation

​Agents API

Full Documentation

​User API

Full Documentation

​Data API

Full Documentation

​CDN API

Full Documentation

​Products API

Full Documentation

​Baskets API

Full Documentation

​Orders API

Full Documentation

​Jobs API

Full Documentation

​Templates API

Full Documentation

​Channels API

Full Documentation

​Environment Variables

Full Documentation

​Type Definitions

​Common Patterns

​External API Integration

​Using Platform APIs

​Custom Data with Search

​API Reference Pages

​Core Classes

LuaAgent

LuaSkill

LuaTool

LuaWebhook

LuaJob

LuaMCPServer

PreProcessor

PostProcessor

defineDevice

LuaVoice

​Runtime APIs

Lua

AI

Agents

User

Data

CDN

Products

Baskets

Orders

Jobs

Templates

Channels

​Voice

LuaVoice

Available APIs

Installation

Quick Start

Import APIs

Create an Agent

Core Classes

Agent Configuration

Building Blocks

Automation

Message Processing

Platform APIs

AI API

Agents API

User API

Data API

CDN API

Products API

Baskets API

Orders API

Jobs API

Templates API

Channels API

Environment Variables

Type Definitions

Common Patterns

External API Integration

Using Platform APIs

Custom Data with Search

API Reference Pages

Core Classes

Runtime APIs

Voice

Utilities

Best Practices

Next Steps