Manage forks and updates

Before you begin

You need:

• Access to the organization containing the template
• template.read permission to view templates and version history
• template.manage permission to create or update an Organization fork
• Permission to update an agent when changing its selected template version
• Lifecycle permission when applying a version to a running agent

Organization Members can view and use shared templates. Organization Owners and Administrators can manage their definitions. Platform Template authoring requires separate Platform Administrator permissions.

If you have not worked with immutable template versions, read Manage template versions first.

Understand the template sources

Agent Barn distinguishes between several template sources.

This guide focuses on Organization forks of Platform Templates.

Organization-owned templates do not receive Platform updates, because they have no Platform source. Agent overrides have a separate Agent-owned version and draft model, covered in Use Agent overrides.

How an Organization fork works

Editing a built-in Platform Template creates an Organization-scoped fork. The fork:

• Keeps the Platform Template’s stable template key
• Copies its content into Organization version 1
• Copies its required Skill rules
• Records the Platform version used as its baseline
• Starts an independent Organization version sequence
• Leaves the global Platform Template unchanged
• Does not move existing agents

The Organization sequence is independent of the Platform sequence. A fork created from Platform v2 starts at Organization v1, not Organization v3.

The same visible lineage can therefore contain:

Built-in platform v1
Built-in platform v2
Built-in platform v3
Organization fork v1
Organization fork v2

Fork, baseline, and origin

An Organization fork maintains two related ideas:

• Origin identifies the Platform Template from which the fork was originally created.
• Baseline identifies the latest Platform version explicitly adopted into the Organization fork.

Suppose an organization creates a fork from Platform v2:

Origin:   Platform Template tpl-4f6a71b29c83
Baseline: Platform v2
Current:  Organization v1

The organization then publishes two custom changes:

Origin:   Platform Template tpl-4f6a71b29c83
Baseline: Platform v2
Current:  Organization v3

Publishing Organization changes does not advance the Platform baseline.

If the organization later applies Platform v5, Agent Barn creates the next Organization version and advances the baseline:

Origin:   Platform Template tpl-4f6a71b29c83
Baseline: Platform v5
Current:  Organization v4

The fork’s original lineage remains intact.

Replacement, not merge

Consider a fork whose Organization version customized the escalation path, and a Platform version that then changed the same content.

The custom Team Atlas escalation is not merged into Organization v3. If that customization is still needed, edit Organization v3 and save it as Organization v4 containing both the new Platform behavior and the local escalation rule.

This makes the release sequence explicit, and preserves every intermediate snapshot.

What happens to existing agents

Applying a Platform update creates a template version. It does not update an agent’s selected version.

Agent A ── Organization v2
Agent B ── Organization v2
Agent C ── Platform v3

Agent A ── Organization v2
Agent B ── Organization v2
Agent C ── Platform v3

Organization v3 is available but not yet selected.

This separation gives you time to test the updated fork. To roll out the update:

1. Select a test agent.
2. Apply the new Organization version.
3. Restart the agent if it is running.
4. Verify its health, activity, logs, and behavior.
5. Apply the version to a small production group.
6. Monitor the group.
7. Move the remaining agents when ready.

There is no automatic fleet-wide rollout.

Required Skills during an update

A Platform update copies the latest Platform version’s complete required Skill configuration. That includes standalone Skills that are all required, and Skill groups where at least one member must be assigned.

The fork’s previous Skill requirements are replaced.

Before applying the new Organization version to an agent:

1. Inspect its required Skills.
2. Confirm that the required Skills are visible to the organization.
3. Confirm that the agent has the required standalone Skills.
4. Choose at least one Skill from every required group.
5. Configure any required provider credentials.
6. Apply the template version.

Agent Barn validates the exact selected version’s requirements when the agent is updated. An agent still pinned to the older Organization version remains governed by that older version’s requirements.

Apply an update with the API

Use the Organization Template update endpoint. No request body is required.

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

Example:

