Skip to main content
An agent template is a published, versioned copy of a working agent: one promoted agent version frozen together with the sections an installer fills in. It exists so a tuned agent can be reproduced for many clients or sites and kept in sync as it improves, without copying source between projects.

​
How a template is published and installed

Publishing freezes a source agent’s promoted version (its skills, webhooks, jobs, preprocessors, postprocessors, triggers, workflows, and model settings) into a template version, together with an env contract and the seven authored sections of the template: block in lua.skill.yaml. Voices and device triggers are not frozen: a source agent that has either is refused with UNSUPPORTED_SOURCE. The sections:
  • connections declare what the agent plugs into as capabilities (“a CRM”), each satisfiable by any listed platform and marked required or optional.
  • personaTemplate carries the persona with {{variables}}, a typed declaration per variable, and whether the installer may edit the rendered text.
  • triggerPresets give each schedule and event trigger an on/off default and the parameters the installer may change.
  • paramsMeta types the install-time parameters: display name, default, allowed values, and when a field is shown.
  • onInstall names a tool to run as the installer right after install and/or one instruction for a single background agent turn.
  • onUninstall does the same before teardown, best-effort.
  • installPolicy (perWorkspace) limits an installer to one install (single) or allows any number (multiple).
The env contract is declared at publish with --env-contract KEY=description (KEY?=description for optional) and lists variable names, never values; an install that lacks a required variable is refused with the missing names. Installing materializes the template as a working agent, either one created for the install or an agent you already run. The installer supplies the per-install answers: environment values, persona variables, connections, and which triggers to arm. The CLI answers environment values only (--env-vars) and arms the recommended trigger defaults; persona variables, connection choices, and trigger overrides come from the desktop install form or the REST install body, so a template whose persona has a required variable without a default cannot be installed from the CLI. Connections you have already granted are reused; only gaps are requested, and when two connections could satisfy a capability you are asked which to use. A template never writes an existing agent’s environment values, channels, or name, and an agent that already has a persona keeps it; the full list is under What installers agree to and keep. Installing promotes a normal agent version, so lua version promote <n> on that agent is the rollback. Visibility is private (your organization only) or public. Each version of a public template is reviewed before anyone else can install it and carries a status of pending, approved, or rejected. An organization can also set a policy on what its members may install: a template is allowed, requires approval (the install is queued as a request), or is blocked with POLICY_BLOCKED. Updates are consent-based. An install opts in with --allow-creator-updates; publishing a version then applies it to every consenting install that is behind (for a public template, once the version is approved), and --skip-auto-apply holds a version back for a manual apply. Each version carries a hash of its consent surface (connections and their scopes, trigger instructions, shipped workflows, and required environment keys); when that hash changes, the update is refused per install with RECONSENT_REQUIRED until the installer reviews and accepts it, whether or not they opted in. Fleet rollouts use lua marketplace template apply --template-id <id> --all-installed --force (or --agents <ids> or --file <path> for a subset), at most 500 targets per run; one failed target marks the run failed and the command exits 1. lua marketplace template status shows who runs which version, and lua marketplace template health --window-days <n> reports workflow health per install.

​
Agent templates, marketplace skills, and project scaffolds

Three things are called “template” and only one is this page. An agent template is a whole agent. A marketplace skill is one reusable skill you install into an agent you already have; it is versioned with semver and managed with lua marketplace skill. The project scaffold is the set of files lua init generates: a starting point for source, not a published artifact. WhatsApp message templates, the pre-approved outbound message formats, are unrelated.

​
When to use it

  • You build the same agent for many clients: publish once, install per client, and roll improvements out with apply.
  • A client operator must run the agent without engineers: the install flow asks only for values and connections, and everything else is managed.
  • Use a marketplace skill instead when you want to add one capability to an existing agent.
  • Use lua init --from-agent-id <id> instead when you want an independent copy you will edit, with no link to the source.

​
Limits

​
Next steps

Publish a template

Draft, author the sections, publish, and roll out.

Install and apply

Install, connect, update, and uninstall as the installer.

Template manifest

Every field of the template: section.

Fleet health

Status and health across every install.