Summary

Retiring an agent version in DAVE marks it unavailable for new workflow assignments while leaving every running instance untouched. This guide covers when to retire, how to do it, and what to watch for before you click the button.

The steps

1
Navigate to the Agents page
In the sidebar, click Agents. The Agents page opens on the Agents tab, showing a table of all agents in your tenant. The table displays each agent's name, status badge (green for active, gray for inactive, red for error), tags, and total version count.
You need the Admin or Create role to retire versions. If the Agents sidebar link is not visible, your account has the Use or Reporting role, which does not include agent access. Ask your administrator to assign the appropriate role under Admin → Settings → Users & Roles.
Do this
- Click Agents in the sidebar.
- Confirm you are on the Agents tab (not the Prompt Library tab).
- Locate the agent whose version you want to retire.
Example
A team has an agent named "Content Summarizer" that was updated last week. They navigate to the Agents page and find it in the table. The Versions column shows 3, meaning three versions exist. They need to retire v1 and v2 now that v3 is confirmed working.
Best practice
- Before retiring, confirm the replacement version is working correctly in a test or staging workflow. Retirement is permanent: there is no rollback.
- If you cannot see the Agents sidebar link at all, you do not have the required role. Do not proceed until your administrator has assigned you Admin or Create access.
2
Open the agent detail page
Click the agent's name in the table. The agent detail page opens, showing the agent's name, description, status badge, and tags at the top. Below that is the Versions section, a chronological list of every version created for this agent.
Each version row shows:
- The version number (v1, v2, v3, and so on) in bold.
- The created date, shown with a clock icon.
- An amber Retired badge if the version has already been retired.
- A Retire button on the right side of the row, visible only for non-retired versions.
Review the version list before proceeding. Identify which version you want to retire and confirm that at least one non-retired version will remain after you do. An agent with all versions retired cannot be selected in any new workflow.
Do this
- Click the agent's name in the Agents table.
- Review the Versions section on the detail page.
- Identify the version to retire.
- Confirm at least one other non-retired version will remain.
Example
The "Content Summarizer" detail page shows three versions. v1 and v2 have no Retired badge and both show a Retire button. v3 also has no Retired badge. The team plans to retire v1 first, then v2. v3 will remain active.
Best practice
- Check the Versions column on the agent list page before opening the detail page. If it shows 1, retiring that version will leave the agent with no usable versions, which will break any new workflow that tries to reference it.
- Read the created dates on each version row. The most recently created version is typically the one you want to keep active. Retire older ones in order, oldest first, to keep the version history clean.
3
Click Retire on the target version
On the version row you want to retire, click the Retire button on the right side of the row. The action takes effect immediately.
After retirement:
- The version row displays an amber Retired badge next to the version number.
- The Retire button disappears from that row. There is no un-retire option.
- The version receives a retiredAt timestamp, which is recorded in the audit trail.
- No new workflow versions or instances can select this retired version.
- Any existing running workflow instances that were already using this version continue to run unaffected until they complete.
Repeat this step for each additional version you want to retire. Each retirement is a separate action on its own row.
Do this
- Click Retire on the version row you want to retire.
- Confirm the amber Retired badge appears on that row.
- Confirm the Retire button is gone from that row.
- Repeat for any other versions to retire.
Example
The team clicks Retire on the v1 row. The amber Retired badge appears immediately and the Retire button disappears. They then click Retire on the v2 row. Both v1 and v2 now show the Retired badge. v3 remains active with its Retire button still visible.
Best practice
- There is no confirmation dialog documented for the Retire action. Click deliberately: the action is immediate and permanent.
- If you need the same configuration as a retired version in the future, open the retired version row, copy the Config JSON, and create a new version with that JSON. The new version receives the next sequential version number automatically.
4
Verify the retirement in the Workflow Editor
To confirm the retired version is no longer selectable, open any workflow in the Workflow Editor that uses this agent (or create a test workflow). Select the Agent Interaction node that references the agent and open the Properties Panel.
In the agent version selector for this node, the retired version should not appear as an available option. Only non-retired versions are listed. If a workflow was already saved with the retired version assigned, that assignment remains valid for existing instances, but the retired version will not appear as a choice when configuring new nodes or creating new workflow versions.
You can also verify via the Troubleshooting note in the agents documentation: if all versions of an agent are retired, the agent will not appear in the Workflow Editor's agent selection dropdown at all. This is the signal that you have retired too aggressively and need to create a new active version.
Do this
- Open a workflow in the Workflow Editor that uses the agent.
- Select the Agent Interaction node.
- Open the Properties Panel and check the version selector.
- Confirm the retired version is not listed as an available option.
Example
The team opens the "Weekly Content Pipeline" workflow in the Workflow Editor, selects the Agent Interaction node that uses "Content Summarizer", and opens the Properties Panel. The version dropdown shows only v3. v1 and v2 are not listed. The retirement is confirmed.
Best practice
- If you retire a version that is currently assigned to a saved workflow node, update that node to reference an active version before the next workflow instance runs. Existing running instances are safe, but new instances triggered after the retirement will fail if the node still references a retired version and no fallback is configured.
- After retiring old versions, document the reason in the agent's Description field or in your team's internal notes. The audit trail records the retirement timestamp and acting user, but not the reason. A brief note in the Description ("v1 and v2 retired 2026-08-30: replaced by v3 with updated brand voice prompt") helps future editors understand the version history at a glance.

