SDK overview

lua-cli is one npm package: the lua command and the TypeScript SDK your agent code imports. Every symbol on this page is exported from the package root, 'lua-cli'; three subpaths cover voice models, voice tests, and the workflow builder. Runtime objects such as Data and User are typed by the package and injected by the platform when your code runs, so the import exists for type-checking and for lua test. Verified against lua-cli 3.33.0.

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

Quick example

One tool, one skill, one agent, and one runtime object in a single file.

src/index.ts

import { LuaAgent, LuaSkill, LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

class LookupOrderTool implements LuaTool {
  name = 'lookup_order';
  description = 'Look up an order by its number';
  inputSchema = z.object({ orderNumber: z.string() });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const page = await Data.get('orders', { orderNumber: { $eq: input.orderNumber } }, 1, 1);
    return page.data[0] ?? { found: false };
  }
}

export default new LuaAgent({
  name: 'shop-assistant',
  persona: 'You help customers of Acme with their orders.',
  skills: [
    new LuaSkill({
      name: 'orders',
      description: 'Order lookups',
      context: 'Use lookup_order when the customer asks about an order.',
      tools: [new LookupOrderTool()],
    }),
  ],
});

Package subpaths

Subpath	Exports	Used for
`lua-cli`	Everything listed on this page	Agent code: primitives, runtime objects, types
`lua-cli/voice`	`deepgram`, `elevenlabs`, `openai`, `google`, `xai`, `inference`	Class-form voice models inside a `defineVoice` config
`lua-cli/voice/test`	`runVoice`, `expectContainsMessage`, `expectCalledTool`, `expectContainsHandoff`, `judge`, `expectJudge`, `llm`, `voice`; types `TestSession`, `RunVoiceOptions`, `JudgeOptions`	Voice test files run by `lua voice test`
`lua-cli/workflow-builder`	The workflow builder values and types listed under Exports, plus `WORKFLOW_DEFAULT_MAX_DURATION_SECONDS` and `WORKFLOW_HITL_MAX_DURATION_SECONDS`	Workflow files that import the builder without the rest of the SDK

There is no lua-cli/skill subpath and no defineTool, defineSkill, defineWebhook, or defineJob export. Tools, skills, webhooks, jobs, processors, and MCP servers are classes; the define* helpers exist only for triggers, devices, device triggers, voices, and workflows.

Exports

Primitive classes and define helpers

Export	Kind	Reference
`LuaAgent`	class	LuaAgent
`LuaSkill`	class	LuaSkill
`ToolFlag`	enum	LuaTool
`LuaWebhook`	class	LuaWebhook
`LuaTrigger`, `defineTrigger`	class, function	LuaTrigger
`LuaJob`	class	LuaJob
`PreProcessor` (alias `LuaPreprocessor`)	class	PreProcessor
`PostProcessor` (alias `LuaPostprocessor`)	class	PostProcessor
`LuaMCPServer`	class	LuaMCPServer
`LuaDevice`, `defineDevice`, `LuaDeviceTrigger`, `defineDeviceTrigger`	class, function	defineDevice and defineDeviceTrigger
`LuaVoice`, `LuaVoiceTool`, `defineVoice`	class, function	defineVoice

Runtime objects

Export	Reference
`User` (with `User.Inbox`)	User, Inbox
`Data`	Data
`Products`, `Baskets`, `Orders`, `BasketStatus`, `OrderStatus`	Products, Baskets, Orders
`Jobs`	Jobs
`Workflows`	Workflows
`AI`	AI
`Agents`	Agents
`Integrations`	Integrations
`Voice`	Voice runtime
`Channels`, `CHANNEL_SEND_CHANNELS`	Channels
`Team`	Team
`Templates`	Templates
`CDN`	CDN
`Lua`	Lua
`env`	env

Workflow builder

Values: LuaWorkflow, LuaWorkflowBuildError, createWorkflow, createStep, defineWorkflow, step, stepOf, init, state, lit, eq, ne, gt, gte, lt, lte, inSet, notIn, exists, notExists, truthy, falsy, and, or, not, fromInit, fromStep, value, template, fromRequest, rows, fromKnowledge. Each is documented on Workflow builder.

