Agent Templates

What an agent template is

An agent template is a published, versioned blueprint of a working agent — everything someone needs to deploy their own copy of it:

Persona — who the agent is, captured as a template with {{variables}} the installer fills in (“You are the sales assistant for {{COMPANY_NAME}}…”).
Skills, webhooks, jobs, processors, triggers, and the model — everything lua push and lua version promote manage together as one agent version.
Connections — what the agent plugs into, declared as capabilities (“a CRM”) satisfiable by any listed platform (Salesforce or HubSpot), each marked required or optional.
Trigger presets — the agent’s schedules and event triggers, with recommended defaults and installer-editable parameters (“check every 5 minutes” — change it to 10 at deploy).
The env contract — which environment variables the template’s code expects, declared by name and description, never by value.
Runtime dependencies — things a deploy can’t create but the agent needs to fully go live, like a WhatsApp or email channel, declared so the installer sees an honest post-deploy checklist instead of a false “live”.
Outcomes — the template’s countable units of work (“follow-ups sent”, “meetings booked”), counted by the platform from real side effects, so every install gets a comparable measure of what the agent actually delivers.

Publishing a template freezes one agent’s promoted version into this blueprint. Deploying it materializes the blueprint as a working agent — a brand-new agent created for you in one call, or installed onto an agent you already run. Every attribute of the blueprint — types, defaults, constraints, and what serves where — is documented in the Template Manifest Reference.

Three things called “template” — which one is this?

Agent Templates (this page, and the lua marketplace template commands) — full agent blueprints on the marketplace.
The Templates runtime API in the SDK — WhatsApp message templates, the pre-approved outbound message formats Meta requires. Unrelated.
Project scaffolds — the starter files lua init generates. Also unrelated.

Looking for the single-tool equivalent? See Skills — a skill is one reusable tool; a template is an entire agent.

Persona: captured, filled in, and yours after install

A template can carry the source agent’s persona as a persona template: the system prompt with {{variable}} slots, each one declared with a type, a display name, and a description, so the deploy flow renders a labeled, explained field per slot — never a bare COMPANY_NAME. Three rules govern how persona behaves across a template’s life:

At deploy, the slots are filled from your answers. If the template marks its persona editable, you can also tweak the resolved prompt before it lands.
An agent that already has a persona keeps it. Installing a template onto an existing agent never replaces its persona by default — overwriting is an explicit opt-in. (A fresh agent created by deploy always gets the template’s persona; there’s nothing to preserve.)
Your post-install persona edits survive updates. If you tune the agent’s persona after install and later accept a template update, the update skips the persona write and tells you so — “re-apply template persona” is a separate, explicit action, never a side effect of updating.

What a template still never touches: environment variable values (always set per-agent via lua env or supplied at install), channels and connected numbers, and the agent’s name.

Voice agents can’t be templated yet. Publishing from a source agent that has voices or device triggers is rejected at publish time, with a message saying why — rather than shipping a template that deploys half-working.

The env contract

A template version declares an env contract: the variable names its code expects, each with a description and a required/optional flag — never values. Missing required variables block an install with a clear list of what’s missing.

# Declare the contract when publishing a version
lua marketplace template publish \
  --template-id tpl_abc \
  --env-contract "STRIPE_KEY=Stripe secret key for the checkout skill" \
  --env-contract "SUPPORT_EMAIL?=Fallback contact address"

# Satisfy it at install time
lua marketplace template install \
  --template-id tpl_abc \
  --env-vars "STRIPE_KEY=sk_live_xxx" \
  --force

KEY=description marks a variable required; KEY?=description marks it optional. Omitting --env-contract entirely when publishing a new version inherits the previous version’s contract unchanged.

--skip-env-check is retired. The env-contract check is now always enforced on the server — there is no way to bypass it. The flag is still accepted so old scripts don’t break, but it does nothing except print a deprecation warning. Satisfy the contract with lua env or --env-vars instead.

Connections: “a CRM”, not “Salesforce”

A template declares what it plugs into as capabilities, each satisfiable by any platform in its allow-list:

A capability like crm might list Salesforce and HubSpot — any one satisfies it.
Each capability is required (install blocks without it) or optional (offered, never blocking — the parts of the agent that depend on it stay safely inactive until you connect it).
At deploy, the platform checks the connections you’ve already granted and reuses them — a capability you’ve already connected is skipped silently. You’re only ever asked to connect the genuine gaps, and often there are none.
If more than one of your connections could satisfy a capability (a personal and an org Salesforce, say), you’re asked which to use — never auto-picked.

See Deploying Templates for the installer’s view of this, including required-versus-optional behavior and rebinding later.

