Use Agent overrides

Before you begin

You need:

• Access to the Agent
• Permission to view its configuration
• agent.update permission to create, edit, publish, or select an Override
• Lifecycle permission to apply an Override to a running Agent
• Any Skills required by the Override assigned to the Agent
• Required provider credentials configured for those Skills

You can safely create, edit, and publish an Override while the Agent is running. Applying a published version to a running Agent requires Apply & Restart.

Choose the correct customization boundary

Use the narrowest boundary that matches the intended audience.

Agent Overrides are useful for:

• Agent-specific tone or identity
• Instructions tied to one business function
• Temporary behavior experiments
• Private escalation rules
• Testing changes before updating a shared template
• Required Skills that apply only to one Agent

Avoid duplicating the same Override across several Agents. Publish common behavior to an Organization Template instead.

How Agent Overrides work

An Override has its own Agent-scoped lifecycle.

1. Shared Template
2. Agent-owned draft
3. Published Override Version
4. Apply
5. Restart

Publishing and selecting are separate operations. Publishing creates an immutable Override Version, but the Agent remains on its currently selected configuration until you explicitly apply the published version.

Understand the isolation boundary

Suppose three Agents use the same Organization Template. Creating and applying an Override for Agent B affects only Agent B.

Organization Template v4
├── Agent A
├── Agent B
└── Agent C

Organization Template v4
├── Agent A
└── Agent C

Agent B
└── Agent Override v1
    Source: Organization Template v4

Agent A and Agent C remain unchanged. The Override:

• Belongs to Agent B
• Has an independent version sequence
• Preserves its shared source metadata
• Is not added to the Organization Templates catalog
• Cannot be applied to Agent A or Agent C
• Remains available if Agent B later switches back to a shared version

What an Override contains

Runtime configuration outside the Template boundary is not included. Rolling back an Override changes template behavior only.

Publishing does not activate the Override

After publication, the Agent keeps its current pin until you select the new version.

Active configuration: Organization Template v4

Published Override history:
└── Override v1

Active configuration: Agent Override v1

Published Override history:
└── Override v1 · Active

This separation lets you publish safely without restarting or changing a production Agent.

Switch back to a shared Template

An Agent can leave its Override history and return to a Platform or Organization Template.

1. Open Template selection.
2. Find the required shared Template.
3. Check whether it is labeled Built-in platform, Organization-owned, or Organization fork.
4. Select the exact version.
5. Preview its content and required Skills.
6. Select Apply or Apply & Restart.

The published Override history is preserved. You can return to an Override later by selecting it again.

Override v2 ── switch ── Organization Template v5
     ▲
     └──────── select Override v2 later

Switching to a shared Template does not publish, merge, or delete an Override.

Understand source updates

Every Override records the exact shared version from which its lineage was created. The direct source can be a Platform Template Version or an Organization Template Version.

If that direct source lineage publishes a newer version, Agent Barn can show a source update in Template selection.

Override source: Platform v2
Latest source:   Platform v4
Label:           Platform update

Override source: Organization v3
Latest source:   Organization v5
Label:           Organization update

Only the direct source lineage is checked. An Override based on an Organization Template does not independently follow that Organization Template’s underlying Platform source.

Apply a source update

A source update changes the Agent’s pin from the Override to the newer shared source version. It does not update the Override itself.

Active: Override v2
Source: Organization Template v3
Draft:  Local unpublished work

Active:  Organization Template v5
Draft:   Local unpublished work remains unchanged
History: Override v1 and v2 remain unchanged

To apply a source update:

1. Open Template selection.
2. Find the entry marked Platform update or Organization update.
3. Preview the complete shared snapshot.
4. Review its required Skills.
5. Select Apply or Apply & Restart.
6. Confirm the change.

Rebase private changes on a newer source

Agent Barn does not perform a three-way merge between an Override and its source.

To build a new Override from a newer shared version:

1. Record the private changes that must be retained.
2. Resolve any existing Override Draft.
3. Apply the newer Platform or Organization source version.
4. Confirm that the shared version is active.
5. Open Agent-owned override.
6. Select Create override.
7. Reapply the required private changes.
8. Save the new draft.
9. Publish it.
10. Apply the new Override Version.
11. Test the Agent.

This produces an explicit history:

Override v2
Source: Organization v3
        │
        ├── Select Organization v5
        ▼
Active shared source: Organization v5
        │
        ├── Create and publish new Override
        ▼
Override v3
Source: Organization v5

Source updates preserve draft work

A source update never overwrites an existing Override Draft. This matters when one user is editing private Agent instructions while another user applies a newer shared source.

Saved Override Draft
├── Custom SOUL.md
└── Custom required Skills

