Agent

What is LuaAgent?

LuaAgent is the main configuration object for your entire AI agent. It brings together your persona, skills, webhooks, jobs, and message processors in one unified structure.

Think of it as:

The “brain” of your AI - where you define who the agent is, what it can do, and how it behaves

LuaAgent replaces the old pattern of exporting individual skills. It’s now the recommended way to configure agents.

Why LuaAgent?

Single Source of Truth

All agent configuration in one place instead of scattered exports

Better Organization

Clear separation between persona, skills, webhooks, jobs, and processors

State Tracking

Component IDs and versions auto-tracked in lua.skill.yaml (do not edit manually)

More Powerful

Support for webhooks, jobs, preprocessors, and postprocessors

Anatomy of an Agent

import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  // Required: Who is this agent?
  name: "customer-support-agent",
  
  // Required: What's its personality and behavior?
  persona: `You are a friendly customer support specialist.
  
Your role:
- Help customers with orders and inquiries
- Use inquiry forms or your knowledge base when structured intake is needed
- Provide accurate information

Communication style:
- Patient and empathetic
- Clear and professional
- Proactive with solutions`,

  
  // Optional: Which LLM to use (default: google/gemini-2.5-flash)
  model: 'openai/gpt-4o',

  // Optional: Skills with tools
  skills: [customerServiceSkill, productSkill],
  
  // Optional: HTTP endpoints for external events
  webhooks: [stripeWebhook, shopifyWebhook],
  
  // Optional: Scheduled automated tasks
  jobs: [dailyReportJob, cleanupJob],
  
  // Optional: Filter messages before processing
  preProcessors: [profanityFilter, rateLimiter],
  
  // Optional: Format responses before sending
  postProcessors: [addDisclaimer, addBranding]
});

The Three Required Elements

1. Name

Unique identifier for your agent:

name: "customer-support-agent"

Best Practices:

Use lowercase with hyphens
Be descriptive and specific
Keep it short (2-4 words)

2. Persona

Defines your agent’s personality, behavior, and capabilities:

persona: `You are Dr. Health, a medical information assistant.

Role: Provide general health information and wellness tips.

Guidelines:
- Always clarify you're not a licensed doctor
- Recommend seeing professionals for serious concerns
- Use clear, non-technical language
- Be empathetic and supportive

Tone: Professional, caring, informative`

Best Practices:

Clearly define the role
List specific capabilities
Set boundaries and limitations
Define communication style
Include do’s and don’ts

3. Skills

At least one skill with tools:

skills: [mySkill]

Without skills, the agent has no capabilities!

Optional Components

Model

Which LLM your agent uses to generate responses:

model: 'openai/gpt-4o'

Use for: Choosing a model with different capabilities, context window, or cost profile. You can also select models dynamically per user or channel. See: Model Selection for available models and dynamic selection patterns.

Welcome Message

First message users see:

Webhooks

HTTP endpoints for external events:

webhooks: [paymentWebhook, orderWebhook]

Use for: Stripe payments, Shopify orders, GitHub events

Jobs

Scheduled automated tasks:

jobs: [dailyReportJob, weeklyCleanupJob]

Use for: Daily reports, cleanup tasks, monitoring

PreProcessors

Filter messages before they reach your agent:

preProcessors: [profanityFilter, businessHoursFilter]

Use for: Spam filtering, routing, validation

PostProcessors

Format responses after agent generation:

postProcessors: [addDisclaimer, addBranding]

Use for: Disclaimers, branding, translation

Real-World Example

Complete agent with all features:

import { 
  LuaAgent, 
  LuaSkill, 
  LuaWebhook, 
  LuaJob,
  PreProcessor,
  PostProcessor 
} from 'lua-cli';

export const agent = new LuaAgent({
  name: "ecommerce-assistant",
  
  persona: `You are Emma, a helpful e-commerce assistant for Acme Store.
  
Your role:
- Help customers find products
- Assist with orders and cart management
- Answer product questions

Communication style:
- Friendly and professional
- Patient and helpful
- Proactive with suggestions

Limitations:
- Cannot modify pricing
- Cannot cancel shipped orders
- Escalate refunds over $100 to manager`,

  skills: [
    productSearchSkill,
    cartManagementSkill,
    orderTrackingSkill
  ],
  
  webhooks: [
    stripePaymentWebhook,
    shopifyOrderWebhook
  ],
  
  jobs: [
    dailySalesReport,
    abandonedCartReminder
  ],
  
  preProcessors: [
    profanityFilter,
    rateLimiter
  ],
  
  postProcessors: [
    addLegalDisclaimer,
    addBrandingFooter
  ]
});

How It All Works Together

User Message
    ↓
PreProcessors (filter/validate)
    ↓
AI Agent (uses Persona)
    ↓
Calls Tools (from Skills)
    ↓
PostProcessors (format/enhance)
    ↓
Response to User

External Events → Webhooks → Trigger Actions
Scheduled Time → Jobs → Automated Tasks

Try Your Agent

Every agent gets a free, hosted chat page on HeyLua — no setup, no embedding, no code. It’s the fastest way to talk to your agent, share it with teammates, or demo it to others. Just open the agent chat page and pass your agent’s ID:

https://heylua.ai/agent?agentId=<your-agent-id>

A Lua agent running on its free hosted chat page

The hosted page is fully branded with your agent’s name, icon, and welcome message, and shows starter prompts to help users begin the conversation.

This also works for Spaces — pass a Space ID as the agentId and the hosted page will coordinate all of the Space’s supervised agents in one conversation.

Next Steps

Skills Concept

Learn about organizing tools into skills

Tools Concept

Understand individual tools

Webhooks Concept

Learn about HTTP endpoints

Jobs Concept

Understand scheduled tasks

Full API Reference

Complete LuaAgent API documentation

Build Your First Agent

Step-by-step tutorial

Welcome

Build with AI

Key Concepts

Featured Demos

What is LuaAgent?

Think of it as:

Why LuaAgent?

Single Source of Truth

Better Organization

State Tracking

More Powerful

Anatomy of an Agent

The Three Required Elements

1. Name

2. Persona

3. Skills

Optional Components

Model

Welcome Message

Webhooks

Jobs

PreProcessors

PostProcessors

Real-World Example

How It All Works Together

Try Your Agent

Next Steps

Skills Concept

Tools Concept

Webhooks Concept

Jobs Concept

Full API Reference

Build Your First Agent

​What is LuaAgent?

Think of it as:

​Why LuaAgent?

Single Source of Truth

Better Organization

State Tracking

More Powerful

​Anatomy of an Agent

​The Three Required Elements

​1. Name

​2. Persona

​3. Skills

​Optional Components

​Model

​Welcome Message

​Webhooks

​Jobs

​PreProcessors

​PostProcessors

​Real-World Example

​How It All Works Together

​Try Your Agent

​Next Steps

Skills Concept

Tools Concept

Webhooks Concept

Jobs Concept

Full API Reference

Build Your First Agent

What is LuaAgent?

Why LuaAgent?

Anatomy of an Agent

The Three Required Elements

1. Name

2. Persona

3. Skills

Optional Components

Model

Welcome Message

Webhooks

Jobs

PreProcessors

PostProcessors

Real-World Example

How It All Works Together

Try Your Agent

Next Steps