Manage template versions

Before you begin

You need:

• Access to the organization containing the template
• template.read permission to inspect templates and their history
• template.manage permission to publish Organization Template versions
• Permission to update an agent when changing its selected version
• Lifecycle permission when applying a version to a running agent

Platform Templates require separate Platform Administrator permissions.

This guide assumes that you already understand how to create and edit templates. If not, begin with Work with templates.

How template versioning works

A template lineage has a stable template key, such as tpl-4f6a71b29c83. The key identifies the template across its published versions, and the template name and key remain stable while the version number increases.

Each version is a complete snapshot containing the description, all eight Markdown artifacts, standalone and grouped Skill requirements, and the exact Skill Version required for every Skill:

• Description
• SOUL.md
• IDENTITY.md
• USER.md
• TOOLS.md
• AGENTS.md
• BOOT.md
• BOOTSTRAP.md
• HEARTBEAT.md
• Standalone and grouped required Skill rules with exact Skill Version pins

Versions are immutable, and agents pin them independently:

1. v1 Initial published snapshot
   • Agent A
   • Agent C
2. v2 Revised escalation behavior
   • Agent B
3. v3 Latest published version
   • New agents, when no version is specified

You cannot overwrite v2 after it has been published. A new change becomes v4.

Latest does not mean active

A template does not have one globally active version.

“Latest” means the highest published version available in a particular template lineage and source. “Active” refers to the exact version currently selected by an individual agent.

This lets you test a version with one agent before applying it to others.

Understand the version sources

Agent Barn can show versions from several sources. Their version numbers are independent sequences.

An Organization fork created from Platform v3 starts at Organization v1. It does not become Platform v4.

Choose the correct version action

Different actions have different effects.

Use Apply when you want one agent to use an existing version. Publish a new version when you want to create a new reusable snapshot.

Test and release a new version

Treat template changes like application releases.

1. Publish next version Publishing a saved Organization draft creates the next immutable version
2. Apply to a stopped test agent Nothing moves until you apply it
3. Verify Skills and credentials The exact version being applied is validated
4. Start the agent and run a test conversation Exercise representative tasks
5. Review health, activity, and logs Confirm the behavior change and look for regressions
6. Apply to a small group of agents Monitor the canary group
7. Roll out to the remaining agents Each agent moves only when you apply the version

Recommended steps:

1. Publish the next template version.
2. Preview the complete snapshot.
3. Confirm that its required Skills are installed.
4. Apply it to a stopped test agent.
5. Start the agent.
6. Run representative conversations or tasks.
7. Review agent health and logs.
8. Apply it to a small set of production agents.
9. Monitor the canary agents.
10. Roll it out to the remaining agents.

There is no automatic rollout when a version is published.

Restore a Platform Template version

Platform Templates use one mutable draft per lineage. Publishing a Platform draft creates the next immutable Template Version and clears that draft; Organization Templates use the same separate draft-save and explicit-publish workflow.

A Platform Administrator can:

1. Open the Platform Template’s version history.
2. Select a historical version.
3. Choose Restore vN as draft.
4. Review or edit the draft.
5. Publish the draft.

Restoring an older Platform Template Version seeds a new draft; it never mutates or reactivates that historical version. Publishing creates the next Platform version. Neither workflow changes existing Agent pins automatically.

Manage required Skills across versions

Required Skill rules belong to the individual template version. A newer version can:

• Add a required Skill
• Remove a required Skill
• Change an “at least one of” Skill group
• Keep the same artifacts but change its Skill requirements

Agent Barn validates the requirements of the exact version being applied. Every standalone Skill must be pinned to its exact required version, while a group passes when at least one member is assigned at that member’s exact required version. The right Skill at the wrong version does not satisfy the requirement.

Before applying a version:

1. Inspect its required Skills.
2. Confirm that the organization has access to them.
3. Confirm that required provider credentials are configured.
4. Resolve missing requirements.
5. Apply the version.

Publishing a newer Skill Version never changes existing Template snapshots or Agent pins. Deleting a Skill Version is blocked while a Template Version references it. A Skill cannot be both standalone and grouped, or belong to multiple groups, in one Template Version. The Apply action is blocked when requirements are unavailable or incorrectly pinned.