Apply source update
        │
        ├── Active Agent pin changes
        └── Saved Override Draft remains unchanged

The draft can be reviewed and published separately. Because its original source metadata remains unchanged, review it carefully before publishing after a source update.

Source availability

Published Overrides are self-contained snapshots. They remain valid even if their original source row is no longer available.

If Agent Barn cannot resolve the exact recorded source:

• The Override remains usable
• Its published history remains available
• The Agent can stay pinned to it
• No source-update candidate is shown

An unavailable source does not invalidate an existing Override.

Required Skills

Required Skill rules are copied into the Override Draft and can be changed for that Agent. The rules can contain standalone Skills that must all be assigned, and groups where at least one member must be assigned.

Agent Barn validates the requirements when the draft is saved or published, and when a version is selected. Validation checks that:

• Each required Skill is available to the organization
• Required standalone Skills are assigned to the Agent
• At least one Skill from each group is assigned
• Required Skill providers are configured for the Agent

Example errors include:

Required template skills must be assigned to the Agent: Jira

At least one of these template skills must be assigned to the Agent: Jira, Linear

Required Skill 'Jira' needs configured providers: jira

Assign the missing Skills or configure the required credentials, then retry.

Permissions and lifecycle behavior

API reference

Read configuration and Override history

GET /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration

The response includes active, draft, source_update, shared_versions, and override_versions.

{
  "agent_id": "928ae950-586f-4b5d-8f01-096116e60c7b",
  "active": {
    "pin_type": "override",
    "version": 1,
    "state": "active"
  },
  "draft": null,
  "source_update": null,
  "shared_versions": [],
  "override_versions": [
    {
      "version": 1,
      "state": "published",
      "pin_type": "override",
      "source_type": "organization",
      "source_template_key": "tpl-4f6a71b29c83",
      "source_template_version": 4
    }
  ]
}

Start an Override Draft

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

No request body is required. If a draft already exists, the existing draft is returned.

Save an Override Draft

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/draft
Content-Type: application/json

{
  "expected_updated_at": "2026-08-29T10:20:30Z",
  "template_name": "Customer Support — Priority Queue",
  "description": "Private behavior for the priority support Agent.",
  "soul_md": "# SOUL.md\n\nRespond calmly and prioritize urgent cases.",
  "required_skill_ids": [
    "3f117494-cac1-43f2-b5bb-456760fbc82e"
  ]
}

At least one draft field must be provided in addition to expected_updated_at. Omitted fields retain their saved draft values.

Publish the draft

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/draft/publish
Content-Type: application/json

{
  "expected_updated_at": "2026-08-29T10:24:05Z"
}

A successful request returns 201 Created with the immutable published Override Version. Publishing does not select it.

Select an Override Version

The Agent must be stopped before calling the selection endpoint directly.

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/configuration/select
Content-Type: application/json

{
  "selection_type": "override",
  "override_version": 2,
  "expected_agent_updated_at": "2026-08-29T10:31:44Z"
}

Do not include template_key or template_version when selection_type is override.

Select a shared source version

{
  "selection_type": "organization",
  "template_key": "tpl-4f6a71b29c83",
  "template_version": 5,
  "expected_agent_updated_at": "2026-08-29T10:31:44Z"
}

Use selection_type: "platform" for a Built-in Platform Template.

Optimistic concurrency

Draft updates, publication, and template selection use timestamps to prevent one user from silently overwriting another user’s work.

Draft operations use expected_updated_at. Agent selection uses expected_agent_updated_at.

If the resource changed after you loaded it, Agent Barn returns a conflict. Refresh the configuration, review the latest state, and retry with the current timestamp.

Published history and retention

Published Override Versions are immutable and remain available for review, audit history, exact selection, rollback, and comparing private revisions.

Published versions do not have an individual deletion workflow.

Switching to a shared Template does not remove Override history. Soft-deleting an Agent retains its Override history for audit purposes, although the deleted Agent and its history are hidden from normal views.

Troubleshooting

Recommended practices

• Use Overrides only for genuinely Agent-specific behavior
• Keep shared behavior in Organization Templates
• Describe why each private version exists
• Review all eight artifacts before publishing
• Treat publication and activation as separate approvals
• Test a new Override before applying it to a running Agent
• Confirm required Skills and providers before publication
• Use exact historical selection for rollback
• Preserve existing drafts during source updates
• Recreate private changes deliberately on top of a newer source
• Record both the Override Version and its shared source version
• Review Agent health and logs after activation

Next steps

Continue to Work with Skills to learn how Skills package reusable instructions, and how Template requirements interact with an Agent’s assigned capabilities.

• Manage forks and updates
• Manage template versions
• Configure an Agent
• Review Agent health and logs