Trigger presets: recommended, confirmed, adjustable

Every schedule and event trigger in a template ships as a preset: a recommended on/off default plus the parameters the creator marked editable (an interval, a time of day). Nothing arms silently — deploy ends with an explicit confirmation listing exactly which automations go live, and anything outbound or event-driven stays off until you confirm it. Schedules render in your timezone, with the next run times shown before you confirm.

Lifecycle: private by default, reviewed when public

Private by default

A new template is visible and installable only within your organization — built for fleets first. Public is an explicit choice.

Per-version review for public templates

Going public puts the template through platform review. Review is per version: every version published while a template is public enters review and is not installable by others — including via the update badge — until approved. A rejection leaves previously approved versions listed. Creator self-test installs on your own org’s agents are exempt, so you can verify a pending version before anyone else can touch it.

Deprecate a version

Deprecating a version blocks new installs of that version; agents already running it are unaffected, and the changelog carries the reason. You can’t deprecate the only approved version of a still-listed public template — unlist first.

Unlist (soft-retire)

Unlisting hides the template and blocks new installs and creator-pushed updates. Existing installs keep running with what they have, uninstall always works, and an installer can still re-run their same installed version to rebind a connection — recovery paths stay open. There is no hard delete: unlist + deprecate is the complete retirement path, keeping the audit trail intact for every agent still running the template.

Installing a template never gives its creator ongoing write access unless you explicitly opt in (allowCreatorUpdates, off by default for user-facing installs). Two different kinds of change are treated differently:

Code-only updates — the creator improved a skill’s implementation without changing what the template asks for — flow to opted-in installs under that standing consent. This is what makes fleet operations work.
Consent-surface changes — widened OAuth scopes, an added connection, a changed trigger instruction — require fresh consent from every install, opted-in or not. A creator push carrying one of these is rejected per target until the installer reviews and accepts it.

Updates are previewed, not blind: before accepting, an installer sees the changelog, what’s added/removed/changed, any scope changes, and which of their currently-armed automations survive. Their persona edits and schedule tweaks are preserved across the update. See Deploying Templates for the full installer view.

Fleet operations

Template creators (and orgs running internal fleets) roll a version out to many agents at once with apply:

# Canary first: a named set of agents
lua marketplace template apply \
  --template-id tpl_abc \
  --agents agent_1,agent_2,agent_3 \
  --force

# Then every consenting agent that has the template installed
lua marketplace template apply --template-id tpl_abc --all-installed --force

apply runs asynchronously on the server — the CLI starts the run, polls it, and prints a per-target result table (pass --no-wait to get the run ID back immediately):

Apply run failed (run_xyz)
AGENT ID   STATUS     LOCAL VERSION  ERROR
agent_1    applied    v4
agent_2    applied    v5
agent_3    failed     v3             Missing required environment variables: STRIPE_KEY

Any failed target marks the whole run failed and makes the CLI exit non-zero, so a partial rollout never looks like a clean success in CI. Successful targets are unaffected; re-running apply is safe. apply only ever reaches agents that opted in with allowCreatorUpdates — and a creator can’t use apply results to probe which agents installed without consenting. A creator push also never arms new automations: new or renamed triggers land disabled on the target, awaiting the installer’s confirmation, and a trigger the installer paused stays paused.

Fleet visibility and rollback

lua marketplace template status --template-id tpl_abc     # who runs which version
lua marketplace template versions --template-id tpl_abc   # all published versions
lua marketplace template view --template-id tpl_abc --version 3

Rollback needs nothing template-specific: installing a template promotes a normal agent version, so lua version promote <n> on any single agent rolls it back, and applying an older template version re-materializes that version fleet-wide.

Publishing Templates — the creator’s guide: draft, author, publish, review, roll out
Template Manifest Reference — every attribute: fields, types, defaults, constraints, lints
Deploying Templates — the installer’s guide: deploy, connect, operate, update, uninstall
Marketplace Command reference
Version Command — the agent-version mechanics installs build on
Environment Variables Command

​What an agent template is

​Persona: captured, filled in, and yours after install

​The env contract

​Connections: “a CRM”, not “Salesforce”

​Trigger presets: recommended, confirmed, adjustable

​Lifecycle: private by default, reviewed when public

​Updates and consent

​Fleet operations

​Fleet visibility and rollback

​Related

What an agent template is

Persona: captured, filled in, and yours after install

The env contract

Connections: “a CRM”, not “Salesforce”

Trigger presets: recommended, confirmed, adjustable

Lifecycle: private by default, reviewed when public

Updates and consent

Fleet operations

Fleet visibility and rollback

Related