Instance classes

JobInstance, UserDataInstance, DataEntryInstance, ProductInstance, BasketInstance, OrderInstance are the classes runtime methods return. Their members are listed on Types.

Type-only exports

Import these with import type; nothing is emitted at runtime.

Area	Types
Primitives	`LuaTool`, `LuaAgentConfig`, `LuaAgentModel`, `PersonaText`, `AgentModelSettings`, `LuaWebhookConfig`, `LuaTriggerConfig`, `TriggerContext`, `LuaJobConfig`, `JobSchedule`, `PreProcessorConfig`, `PreProcessorAction`, `PreProcessorResult`, `PreProcessorBlockResponse`, `PreProcessorProceedResponse`, `PostProcessorConfig`, `PostProcessorResponse`, `LuaMCPServerConfig`, `MCPSSEServerConfig`, `MCPStreamableHttpServerConfig`, `MCPTransport`, `MCPServerBaseConfig`, `LuaDeviceConfig`, `DeviceCommandConfig`, `DeviceTriggerConfig`, `LuaDeviceTriggerConfig`, `LuaVoiceConfig`, `LuaVoiceToolConfig`, `LuaVoiceToolCtx`, `LuaVoiceHookContext`, `LuaVoiceTurnContext`
Messages	`ChatMessage`, `TextMessage`, `ImageMessage`, `FileMessage`, `ChatHistoryMessage`, `ChatHistoryContent`, `PreProcessorOverride`, `PostProcessorOverride`
Runtime and end users	`Channel`, `LuaRuntime`, `LuaRequest`, `WebhookRequest`, `UserLookupOptions`, `ProfileResponse`
Runtime object interfaces	`AgentsApi`, `AiApi`, `ChannelsApi`, `IntegrationsApi`, `TeamApi`, `VoiceApi`, `WorkflowsApi` — the types of `Agents`, `AI`, `Channels`, `Integrations`, `Team`, `Voice`, and `Workflows`
Data and AI	`LuaQuery`, `LuaQueryFieldOperators`, `LuaQueryScalar`, `AiGenerateInput`, `AiGenerateOutput`, `AiGenerateStructuredOutput`, `AiGenerateJsonSchema`, `AiGenerateSource`, `AiGenerateToolCall`, `AiGenerateToolResult`
Channels and templates	`ChannelSendChannel`, `ChannelSendTarget`, `ChannelSendOptions`, `ChannelSendInput`, `ChannelSendOutput`, `WhatsAppTemplateSendInput`, `WhatsAppReactionSendInput`, `EmailSendInput`, `DeliveryView`, `DeliveryStatus`, `DeliveryErrorCategory`, `DeliveryError`, `DeliveryListFilter`, `WhatsAppTemplate`, `PaginatedTemplatesResponse`, `ListTemplatesOptions`, `SendTemplateData`, `SendTemplateResponse`, `SendTemplateValues`, `WhatsAppTemplateCategory`, `WhatsAppTemplateStatus`, `WhatsAppTemplateComponent`
Integrations and team	`IntegrationPassthroughMethod`, `IntegrationPassthroughRequest`, `IntegrationPassthroughResponse`, `DirectoryTarget`, `DirectoryMatch`, `DirectoryResolveResult`
Workflows	`LuaWorkflowConfig`, `LuaWorkflowBuilder`, `LuaWorkflowStep`, `LuaWorkflowBuildCode`, `LuaWorkflowBuildWarning`, `WorkflowStepContext`, `WorkflowStepResultError`, `WorkflowExec`, `WorkflowShell`, `WorkflowShellValue`, `WorkflowExecOptions`, `WorkflowExecResult`, `WorkflowExecError`, `WorkflowExecErrorCode`, `WorkflowExecRefusalReason`, `WorkflowExecBinary`, `WorkflowArtefactMeta`, `WorkflowGoalEnvelope`, `WorkflowRunTrigger`, `RetryPolicy`, `StepRef`, `ContainerArm`, `AgentStepOptions`, `SpecialistStepOptions`, `ToolStepOptions`, `NestedWorkflowOptions`, `ApprovalOptions`, `WaitForSignalOptions`, `ForeachOptions`, `LoopOptions`, `TemplateLike`, `DotPath`, `PathValue`, `StepPathRef`, `ReplyChannel`, `WorkflowJobToolId`, `WorkflowJobHarness`, `WorkflowWorkspaceBackend`, `WorkflowSpecialistRole`, `WorkflowApproverSpec`, `WorkflowSuspendTimeoutChain`, `WorkflowSuspendTimeoutChainMember`, `WorkflowFourEyes`, `WorkflowBusinessHours`, `WorkflowStepWorkspace`, `WorkflowMergePolicy`, `WorkflowSuspendOnTimeout`, `WorkflowOutputVisibility`, `WorkspaceSpec`, `AgentToolScope`, `ArtefactRef`, `DatasetRef`, `EnvRefBinding`, `JsonSchema`, `KnowledgeBindingSpec`, `Literal`, `LuaMapConfig`, `LuaPredicate`, `MapDescriptor`, `PathOrLiteral`, `SerializedWorkflowGraph`, `TemplateBinding`, `TypedRef`

