LuaAgent

LuaAgent is the object your project exports from src/index.ts: it names the agent, holds its persona and model, and registers every primitive the compiler bundles. lua compile looks for new LuaAgent({ … }) in index.ts, src/index.ts, agent.ts, src/agent.ts, main.ts, then src/main.ts, and compiles only the primitives referenced from that object’s arrays. Pass the config as an object literal directly to the constructor; a config held in a variable isn’t traversed, so its primitives aren’t compiled. Verified against lua-cli 3.33.0.

import { LuaAgent } from 'lua-cli';

Quick example

src/index.ts

import { LuaAgent } from 'lua-cli';
import ordersSkill from './skills/orders.skill';
import dailyDigest from './jobs/DailyDigestJob';
import orderPaid from './webhooks/OrderPaidWebhook';

export default new LuaAgent({
  name: 'shop-assistant',
  description: 'Answers order, delivery, and returns questions for Acme customers.',
  persona: 'You are the Acme support agent. Be concise and confirm order numbers before acting.',
  model: 'openai/gpt-5.4',
  modelSettings: { temperature: 0.2, reasoning: { effort: 'low' } },
  skills: [ordersSkill],
  jobs: [dailyDigest],
  webhooks: [orderPaid],
});

lua push agent uploads this configuration; the primitives in the arrays are pushed with their own lua push <type> commands or together with lua push all.

Constructor

new LuaAgent(config: LuaAgentConfig)

The constructor throws when:

persona is an object with none of base, voice, text: Agent persona object must have at least one of: base, voice, text
modelSettings.temperature is outside 0 to 2: Agent modelSettings.temperature must be between 0 and 2
modelSettings.topP is outside 0 to 1: Agent modelSettings.topP must be between 0 and 1
modelSettings.maxOutputTokens is less than 1: Agent modelSettings.maxOutputTokens must be >= 1
temperature, topP, topK, maxOutputTokens, presencePenalty, frequencyPenalty, or seed is not a finite number: Agent modelSettings.<key> must be a finite number
modelSettings.stopSequences is not an array of strings: Agent modelSettings.stopSequences must be a string array
modelSettings.reasoning is not an object, its effort is not one of the six values, or its show is not a boolean: Agent modelSettings.reasoning must be an object, Agent modelSettings.reasoning.effort must be one of: off, minimal, low, medium, high, max, Agent modelSettings.reasoning.show must be a boolean

name and a string persona are not validated; lua compile warns Agent should have a persona when the persona is empty.

Configuration

Fields of LuaAgentConfig, in declaration order.

string

required

Agent name shown in the compiled manifest and in CLI output. The platform identifies the agent by the agentId in lua.skill.yaml, not by this name.

string

Summary of what the agent can do, read by a Space when deciding whether to route a request to this agent. The persona owns tone and behavior. Omit it to leave any description set in the admin dashboard untouched; set '' to clear it on the next lua push agent.

PersonaText

required

The prompt text that defines who the agent is and how it behaves. A string, or { base?, voice?, text? } where base is rendered on every channel, voice is appended in voice sessions, and text is appended on text channels. An object needs at least one key.

LuaAgentModel

A model code such as 'openai/gpt-5.4' (list them with lua models list), or a model resolver (request: LuaRequest) => string | Promise<string> that runs on every request with every runtime object available. Omit it to use the platform default model.

model: async (request) => (request.channel === 'whatsapp' ? 'openai/gpt-5.4-mini' : 'openai/gpt-5.4'),

AgentModelSettings

Sampling settings sent with every model call. A key left out keeps the provider’s default. reasoning is the agent-level default; a per-request override wins.

Show keys

number

0 to 2.

number

0 to 1. Set either temperature or topP, not both.

number

Top-K sampling. Provider support varies.

number

At least 1.

number

-2 to 2 where the provider supports it. The range is not checked at construction.

number

-2 to 2 where the provider supports it. The range is not checked at construction.

string[]

Generation stops when the model emits one of them.

number

Deterministic sampling where the provider supports it.