curl --request POST \
  --url "${AGENT_BARN_URL}/api/v1/organizations/${ORGANIZATION_ID}/templates/${TEMPLATE_KEY}/platform-update" \
  --header "Authorization: Bearer ${AGENT_BARN_TOKEN}"

A successful request returns 201 Created and the newly created Organization version:

{
  "template_key": "tpl-4f6a71b29c83",
  "template_name": "Customer Support Agent",
  "template_source": "pre-defined",
  "version": 4,
  "fork_baseline_platform_version": 5,
  "platform_update_available": false
}

The response also contains the copied template content and required Skills.

Platform update validation

The API rejects the update when:

• The template key does not identify an Organization fork
• The template is an Organization-owned custom template
• The fork’s Platform baseline is unavailable
• No newer Platform version exists
• The caller lacks template.manage permission

Possible conflict responses include:

409 Template Update is only available for organization forks of Platform Templates

409 No newer Platform Template Version is available

409 The fork's Platform Template baseline is no longer available

Refresh the template before retrying, so you are working with its latest lineage state.

Choose the correct action

Use a safe update workflow

A recommended release sequence is:

1. Platform update detected
2. Review latest snapshot
3. Record customizations
4. Apply update
5. Reapply customizations
6. Test with one Agent
7. Canary rollout
8. Wider rollout

For high-impact templates, keep the previous Organization version pinned to at least one test agent until the new version has been verified.

Roll back after a Platform update

Because previous Organization versions remain immutable, you have two rollback options.

Roll back one agent

Repin the agent to its previous Organization version. This is the fastest option, and it does not create a template version.

Agent A: Organization v5 → Organization v3

Other agents remain unchanged.

Restore fork content as a new version

If historical content must become the latest fork version:

1. Open the historical Organization version.
2. Review all artifacts and required Skills.
3. Edit or reproduce its complete snapshot.
4. Save it as the next Organization version.
5. Apply the new version to the required agents.

This preserves the Platform update in history, while creating a new immutable version containing the restored behavior.

For an exact API restoration, submit all template fields and Skill requirements. Omitted fields inherit from the current latest Organization version.

Return an agent to the Platform source

Creating a fork does not prevent an individual agent from using a Built-in Platform version.

1. Open the agent.
2. Go to Configuration.
3. Open the template selector.
4. Find the entry labeled Built-in platform.
5. Select the exact Platform version.
6. Preview its content and required Skills.
7. Select Apply or Apply & Restart.

This changes only that agent’s pin. It does not remove or alter the Organization fork.

Deleting and detaching forks

Organization forks cannot be deleted through normal Template deletion. You also cannot detach a fork and convert its existing lineage into a normal Organization-owned template.

If you need a separately managed template with no Platform update relationship:

1. Create a new Organization-owned template.
2. Copy the desired content.
3. Configure its required Skills.
4. Publish it as Organization version 1.
5. Test it.
6. Move the required agents to the new template.

The original Organization fork remains available with its history and Platform relationship.

Template forks and Skill forks are different

This update model applies to Organization Template forks. A fork of a built-in Skill is different:

• It creates a new Organization-owned custom Skill
• It is a one-time snapshot
• It has its own identity and version history
• It does not track future updates from the built-in Skill

Do not expect a custom Skill fork to display Platform update available.

Troubleshooting

Recommended practices

• Record the fork’s Platform baseline before making Organization changes
• Keep Organization customizations focused and documented
• Review all eight artifacts before applying an update
• Treat required Skill changes as part of the release
• Assume an update is a replacement, never a merge
• Test updates with a dedicated agent
• Use a canary rollout before moving all agents
• Keep previous versions available for rollback
• Reapply local changes as a separate immutable version
• Record both source and version when discussing a template
• Never assume publishing or updating automatically moves agents

Next steps

Continue to Use Agent overrides to learn how one agent can maintain private template changes without modifying its Organization or Platform source.

• Manage template versions
• Work with templates
• Configure an Agent