What retiring a version actually does

Retiring an agent version is a scoped, non-destructive action. It does exactly one thing: it marks the version unavailable for new workflow assignments. Everything else stays the same.

Specifically, retirement does not:

Stop or interrupt any currently running workflow instance that references the retired version.
Delete the version or its configuration from the system.
Affect the agent itself: the agent remains active and available as long as at least one non-retired version exists.
Remove the version from the audit trail or version history.

What retirement does:

Sets a retiredAt timestamp on the version record, logged in the audit trail.
Displays an amber Retired badge on the version row in the agent detail page.
Removes the version from the selectable options when a workflow designer configures an Agent Interaction node.
Prevents new workflow instances from being created with the retired version.

The result is a clean separation between historical record and active availability. The version history is preserved for audit and reference. The retired version is simply not on offer for anything new.

When to retire a version and when to wait

The agents documentation is direct on this: retire old versions promptly once you have confirmed a new version works correctly. Leaving old versions active creates risk: another workflow designer might select the old version by mistake, especially in a tenant with many agents and many versions.

Retire when:

A newer version supersedes it. You have created v2 or v3, tested it in a staging workflow, and confirmed it produces the expected output. The old version serves no purpose for new work.
The configuration contains an outdated system prompt or incorrect parameters. A prompt that no longer reflects current requirements, a model that has been deprecated by the provider, or temperature and token settings that produced poor results are all good reasons to retire.
A model referenced in the config has been deprecated. If the AI provider has retired a model, any agent version that references it will fail at runtime. Retire the version and create a new one pointing to a supported model.

Wait to retire when:

The replacement version is not yet confirmed. Do not retire the current version until you have verified the new one works correctly in a real or representative workflow run. Retiring first and discovering a problem second leaves you with no active version.
Active workflow instances are in progress. Running instances are not interrupted by retirement, but if your workflow design routes failures back to a human review step that might re-invoke the agent, confirm the retry path uses an active version before retiring the old one.
The version is the only one. An agent with all versions retired cannot be used in any new workflow. If you need to replace a single-version agent, create the new version first, verify it, then retire the old one.

Who can retire versions

Version retirement is an agent write operation. DAVE ships with six default tenant roles: Admin, Create, Curate, Use, Reporting, and Financial. All roles are editable by your administrator.

Action	Admin	Create	Curate	Use	Reporting
View agent detail and version list	Yes	Yes	Yes	No	No
Create new versions	Yes	Yes	No	No	No
Retire versions	Yes	Yes	No	No	No

Curate-role users can view the agent detail page and see the version list, including which versions are retired, but they cannot click the Retire button. The button is not visible to Curate users. This makes Curate the right role for workflow designers who need to reference agents without being able to modify them.

Use and Reporting roles cannot access the Agents section at all. The sidebar link is not visible to these roles.

If you need to retire a version but do not have the required role, ask your administrator to assign you the Admin or Create role under Admin → Settings → Users & Roles.

Frequently asked questions

Can I un-retire a version?

No. Retirement is a one-way action. Once a version is retired, it cannot be restored to active status. If you need the same configuration again, open the retired version row to reference its Config JSON, then create a new version with that JSON. The new version receives the next sequential version number.

What happens to workflows that are already using a retired version?

Existing running workflow instances that were already using the retired version when it was retired continue to run unaffected. They use the retired version's configuration until they complete. Retirement only prevents new instances from selecting the retired version going forward.

What if I retire all versions of an agent?

An agent with all versions retired will not appear in the Workflow Editor's agent selection dropdown. Any new workflow instance that tries to invoke that agent will fail. If this happens, create a new version with the correct configuration to restore the agent to active availability.

Does retiring a version affect the agent's status?

Not directly. The agent's status (active, inactive, error) is separate from its version retirement state. An agent remains active as long as at least one non-retired version exists and the agent itself has not been set to inactive. If all versions are retired, the agent effectively becomes unusable for new work even if its status badge still shows active.

Is retirement logged in the audit trail?

Yes. The retirement action sets a retiredAt timestamp on the version record and is captured in the audit trail with the acting user's identity. When SOC 2 or GDPR compliance is enabled for the tenant, agent version changes including retirements are tracked as configuration changes, supporting SOC 2 CC8.1 change management requirements.

Can I retire a version that is currently assigned to a saved workflow node?

Yes, the platform allows it. Existing running instances using that version are not affected. However, if the workflow node still references the retired version when a new instance is triggered, that new instance may fail at the agent invocation step. Update the workflow node to reference an active version before triggering new instances.