{ effort?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'; show?: boolean }

Default reasoning effort and whether the reasoning trace is returned. show defaults to true. An effort the resolved model doesn’t support is mapped to its nearest tier.

LuaSkill[]

default:"[]"

Skills and, through them, tools.

LuaWebhook[]

default:"[]"

Webhooks.

LuaTrigger[]

default:"[]"

Triggers.

LuaJob[]

default:"[]"

Jobs.

LuaWorkflow[]

default:"[]"

Workflows built with createWorkflow or defineWorkflow. Tools referenced by a workflow’s tool steps are compiled through this array too.

PreProcessor[]

default:"[]"

Preprocessors, run before a message reaches the model.

PostProcessor[]

default:"[]"

Postprocessors, run on the reply before it is sent.

LuaMCPServer[]

default:"[]"

MCP servers.

LuaDevice[]

default:"[]"

Devices.

LuaDeviceTrigger[]

default:"[]"

Standalone device triggers.

LuaVoice[]

Voices the agent can answer with. A channel picks one in its channel configuration; without a binding the first entry is used.

BatchingConfig

Message batching for this agent. A key left out falls back to the platform default.

Show keys

number

How long to hold the first message so rapid follow-ups join the same batch. 0 disables the hold.

number

Window for collecting further messages while a turn is in flight. 0 disables batching.

number

Maximum messages in one batch.

boolean

default:"false"

When true, a message arriving mid-turn waits for the current turn instead of aborting it. No effect when debounceWindowMs is 0.

GovernanceConfig

Governance policy for tool calls, preprocessors, and postprocessors. The credential for 'api' mode is read from the GOVERNANCE_API_KEY environment variable, never from this object.

Show keys

'sdk' | 'api'

required

'sdk' enforces preset, injection, and rules in the runtime; 'api' defers to the server at serverUrl.

'security'

Named baseline rule set, layered under rules.

{ threshold: number; ml?: boolean; mlThreshold?: number }

Prompt-injection scan on inputs. ml: true adds the platform’s classifier with its own mlThreshold.

{ blockTools?: string[]; requireToolApproval?: string[]; tokenBudget?: number }

Tool names to block, tool names that need human approval, and a token budget. requireApproval is a deprecated spelling of requireToolApproval.

string

Enforcement server for 'api' mode.

boolean | BrowserSwitchConfig

Browser tools for the agent, off by default. true turns them on with platform defaults; an object adds policy.

Show keys

'auto' | 'browser-use' | 'agent-browser'

'auto' lets the platform pick a local desktop browser or the cloud engine.

string[]

Domains the browser may navigate to or request.

string[]

Names of vault credential entries the agent may use. Never raw secrets.

number

Hard cap on one browser session.

Methods

Read-only getters that return what was passed to the constructor.

Method	Returns
`getName()`	`string`
`getDescription()`	`string \| undefined`
`getBrowser()`	`boolean \| BrowserSwitchConfig \| undefined`
`getPersona()`	`PersonaText`
`getModel()`	`LuaAgentModel \| undefined`
`getModelSettings()`	`AgentModelSettings \| undefined`
`getSkills()`, `getWebhooks()`, `getTriggers()`, `getJobs()`, `getWorkflows()`, `getPreProcessors()`, `getPostProcessors()`, `getMCPServers()`, `getDevices()`	The registered array, `[]` when unset
`getBatching()`	`BatchingConfig \| undefined`
`getVoices()`	`LuaVoice[] \| undefined`

There is no getter for deviceTriggers or governance.

Types

LuaAgentConfig, LuaAgentModel, PersonaText, AgentModelSettings, and LuaRequest are exported types. BatchingConfig, GovernanceConfig, and BrowserSwitchConfig are declared inline; derive them from the config type.

import type { LuaAgentConfig, LuaAgentModel, PersonaText, AgentModelSettings } from 'lua-cli';

type BatchingConfig = NonNullable<LuaAgentConfig['batching']>;
type GovernanceConfig = NonNullable<LuaAgentConfig['governance']>;
type BrowserSwitchConfig = Exclude<NonNullable<LuaAgentConfig['browser']>, boolean>;

SDK

CLI

REST API

Quick example

Constructor

Configuration

Methods

Types

See also

​Quick example

​Constructor

​Configuration

​Methods

​Types

​See also

Quick example

Constructor

Configuration

Methods

Types

See also