Overview
LuaAgent is the recommended way to configure your AI agent in modern lua-cli. It provides a single, intuitive configuration object that combines skills, webhooks, jobs, and message processors.
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.Agent configuration object
Configuration Parameters
Required Fields
Agent identifier used for organization and loggingExamples:
'customer-support-agent', 'sales-assistant'Defines the agent’s personality, behavior, tone, and capabilitiesString form (recommended):
- Who the agent is
- What role they play
- How they should communicate
- What they can and cannot do
- Any specific behaviors or rules
base— Always rendered, on every channelvoice— Appended tobaseon voice channels, ignored on texttext— Appended tobaseon text channels (web, WhatsApp, SMS), ignored on voice
Optional Fields
Array of skills (tool collections) the agent can useDefault:
[]HTTP endpoints that can receive external eventsDefault:
[]Scheduled tasks that run automaticallyDefault:
[]Functions that process messages before they reach the agentDefault:
[]Functions that process agent responses before sending to usersDefault:
[]The LLM your agent uses. Either a static Static model:Dynamic resolver — receives the full request with all platform APIs available (See: Model Selection
'provider/model' string or a resolver function
that selects the model dynamically per request.Format: 'provider/model' — e.g. 'google/gemini-2.5-flash', 'openai/gpt-4o'Default: 'google/gemini-2.5-flash'Lua manages the API credentials — you don’t need to configure any API keys.
Support for user-provided API keys is coming in a future release.
User, Baskets, Products, etc.):Per-call sampling settings forwarded to the model on every chat turn.
Set them once on the agent instead of overriding them in every skill via
Supported fields:
Obviously-broken values (non-finite numbers,
AI.generate({ temperature }). Undefined leaves provider defaults in
place.| Field | Type | Range / Notes |
|---|---|---|
temperature | number | 0–2 (provider-dependent; typical for OpenAI / Anthropic) |
topP | number | 0–1. Set either temperature or topP, not both. |
topK | number | Top-K sampling (advanced) |
maxOutputTokens | number | Maximum tokens to generate |
presencePenalty | number | -2–2 (OpenAI; not all providers support) |
frequencyPenalty | number | -2–2 (OpenAI; not all providers support) |
stopSequences | string[] | Generation halts when the model emits one |
seed | number | Random seed for deterministic sampling (provider support varies) |
temperature outside 0..2,
topP outside 0..1, non-positive maxOutputTokens, non-string
stopSequences) are rejected at construction time. Provider-specific
range checks are deferred to the provider.Basic Example
Complete Example
Persona Best Practices
✅ Good Persona
❌ Bad Persona
Persona Storage
Persona is stored in yourLuaAgent 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
With All Components
Dynamic Configuration
Migration from v2.x
Before (v2.x):Related APIs
LuaSkill
Tool collections
LuaTool
Individual tools
LuaWebhook
HTTP endpoints
LuaJob
Scheduled tasks
LuaMCPServer
External MCP tools