Understand placeholders and runtime rendering

Template placeholders are resolved when an agent starts, not when the template is published.

That means two agents can use the same immutable template version while receiving different rendered values, based on their names, organization details, or start context. The stored template version remains unchanged.

When you apply a version to a running agent, restart it so Agent Barn can render and generate its new runtime configuration.

Update an Organization fork from Platform

A Platform update is different from publishing a normal Organization edit. Applying a Platform update to an Organization fork:

• Copies the latest complete Platform snapshot
• Copies its exact required Skill Versions and grouped requirements
• Creates the next Organization version
• Replaces the fork’s Organization customizations
• Advances the fork’s Platform baseline
• Leaves all existing agent pins unchanged

It is a replacement operation, not a three-way merge.

POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update

See Manage forks and updates for the complete workflow.

Template deletion boundary

Individual published Template Versions cannot be deleted.

For an Organization-owned custom template, you can delete the entire lineage only when no live agent uses it:

DELETE /api/v1/organizations/{organization_id}/templates/{template_key}

Deleting the lineage permanently removes all of its versions.

You cannot delete:

• One individual shared-template version
• A built-in Platform Template
• An Organization fork
• A custom lineage still used by a non-deleted agent

Publishing a new version is allowed while older versions are in use. Live use blocks deletion of the lineage, not version creation. Do not confuse Template deletion with separately supported, reference-protected deletion of individual Skill Versions.

API reference

List lineage versions

GET /api/v1/organizations/{organization_id}/templates/{template_key}/versions

This endpoint returns the lineage's published history, newest first. Once the Organization has published any version for that key, the response contains its Organization versions. Before an Organization version exists, it falls back to the Platform lineage. An unpublished Organization draft is not a published version and does not by itself replace that fallback.

This endpoint does not combine Platform and Organization histories. The Agent configuration selector uses a separate shared-version lookup so it can offer both sources deliberately. Use the Agent configuration response's shared versions when building that selector; do not use the lineage-history endpoint as a complete list of its source options.

Version numbers are local to their source. Keep source labels when presenting a selected Agent version, even though an individual lineage-history response follows one scope.

Check fields such as:

• version
• organization_id
• template_source
• forked_from_platform_template_id
• fork_baseline_platform_version
• Creation and update timestamps

Do not identify a version using its number alone.

Save a draft and publish an Organization version

PATCH /api/v1/organizations/{organization_id}/templates/{template_key}/draft

{
  "description": "Improve escalation behavior for urgent requests.",
  "agents_md": "# AGENTS.md\n\nEscalate urgent requests to the on-call operator.",
  "required_skill_ids": ["{standalone_skill_id}"],
  "required_skill_groups": [
    { "group_key": "code-host", "skill_ids": ["{github_skill_id}", "{bitbucket_skill_id}"] }
  ],
  "required_skill_versions": {
    "{standalone_skill_id}": 3,
    "{github_skill_id}": 2,
    "{bitbucket_skill_id}": 5
  }
}

POST /api/v1/organizations/{organization_id}/templates/{template_key}/draft/publish

Saving retains unpublished work. Publishing creates the next immutable version and clears the draft. Required Skill selections retain exact version pins and standalone or group requirements. Existing Agent pins do not move.

Apply a version to an agent

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select

Example request:

{
  "selection_type": "platform",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 5,
  "expected_agent_updated_at": "2026-08-29T09:40:12Z"
}

Apply the latest Platform snapshot to a fork

POST /api/v1/organizations/{organization_id}/templates/{template_key}/platform-update

This creates the next Organization version, but does not repin agents.

Troubleshooting

Recommended operating practices

• Treat every version as a release artifact
• Use descriptions that explain the behavioral change
• Test new versions with a dedicated agent
• Roll out to a small canary group first
• Review required Skills before applying a version
• Record both the version number and its source
• Keep agents pinned until their update is intentional
• Roll back by selecting a known-good version
• Republish historical content only when it must become the new latest version
• Review Organization customizations before applying Platform updates

Next steps

Continue to Manage forks and updates to learn how Organization forks track Platform changes, and how to safely adopt a new Platform snapshot.

• Work with templates
• Manage Skill versions
• Use Agent overrides
• Configure an Agent
• Review Agent health and logs