Skip to main content

​
What You Get

When you run lua init, you get a minimal, clean project ready for you to build your agent:

Empty Agent

A clean slate - no example code cluttering your project

TypeScript Setup

Full type safety and configuration included

Ready to Deploy

All configuration files in place

Quick Start Guide

Step-by-step instructions included

​
Minimal vs Full Template

lua init
Creates a clean project with just the essentials:
your-project/
├── src/
│   └── index.ts          # Empty agent ready to customize
├── lua.skill.yaml        # Configuration
├── package.json          # Dependencies
└── tsconfig.json         # TypeScript config
Best for: Experienced developers who want a clean slate

​
Quick Start (Minimal Template)

1

Initialize Your Project

mkdir my-agent && cd my-agent
lua init
2

Chat with Your Agent

lua chat
Select sandbox mode. Your agent works out of the box!
3

Create Your First Tool

Create src/skills/tools/GreetingTool.ts:
import { LuaTool } from "lua-cli";
import { z } from "zod";

export default class GreetingTool implements LuaTool {
    name = "greet_user";
    description = "Generate a personalized greeting";
    
    inputSchema = z.object({
        name: z.string()
    });

    async execute(input: z.infer<typeof this.inputSchema>) {
        return { greeting: `Hello, ${input.name}!` };
    }
}
4

Create a Skill

Create src/skills/greeting.skill.ts:
import { LuaSkill } from "lua-cli";
import GreetingTool from "./tools/GreetingTool";

export default new LuaSkill({
    name: "greeting-skill",
    description: "Greeting tools",
    context: "Use when users want greetings",
    tools: [new GreetingTool()],
});
5

Add to Your Agent

Update src/index.ts:
import { LuaAgent } from "lua-cli";
import greetingSkill from "./skills/greeting.skill";

const agent = new LuaAgent({
    name: `My Agent`,
    persona: `You are a friendly assistant.`,
    skills: [greetingSkill],
});
6

Test & Deploy

lua test                           # Test your tool
lua chat                           # Chat with your agent
lua push all --force --auto-deploy # Deploy

​
Examples (—with-examples)

When you use lua init --with-examples, you get comprehensive examples:

​
Example Skills & Tools

  • UserDataTool.ts - User API (get/update user data)
  • ProductsTool.ts - Products API (CRUD operations)
  • BasketTool.ts - Baskets API (shopping cart)
  • OrderTool.ts - Orders API (order management)
  • CustomDataTool.ts - Data API (custom collections + semantic search)

​
Example Webhooks

HTTP endpoints for external integrations:
FilePurpose
PaymentWebhook.tsStripe payment notifications
UserEventWebhook.tsExternal events + WhatsApp templates

​
Example Jobs

Scheduled background tasks:
FileSchedule Type
HealthCheckJob.tsInterval (every 5 minutes)
DailyCleanupJob.tsCron (daily at 2 AM)
DataMigrationJob.tsOne-time (specific date)
AbandonedBasketProcessorJob.tsInterval (batch processing)

​
Example Processors

TypeFilePurpose
PremessageMatching.tsModify/block incoming messages
PostmodifyResponse.tsTransform agent responses

​
Using the Examples

​
Copy What You Need

# Initialize with examples
lua init --with-examples

# Copy a tool to your src
cp examples/skills/tools/GetWeatherTool.ts src/skills/tools/

# Import and use it

​
Move the Entire Structure

# Move all examples into your src
mv examples/skills src/
mv examples/webhooks src/
mv examples/jobs src/

​
Key Files

​
src/index.ts

Your agent’s main configuration: 
import { LuaAgent } from "lua-cli";

const agent = new LuaAgent({
    name: `your-agent-name`,
    persona: `Your agent's personality...`,
    skills: [],        // Add your skills here
    // webhooks: [],   // Optional: HTTP endpoints
    // jobs: [],       // Optional: Scheduled tasks
});

​
lua.skill.yaml

Auto-managed configuration file: 
agent:
  agentId: agent_abc123
  orgId: org_xyz789
  persona: "..."

skills:
  - name: my-skill
    version: 1.0.0
    skillId: skill_xyz  # Auto-created
Don’t manually edit skillId, webhookId, or jobId - they’re auto-managed by the CLI!

​
Next Steps

Build Your First Skill

Step-by-step tutorial

Project Structure

Understanding file organization

API Reference

Available platform APIs

Best Practices

Tips for building great agents