🤖 Lua AI Agent

Welcome to your Lua AI Agent! This is a minimal project ready for you to build your custom agent.

🚀 Quick Start

# 1. Test your agent (sandbox mode)
lua chat

# 2. Create your first tool
# See "Creating Your First Tool" below

# 3. Deploy to production
lua push all --force --auto-deploy

📁 Project Structure

your-project/
├── src/
│   └── index.ts          # Your agent configuration
├── lua.skill.yaml        # State manifest (IDs + versions only; auto-managed)
├── package.json          # Dependencies
└── tsconfig.json         # TypeScript config

🛠️ Creating Your First Tool

1. Create the tool file

mkdir -p src/skills/tools

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().describe('The name of the person to greet'),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    return {
      greeting: `Hello, ${input.name}! How can I help you today?`,
    };
  }
}

2. Create a skill to group your tools

Create src/skills/greeting.skill.ts:

import { LuaSkill } from 'lua-cli';
import GreetingTool from './tools/GreetingTool';

const greetingSkill = new LuaSkill({
  name: 'greeting-skill',
  description: 'Tools for greeting users',
  context: 'Use these tools when the user wants to be greeted',
  tools: [new GreetingTool()],
});

export default greetingSkill;

3. Add the skill 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],
});

4. Test it!

lua test      # Test the tool directly
lua chat      # Chat with your agent

📖 Essential Commands

Command	Purpose
lua test	Test individual tools interactively
lua chat	Interactive chat with your agent
lua compile	Compile your code
lua push	Upload to server
lua deploy	Deploy to production
lua logs	View execution logs

🎯 Want Examples?

Initialize a new project with example code:

mkdir my-project-with-examples && cd my-project-with-examples
lua init --with-examples

This includes:

• ✅ 30+ example tools
• ✅ Example webhooks (HTTP endpoints)
• ✅ Example scheduled jobs
• ✅ Example pre/post processors
• ✅ Working e-commerce flow (products, baskets, orders)

📚 Learn More

• Documentation: https://docs.heylua.ai
• Examples: https://docs.heylua.ai/examples
• API Reference: https://docs.heylua.ai/api

💡 Tips

1. Use Zod schemas - They provide type safety and help the AI understand your tool inputs
2. Write clear descriptions - The AI reads these to decide when to use your tools
3. Test in sandbox first - Use lua chat with sandbox mode before deploying
4. Keep tools focused - Each tool should do one thing well

---

Built with Lua CLI