--- title: Use Agent overrides canonical: "https://agentbarn.dev/guides/templates-and-skills/agent-overrides" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Understand Agent Barn Agent overrides: private per-Agent template drafts, immutable published versions, explicit activation, source updates, and rollback." tags: [Templates and Skills, Concept, "Agent operators, Agent editors, Template authors, and Organization administrators", Agent override, override draft, override version, private template, publish override, source update, template selection, roll back override, agent update permission] categories: [Guides, Templates and Skills] --- - Templates and Skills - 12–15 minutes An Agent Override is a private template configuration owned by one Agent. Use an Override when an Agent needs instructions, identity, required Skills, or other template content that should not be published to a shared Organization Template. **Core principle** An Agent Override affects only its owning Agent. It never changes the shared Platform or Organization Template, and it cannot be selected by another Agent. ## 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. | Requirement | Use | | --- | --- | | Make behavior available globally | Platform Template | | Share behavior across an organization | Organization Template | | Customize a built-in for an organization | [Organization fork](/guides/templates-and-skills/forks-and-updates) | | Customize only one Agent | Agent Override | | Test a private change before promoting it | Agent Override | | Give several Agents the same change | Organization Template, not multiple Overrides | 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. ### Shared Template, before ``` Organization Template v4 ├── Agent A ├── Agent B └── Agent C ``` ### Agent-owned Override, after ``` 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 ### Included in the snapshot - Template name - Description - `SOUL.md` - `IDENTITY.md` - `USER.md` - `TOOLS.md` - `AGENTS.md` - `BOOT.md` - `BOOTSTRAP.md` - `HEARTBEAT.md` - Standalone and grouped Skill requirements - The exact required Skill Version for every requirement - Each grouped requirement’s `group_key` - Source Template type, key, and version - Author information - Creation and update timestamps ### Not copied or versioned - Secrets - Provider credentials - Channel configuration - Runtime selection - Deployment settings - Agent access assignments - Logs or activity history 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. ## Create an Override To create an Agent-specific Override: 1. Open the Agent. 2. Go to **Configuration**. 3. Select **Agent-owned override**. 4. Select **Create override**. 5. Edit the template name or description if needed. 6. Edit the required Markdown artifacts. 7. Review the required Skills. 8. Select **Save draft**. 9. Review the saved draft. 10. Select **Publish** when it is ready. The initial draft is seeded from the Agent’s currently active configuration. If the Agent uses a shared Template, the draft copies that exact Platform or Organization version. If the Agent already uses an Override, **Create new draft** copies the active Override Version. **Important** The draft is a full snapshot. It does not contain only the fields that differ from the source. ## Work with an Override Draft Each Agent can have one Override Draft at a time. The draft is private to the Agent and remains editable until it is published. Saving the draft does not change the Agent’s active configuration. The draft editor supports the Template name, description, all eight Markdown artifacts, standalone required Skills, and “at least one of” required Skill groups. Retained requirements preserve their exact Skill Version pins; a newly added requirement resolves to that Skill’s latest published version when added. Omitted requirement fields retain their saved values. Supplying only standalone requirements preserves existing groups, and supplying only groups preserves existing standalone requirements. A Skill cannot be both standalone and grouped, or appear in multiple groups. The Override Draft update contract does not accept `required_skill_versions`. To continue an existing draft: 1. Open the Agent’s configuration. 2. Select **Agent-owned override**. 3. Find **Override draft**. 4. Select **Edit**. 5. Make the required changes. 6. Select **Save draft**. Selecting **Cancel** exits the current editing session and leaves the previously saved draft intact. **Tip** Save the draft before leaving the page. The saved draft remains available even when the Agent continues using another published configuration. ## Publish an Override Version Publishing freezes the current draft as the next immutable Override Version. 1. Open the saved Override Draft. 2. Review every artifact. 3. Confirm its required Skills. 4. Select **Publish**. 5. Review the confirmation. 6. Select **Publish override**. Publishing: - Creates the next Agent-owned Override Version - Records the author - Copies the complete draft snapshot - Clears the published draft slot - Preserves previous Override Versions - Leaves the Agent’s active configuration unchanged If the Agent has no published Override Versions, the first publish creates Override `v1`. ## Publishing does not activate the Override After publication, the Agent keeps its current pin until you select the new version. ### After publishing ``` Active configuration: Organization Template v4 Published Override history: └── Override v1 ``` The Agent continues using Organization Template `v4`. ### After applying ``` Active configuration: Agent Override v1 Published Override history: └── Override v1 · Active ``` Select Override `v1` in **Template selection** and apply it. This separation lets you publish safely without restarting or changing a production Agent. ## Apply a published Override 1. Open the Agent. 2. Go to **Configuration**. 3. Select **Template selection**. 4. Open the Template version selector. 5. Find the entry labeled **Agent override**. 6. Select the exact Override Version. 7. Preview its artifacts and required Skills. 8. Select **Apply** or **Apply & Restart**. 9. Confirm the change. For a stopped Agent, **Apply** changes the pin and leaves the Agent stopped. For a running Agent, **Apply & Restart** stops the Agent, selects the Override Version, and starts the Agent again. The restart is required because Agent Barn generates runtime configuration when the Agent starts. ## Create another Override Version After applying an Override, you can create another revision: 1. Open **Agent-owned override**. 2. Select **Create new draft**. 3. Edit the new draft. 4. Save it. 5. Publish it. 6. Open **Template selection**. 7. Apply the new published version. The new draft is copied from the Agent’s active Override. ``` Active Override v1 │ ├── Create new draft │ ├── Edit and publish ▼ Published Override v2 Active remains Override v1 until Override v2 is applied. ``` ## Roll back an Override Rollback means selecting a previous immutable Override Version. It does not create another version, and it does not alter an existing draft. 1. Open the Agent’s configuration. 2. Select **Template selection**. 3. Find the previous **Agent override** version. 4. Preview the complete snapshot. 5. Verify its required Skills. 6. Select **Apply** or **Apply & Restart**. 7. Verify the Agent after activation. Published Override history after rolling back to `v1`: - **Override v3** Published from the third draft - **Override v2** Published from the second draft - **Override v1 Active** Published from the first draft There is no separate rollback endpoint. Historical selection is the rollback operation. **Important** Rolling back an Override does not roll back Secrets, Skills assigned directly to the Agent, runtime settings, or channel configuration. ## 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. ### Platform source ``` Override source: Platform v2 Latest source: Platform v4 Label: Platform update ``` ### Organization source ``` 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. ### Before ``` Active: Override v2 Source: Organization Template v3 Draft: Local unpublished work ``` ### After ``` 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. **Source update** Applying a source update never mutates or merges the Override Draft, never publishes a new Override Version, and leaves existing published Override Versions and their exact Skill requirements unchanged. A stopped Agent selects the shared version directly; a running Agent uses Apply & Restart. ## 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 ``` **Warning** If an older saved draft already exists, creating an Override returns that existing draft instead of replacing it. Publish and preserve that work before starting a clean draft from the newer active source. ## 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 | Action | Required authority | | --- | --- | | View Agent configuration | Access to the Agent | | Create or edit an Override Draft | `agent.update` | | Publish an Override | `agent.update` | | Apply to a stopped Agent | `agent.update` | | Apply to a running Agent | `agent.update` and lifecycle permission | | Change a shared Template definition | Separate Template management permission | **Permissions** Template management permission is not implied by the ability to create an Agent Override. The Override remains inside the Agent access boundary. ## 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 ### I published an Override, but the Agent still uses the shared Template Publishing never activates Publishing does not activate an Override. Open **Template selection**, select the published Agent Override Version, and apply it. ### The Override changed after restart but not before it Configuration is generated at start Template configuration is generated when the Agent starts. A running Agent must restart to load a newly selected version. ### I cannot publish the draft Permissions, Skills, or a conflict Check that: - The draft still exists - You have `agent.update` permission - Its required Skills are assigned - Required Skill providers are configured - The draft has not changed since you loaded it Refresh the page if the server reports a concurrency conflict. ### The right Skill lineage is assigned, but validation still fails Exact version required The Override requires the exact pinned Skill Version. Assigning another version from the same lineage does not satisfy the requirement; select the matching version and configure any required provider. ### Create override opened an existing draft One draft per Agent Each Agent has only one saved Override Draft. If one already exists, Agent Barn returns it instead of replacing it. Review and publish that draft before creating another one from the active configuration. ### Applying a source update did not change my draft Expected: drafts are preserved This is expected. Source updates change the Agent’s active shared pin and deliberately leave private draft work unchanged. ### A newer Skill Version was published, but this Override did not change Pins do not advance automatically Drafts, published Override Versions, and selected Agent configurations retain their exact Skill Version pins. Edit the draft or select a different complete version explicitly when you want to adopt a newer Skill. ### My Override does not show a source update Only the direct source is checked A source update appears only when the active configuration is an Override, its exact direct source can still be resolved, and that direct Platform or Organization lineage has a newer version. An Override based on an Organization source does not independently follow the Organization Template’s Platform origin. ### Another Agent cannot see this Override Overrides are Agent-owned Overrides are Agent-owned and intentionally private. Publish the content as an Organization Template if it must be shared. ### A required private Skill belongs to another Agent Private Skills do not cross Agent boundaries Another Agent’s private Skill is never available to this Override. Use a visible Platform or Organization Skill, or create a private Skill owned by this Agent. ### I cannot apply an Override to a running Agent Lifecycle permission required Applying a running change requires both Agent update and lifecycle permissions. Use **Apply & Restart**. The raw selection API requires the Agent to be stopped first. ### Applying an old Override fails because a Skill is missing The exact version is revalidated Agent Barn revalidates the exact version’s Skill requirements during selection. Restore access to the Skill, assign it to the Agent, and configure its required provider credentials. ### Rolling back did not restore Secrets or channel settings Rollback covers the Template only Override rollback covers only the Template snapshot. Secrets, deployment configuration, channel access, runtime selection, and other Agent settings are separate. ## 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](/guides/templates-and-skills/skills) to learn how Skills package reusable instructions, and how Template requirements interact with an Agent’s assigned capabilities. - [Manage forks and updates](/guides/templates-and-skills/forks-and-updates) - [Manage template versions](/guides/templates-and-skills/template-versions) - [Configure an Agent](/guides/agents/configuration) - [Review Agent health and logs](/guides/agents/health-and-logs)