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 is visible only through Agent B’s access boundary, not in the Organization catalog or to sibling Agents. 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

Users need Agent access to view this configuration and agent.update to create, edit, publish, or select it. Agent-private Skills are likewise visible only through their owning Agent; shared Template and Skill management remains separate.

What an Override contains

An Override Draft and every published Override Version are complete snapshots, not deltas. 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.

A source update exists only for the active Override’s exact direct Platform or Organization source lineage when that lineage publishes a newer version. An Override sourced from an Organization Template does not independently follow that Template’s Platform origin.

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. If the source can no longer be resolved, no update candidate appears, but the self-contained Override remains valid.

Apply a source update

A source update selects the complete newer shared Template Version as the Agent’s active pin. Its exact required Skill Versions must be satisfied. 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 and satisfy its exact required Skill Versions.
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. Every requirement must be visible to the owning Agent: Platform Skills, its Organization’s Skills, and its own Agent-private Skills are eligible; another Agent’s private Skills are never visible or eligible.

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

• Every standalone Skill is assigned to the Agent at its exact required Skill Version
• At least one Skill from each group is assigned at that member’s exact required Skill Version
• Required Skill providers are configured for the Agent

Having the correct Skill lineage at a different version does not satisfy the requirement. Validation runs when requirements are saved, the Override Draft is published, and a published Override Version is selected. Publishing a newer Skill Version never changes an existing Override Draft, published Override Version, or Agent Skill pin.

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 or repin the required Skills at their exact versions, then configure required provider credentials and 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,
      "required_skills": [
        { "id": "{skill_id}", "name": "Jira", "version": 3, "group_key": null },
        { "id": "{skill_id}", "name": "GitHub", "version": 2, "group_key": "code-host" }
      ]
    }
  ]
}

Each required_skills entry carries its exact version; group_key: null is standalone, while matching non-null keys form a group.

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