> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # SDK overview > Every export of the lua-cli package grouped by kind, the three package subpaths, and where each runtime object is available `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.* ```ts theme={null} import { LuaAgent, LuaSkill, LuaTool, Data } from 'lua-cli'; ``` ## Quick example One tool, one skill, one agent, and one runtime object in a single file. ```ts src/index.ts theme={null} 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) { 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`](/reference/sdk/voice) 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](/reference/sdk/luaagent) | | `LuaSkill` | class | [LuaSkill](/reference/sdk/luaskill) | | `ToolFlag` | enum | [LuaTool](/reference/sdk/luatool) | | `LuaWebhook` | class | [LuaWebhook](/reference/sdk/luawebhook) | | `LuaTrigger`, `defineTrigger` | class, function | [LuaTrigger](/reference/sdk/luatrigger) | | `LuaJob` | class | [LuaJob](/reference/sdk/luajob) | | `PreProcessor` (alias `LuaPreprocessor`) | class | [PreProcessor](/reference/sdk/preprocessor) | | `PostProcessor` (alias `LuaPostprocessor`) | class | [PostProcessor](/reference/sdk/postprocessor) | | `LuaMCPServer` | class | [LuaMCPServer](/reference/sdk/luamcpserver) | | `LuaDevice`, `defineDevice`, `LuaDeviceTrigger`, `defineDeviceTrigger` | class, function | [defineDevice and defineDeviceTrigger](/reference/sdk/device-definition) | | `LuaVoice`, `LuaVoiceTool`, `defineVoice` | class, function | [defineVoice](/reference/sdk/voice) | ### Runtime objects | Export | Reference | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `User` (with `User.Inbox`) | [User](/reference/sdk/user), [Inbox](/reference/sdk/inbox) | | `Data` | [Data](/reference/sdk/data) | | `Products`, `Baskets`, `Orders`, `BasketStatus`, `OrderStatus` | [Products](/reference/sdk/products), [Baskets](/reference/sdk/baskets), [Orders](/reference/sdk/orders) | | `Jobs` | [Jobs](/reference/sdk/jobs) | | `Workflows` | [Workflows](/reference/sdk/workflows) | | `AI` | [AI](/reference/sdk/ai) | | `Agents` | [Agents](/reference/sdk/agents) | | `Integrations` | [Integrations](/reference/sdk/integrations) | | `Voice` | [Voice runtime](/reference/sdk/voice-runtime) | | `Channels`, `CHANNEL_SEND_CHANNELS` | [Channels](/reference/sdk/channels) | | `Team` | [Team](/reference/sdk/team) | | `Templates` | [Templates](/reference/sdk/templates) | | `CDN` | [CDN](/reference/sdk/cdn) | | `Lua` | [Lua](/reference/sdk/lua) | | `env` | [env](/reference/sdk/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](/reference/sdk/workflow-builder). ### Instance classes `JobInstance`, `UserDataInstance`, `DataEntryInstance`, `ProductInstance`, `BasketInstance`, `OrderInstance` are the classes runtime methods return. Their members are listed on [Types](/reference/sdk/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. ```ts theme={null} import type { LuaSkill, LuaTool, LuaAgentConfig, LuaWebhookConfig } from 'lua-cli'; type LuaSkillConfig = ConstructorParameters[0]; type LuaToolCtx = NonNullable[1]>; type LuaWebhookEvent = Parameters[0]; type BatchingConfig = NonNullable; ``` ## 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](/reference/sdk/luatrigger) | | Workflow code step | Depends on the run | See [Workflows](/reference/sdk/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](/concepts/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](/reference/sdk/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](/reference/sdk/voice-runtime). * `JobInstance.execution` is the reverse case: set in the deployed runtime, `undefined` in `lua test`, and absent from the type. See [Jobs](/reference/sdk/jobs). ## See also * [About execution contexts](/concepts/execution-contexts) * [Types](/reference/sdk/types) * [LuaAgent](/reference/sdk/luaagent) * [Workflow builder](/reference/sdk/workflow-builder) * [lua test](/reference/cli/test)