Some shapes the typings use are declared without a named export: LuaSkillConfig, LuaToolCtx, LuaWebhookEvent, TriggerStartWorkflow, SkillContextText, BatchingConfig, GovernanceConfig, and BrowserSwitchConfig. Write them inline or derive them from the exported types.

import type { LuaSkill, LuaTool, LuaAgentConfig, LuaWebhookConfig } from 'lua-cli';

type LuaSkillConfig = ConstructorParameters<typeof LuaSkill>[0];
type LuaToolCtx = NonNullable<Parameters<LuaTool['execute']>[1]>;
type LuaWebhookEvent = Parameters<LuaWebhookConfig['execute']>[0];
type BatchingConfig = NonNullable<LuaAgentConfig['batching']>;

Availability

The platform injects the runtime objects into every execution context that runs your code; what differs is whether an end user is in scope.

Context	End user in scope	Notes
Tool `execute` and `condition`, skill `condition`, preprocessor, postprocessor, model resolver	Yes	`User.get()` with no argument is the person in the conversation
Webhook `execute`, job `execute`	No	Pass an ID: `User.get(userId)`. `User.Inbox.push` throws `Inbox.push requires a user context`
Trigger `verify`, `filter`, `transform`, `tool.input`	No	`env()` works; the slots share a 15-second budget. See LuaTrigger
Workflow code step	Depends on the run	See Workflows

Workflows and Integrations.passthrough throw a typed error when the runtime they run in has no connection to those services. The rules per context are on About execution contexts.

Runtime lag

Local runs only. These members type-check and pass in lua test but the deployed runtime doesn’t accept them yet; each linked page carries the workaround.

Data.create(collection, data, { searchText, index }) and the matching Data.update options object. The deployed runtime takes searchText as a plain string in that position and fails the object form with searchText must be a string. See Data.
Data.collections() is not available in the deployed runtime.
Voice.createSession() is not available in the deployed runtime; Voice.call() is. See Voice runtime.
JobInstance.execution is the reverse case: set in the deployed runtime, undefined in lua test, and absent from the type. See Jobs.

SDK

CLI

REST API

Quick example

Package subpaths

Exports

Primitive classes and define helpers

Runtime objects

Workflow builder

Instance classes

Type-only exports

Availability

Runtime lag

See also

​Quick example

​Package subpaths

​Exports

​Primitive classes and define helpers

​Runtime objects

​Workflow builder

​Instance classes

​Type-only exports

​Availability

​Runtime lag

​See also

Quick example

Package subpaths

Exports

Primitive classes and define helpers

Runtime objects

Workflow builder

Instance classes

Type-only exports

Availability

Runtime lag

See also