Solution templates
Install a governed agent from a versioned template, or author and publish your own: preview every write, upgrade keeping local changes, uninstall cleanly.
- Preview and install a template as one transaction
- Upgrade an installed agent to a newer template version
- Uninstall exactly what an install wrote
- Author, version and publish your own templates with parameters
A solution template is a versioned package of everything one agent needs, installed together:
| Part | What it installs |
|---|---|
| Agent | Identity, instructions, registry entry (risk tier, intended purpose, out of scope, oversight roles), token ceiling |
| Guardrails | Policies scoped to that agent alone and bound to it. A template can never put a rule on the rest of the estate |
| Workflow | A workflow, with a person's approval in front of anything that changes a record |
| Triggers | Cron or ticket-event triggers, installed paused unless you ask |
| Eval set | Cases for the agent, including refusals and must-not-contain checks |
| Budget | A monthly budget |
Built-in templates cover IT service desk, HR, SAP, Salesforce and Finance. A template is offered only for the solutions your tenant has.
The gallery
Open Agents › Templates (/templates). Each card shows the solution, version, risk tier and what the template installs.
- View opens the parts and the instructions.
- Install opens a short form: agent id, tags, optional provider and model, whether to start the triggers, and values for the template's parameters.
- Preview shows the plan per record.
- The Installed tab lists installs, with Upgrade to x.y.z when a newer version is published, and Uninstall.
Preview and install
POST /api/templates/{key}/preview makes every write the install would and rolls them back. The answer says what would be created, changed or refused (valid, step, refusal), not only what differs.
POST /api/templates/{key}/install makes the writes for real, in one transaction: the template lands whole or not at all. The writes go through the same routes you would use building the agent by hand, so every permission, Cedar gate, weakening gate and validator applies.
| Body field | Meaning |
|---|---|
agent_id | The new agent's id. Empty takes the template's default |
provider, model | Optional model binding. Empty leaves the agent unbound |
tags | Your tags, added to the template's own (up to 20) |
enable_triggers | false by default: triggers are installed paused |
params | Values for the template's parameters. A parameter left out takes its default |
reason | Required when an upgrade drops a guardrail (a weakening) |
An install refuses (409) to take over an agent, guardrail or eval set it did not create, never installs over a GitOps-locked agent, and refuses a template whose solution the tenant does not have. An agent deleted by hand and registered again under the same id is a different agent: an install refuses it and an uninstall leaves it alone.
Upgrade
Installing a newer version over an agent the template installed is an upgrade. It keeps what a person changed since: their tags, their own triggers, triggers they switched on or off, the provider they bound and the budget they set. It applies the template's instructions, registry entry, guardrails and workflow.
A guardrail the newer version no longer carries is deleted. That is a weakening, so it needs governance.weaken and a reason.
Uninstall
DELETE /api/template-installs/{agent} removes exactly what the install wrote: the workflow, the guardrail binding, the agent with its triggers and budget, and its guardrails.
| Body field | Meaning |
|---|---|
keep_guardrails | Keep the guardrails instead of deleting them |
reason | Required to delete enforcing guardrails (governance.weaken) |
dry_run | Say what would go, and whether it would be refused, without changing anything |
The eval set is kept: its versions are immutable and scored runs refer to them. Installing the same template again under that id takes the kept set back, unless someone wrote a version on it since.
Author your own templates
Open Agents › Templates › Your templates (/api/template-authoring).
- Choose New from an agent. The draft is built from an agent you run: its instructions, registry entry, the guardrails bound to it alone, its cron and ticket triggers, a workflow, its
<agent>-evalsset and its budget. Nothing is saved yet. - Edit the metadata and the parts, and add parameters.
- Choose Check to validate against the same template schema the built-in templates pass.
- Save draft versions. A draft is rewritten in place until it is published.
- Publish the version. The gallery lists it beside the built-in templates as "Your template", and install, preview, upgrade and uninstall work exactly as above.
Versions are MAJOR.MINOR.PATCH and only go up. A published version never changes; a later change is a newer version. Withdrawing a template removes every version from the gallery and leaves installed agents running with their install records.
Authored templates are stored per tenant under row-level security. Another tenant neither sees nor installs them, and a key may not reuse a built-in template's key.
Parameters
Declare parameters under params: name, label, type (text, number, boolean or choice), default and required. Use them as {{ params.name }} anywhere in the template's text. The install form asks for them, and they are sent as params on install. A reference to a parameter that is not declared fails validation.
Routes and permissions
| Task | Endpoint | Permission |
|---|---|---|
| List templates, read one | GET /api/templates, GET /api/templates/{key} | agents.read |
| Preview, install or upgrade | POST /api/templates/{key}/preview, /install | agents.create, plus each part's own permission |
| List installs | GET /api/template-installs | agents.read |
| Uninstall | DELETE /api/template-installs/{agent} | agents.delete |
| List or read authored templates | GET /api/template-authoring, /{key} | templates.write |
| Check a document | POST /api/template-authoring/validate | templates.write |
| Draft from an agent | POST /api/template-authoring/from-agent | templates.write and agents.read |
| Save a draft version | PUT /api/template-authoring/{key}/versions/{version} | templates.write |
| Publish | POST /api/template-authoring/{key}/versions/{version}/publish | templates.write |
| Delete a draft version | DELETE /api/template-authoring/{key}/versions/{version} | templates.write |
| Withdraw a template | DELETE /api/template-authoring/{key} | templates.write |
Each part's own permission is checked as its route checks it: governance.write for the guardrails, binding, budget and eval set, and agents.update for the workflow. templates.write is held by administrators and is not implied by agents.build.
Audit rows: template.install, template.upgrade, template.uninstall and their .refused rows, and template.author.save, .publish and .delete. A refused or previewed install leaves no rows for changes that never happened.
Limits
- Templates are per tenant. There is no marketplace to share one with another tenant, and no import of a template file from outside.
- SAP, Salesforce and finance templates assume their connection exists; they do not create or check the MCP server they read from.