Skip to main content

Overview

LuaAgent is the recommended way to configure your AI agent in v3.0.0+. It provides a single, intuitive configuration object that combines skills, webhooks, jobs, and message processors.
import { LuaAgent } from 'lua-cli';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: 'You are a helpful assistant...',
  skills: [skill1, skill2]
});
New in v3.0.0: LuaAgent replaces the need to export individual skills, webhooks, and jobs separately.

Why LuaAgent?

Single Source of Truth

All agent components in one configuration object

Auto-Sync

CLI auto-manages lua.skill.yaml (do not edit manually)

Better IDE Support

Improved autocomplete and type safety

Clear Organization

Organized, readable agent configuration

Constructor

new LuaAgent(config)

Creates a new agent configuration.
config
LuaAgentConfig
required
Agent configuration object

Configuration Parameters

Required Fields

name
string
required
Agent identifier used for organization and loggingExamples: 'customer-support-agent', 'sales-assistant'
persona
string
required
Defines the agent’s personality, behavior, tone, and capabilitiesShould include:
  • Who the agent is
  • What role they play
  • How they should communicate
  • What they can and cannot do
  • Any specific behaviors or rules

Optional Fields

skills
LuaSkill[]
Array of skills (tool collections) the agent can useDefault: []
webhooks
LuaWebhook[]
HTTP endpoints that can receive external eventsDefault: []
jobs
LuaJob[]
Scheduled tasks that run automaticallyDefault: []
preProcessors
PreProcessor[]
Functions that process messages before they reach the agentDefault: []
postProcessors
PostProcessor[]
Functions that process agent responses before sending to usersDefault: []
mcpServers
LuaMCPServer[]
MCP (Model Context Protocol) servers providing external toolsDefault: []See: LuaMCPServer API

Basic Example

import { LuaAgent, LuaSkill } from 'lua-cli';
import GetWeatherTool from './tools/GetWeatherTool';

const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather information',
  context: 'Use these tools to get weather data',
  tools: [new GetWeatherTool()]
});

export const agent = new LuaAgent({
  name: 'weather-assistant',
  persona: 'You are a friendly weather assistant. Provide weather information when asked.',
  skills: [weatherSkill]
});

Complete Example

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

// Import your components
import { customerSupportSkill } from './skills/customer-support';
import { productSkill } from './skills/products';
import { orderSkill } from './skills/orders';
import paymentWebhook from './webhooks/payment';
import orderWebhook from './webhooks/order';
import dailyReportJob from './jobs/daily-report';
import cleanupJob from './jobs/cleanup';
import profanityFilter from './preprocessors/profanity-filter';
import addDisclaimer from './postprocessors/disclaimer';
import filesystemServer from './mcp/filesystem';

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
- Process returns and exchanges

Communication style:
- Friendly and professional
- Patient and understanding
- Proactive with suggestions
- Clear and concise

Capabilities:
- Search product catalog
- Manage shopping carts
- Track orders
- Process payments
- Answer product questions

Limitations:
- Cannot ship orders manually
- Cannot modify pricing (suggest contacting manager)
- Cannot issue refunds over $100 (requires manager approval)
`,

  skills: [
    customerSupportSkill,
    productSkill,
    orderSkill
  ],

  webhooks: [
    paymentWebhook,
    orderWebhook
  ],

  jobs: [
    dailyReportJob,
    cleanupJob
  ],

  preProcessors: [
    profanityFilter
  ],

  postProcessors: [
    addDisclaimer
  ],

  mcpServers: [
    filesystemServer
  ]
});

Persona Best Practices

✅ Good Persona

persona: `You are Dr. Smith, 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`

❌ Bad Persona

// Too vague
persona: `You are helpful`

// Too robotic
persona: `I am an AI assistant that answers questions.`

// Missing boundaries
persona: `You can do anything the user asks.`

Persona Storage

Persona is stored in your LuaAgent code definition (in src/index.ts). The lua.skill.yaml file is state-only and tracks IDs and versions, not persona content. When you edit persona using lua persona, it updates the persona field in your LuaAgent code directly.

Multiple Skills Example

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

// Organize tools by domain
const weatherSkill = new LuaSkill({
  name: 'weather-skill',
  description: 'Weather tools',
  context: 'Use for weather queries',
  tools: [getWeatherTool, getForecastTool]
});

const calculatorSkill = new LuaSkill({
  name: 'calculator-skill',
  description: 'Math tools',
  context: 'Use for calculations',
  tools: [addTool, multiplyTool, advancedMathTool]
});

const dataSkill = new LuaSkill({
  name: 'data-skill',
  description: 'Data management',
  context: 'Use for storing and retrieving user data',
  tools: [saveDataTool, queryDataTool]
});

export const agent = new LuaAgent({
  name: 'multi-purpose-assistant',
  persona: 'You are a versatile assistant that helps with weather, calculations, and data management.',
  skills: [weatherSkill, calculatorSkill, dataSkill]
});

With All Components

import { LuaAgent } from 'lua-cli';
import { skills } from './skills';
import { webhooks } from './webhooks';
import { jobs } from './jobs';
import { preProcessors } from './preprocessors';
import { postProcessors } from './postprocessors';
import { mcpServers } from './mcp';

export const agent = new LuaAgent({
  name: 'enterprise-assistant',
  
  persona: `You are an enterprise-grade AI assistant.
  - Professional and efficient
  - Data-driven and accurate
  - Proactive with insights
  - Security and privacy conscious`,
  
  skills: skills,
  webhooks: webhooks,
  jobs: jobs,
  preProcessors: preProcessors,
  postProcessors: postProcessors,
  mcpServers: mcpServers
});

Dynamic Configuration

import { LuaAgent } from 'lua-cli';
import { env } from 'lua-cli';

// Load configuration from environment
const agentName = env('AGENT_NAME') || 'default-agent';
const customPersona = env('AGENT_PERSONA') || 'You are a helpful assistant';

// Conditionally add components
const skills = [coreSkill];
if (env('ENABLE_ANALYTICS') === 'true') {
  skills.push(analyticsSkill);
}

export const agent = new LuaAgent({
  name: agentName,
  persona: customPersona,
  skills: skills,
  // Add webhooks only in production
  webhooks: env('NODE_ENV') === 'production' ? productionWebhooks : []
});

Validation

The LuaAgent automatically validates:
  • ✅ Name is provided and non-empty
  • ✅ Persona is provided and non-empty
  • ✅ All skills are valid LuaSkill instances
  • ✅ All webhooks are valid LuaWebhook instances
  • ✅ All jobs are valid LuaJob instances
  • ✅ All MCP servers are valid LuaMCPServer instances
  • ✅ Tool names are unique across all skills
  • ✅ Component names follow naming conventions

Migration from v2.x

Before (v2.x):
// Multiple exports
export const skill1 = new LuaSkill({...});
export const skill2 = new LuaSkill({...});
export const webhook1 = new LuaWebhook({...});
After (v3.0.0):
// Single export with LuaAgent
export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [skill1, skill2],
  webhooks: [webhook1]
});

See Also