Template Overview

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

Minimal (Default)
With Examples

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

lua init --with-examples

Creates a full project with 30+ working examples:

your-project/
├── src/
│   └── index.ts          # Agent configuration
├── examples/             # 👈 Example code
│   ├── skills/           # Example skills & tools
│   ├── webhooks/         # Example HTTP endpoints
│   ├── jobs/             # Example scheduled tasks
│   ├── preprocessors/    # Example message filters
│   └── postprocessors/   # Example response formatters
├── lua.skill.yaml
├── package.json
└── tsconfig.json

Best for: New users who want to learn by example

Quick Start (Minimal Template)

Initialize Your Project

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

Chat with Your Agent

lua chat

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

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}!` };
    }
}

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()],
});

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],
});

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

Platform APIs
External APIs
Advanced Patterns

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)

GetWeatherTool.ts - External HTTP API integration
PaymentTool.ts - Stripe payment links
CreatePostTool.ts - Simple POST request example

SmartBasketTool.ts - Dynamic job creation from tools
GameScoreTrackerTool.ts - Interval jobs that self-deactivate

Example Webhooks

HTTP endpoints for external integrations:

File	Purpose
`PaymentWebhook.ts`	Stripe payment notifications
`UserEventWebhook.ts`	External events + WhatsApp templates

Example Jobs

Scheduled background tasks:

File	Schedule Type
`HealthCheckJob.ts`	Interval (every 5 minutes)
`DailyCleanupJob.ts`	Cron (daily at 2 AM)
`DataMigrationJob.ts`	One-time (specific date)
`AbandonedBasketProcessorJob.ts`	Interval (batch processing)

Example Processors

Type	File	Purpose
Pre	`messageMatching.ts`	Modify/block incoming messages
Post	`modifyResponse.ts`	Transform 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

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Template Overview

What You Get

Empty Agent

TypeScript Setup

Ready to Deploy

Quick Start Guide

Minimal vs Full Template

Quick Start (Minimal Template)

Examples (—with-examples)

Example Skills & Tools

Example Webhooks

Example Jobs

Example Processors

Using the Examples

Copy What You Need

Move the Entire Structure

Key Files

src/index.ts

lua.skill.yaml

Next Steps

Build Your First Skill

Project Structure

API Reference

Best Practices

​What You Get

Empty Agent

TypeScript Setup

Ready to Deploy

Quick Start Guide

​Minimal vs Full Template

​Quick Start (Minimal Template)

​Examples (—with-examples)

​Example Skills & Tools

​Example Webhooks

​Example Jobs

​Example Processors

​Using the Examples

​Copy What You Need

​Move the Entire Structure

​Key Files

​src/index.ts

​lua.skill.yaml

​Next Steps

Build Your First Skill

Project Structure

API Reference

Best Practices

What You Get

Minimal vs Full Template

Quick Start (Minimal Template)

Examples (—with-examples)

Example Skills & Tools

Example Webhooks

Example Jobs

Example Processors

Using the Examples

Copy What You Need

Move the Entire Structure

Key Files

src/index.ts

lua.skill.yaml

Next Steps