Join the Waitlist
Guide

How to Version an Agent Prompt Safely in DAVE

By DAVE by voolama6 stepsUpdated AUG 2026AI

Summary

Changing an agent's system prompt without a version record is how silent regressions happen. This guide covers the full safe-versioning workflow: creating a new version, testing it in isolation, retiring the old one, and rolling back without disrupting active workflow instances.

The steps

  1. Open the agent detail page

    Navigate to Agents in the left sidebar. The Agents page shows a table of all agents in your tenant with four columns: Name, Status, Tags, and Versions. Find the agent whose prompt you want to update and click its name to open the agent detail page.

    The detail page shows the agent's name and description at the top, a status badge in the top-right corner, tags as labeled chips below the header, and a Versions section listing every version in chronological order. Each version row shows the version number in bold (v1, v2, v3), the creation date with a clock icon, an amber Retired badge if the version has been retired, and a Retire button for any non-retired version.

    Before creating a new version, read the existing version rows. Note which version number is currently active and which versions, if any, are already retired. This gives you the full history before you add to it.

    Do this
    • Click Agents in the left sidebar.
    • Find the agent you want to update in the table and click its name.
    • On the detail page, read the Versions section. Note the current highest version number and which versions are active versus retired.
    • If you need to read the current Config JSON before writing the new one, there is no inline viewer on the version row: you will need to refer to your own records or the workflow editor's agent configuration panel, which shows the version's model and prompt when selected.
    Example

    A content team lead opens the Blog Post Summarizer agent. The Versions section shows two rows: v1 (retired, amber badge) and v2 (active, Retire button visible). The next version they create will be v3.

    Best practice

    Only users with the Admin or Create role can create or retire versions. The Curate role can view the detail page but cannot modify it. DAVE ships with six default tenant roles (Admin, Create, Curate, Use, Reporting, and Financial), all editable by your administrator. Confirm you have the right role before starting: if the Create Version button is missing from the Versions section header, your role does not include version creation.

  2. Draft the new Config JSON before touching the form

    The Config JSON editor is a plain monospaced textarea. There is no diff view, no autosave, and no draft state: once you click Create Version, the version is permanent and immutable. Drafting the new JSON before opening the form reduces errors and gives you a chance to review the change in isolation.

    A typical Config JSON for a prompt update looks like this:

    {
 "systemPrompt": "You are an editorial summarizer. Given a long-form article, produce a concise two-sentence abstract. Be factual and neutral. Do not add information not present in the source text. Always write in the present tense.",
 "model": "gpt-4o",
 "temperature": 0.2,
 "maxTokens": 256,
 "topP": 1.0
}

    The fields you are most likely to change when updating a prompt are systemPrompt and, if you are also switching models, model. Keep all other fields (temperature, maxTokens, topP) identical to the current version unless you have a specific reason to change them: changing multiple variables at once makes it harder to attribute output differences to a single cause.

    Validate your JSON before pasting it into the form. Common errors: trailing commas after the last property, single quotes instead of double quotes, unquoted keys, or unbalanced braces. Any of these will produce a validation error when you click Create Version.

    Do this
    • Copy the Config JSON from your current active version (from your records or the workflow editor's agent panel).
    • Paste it into a text editor outside DAVE.
    • Make your prompt changes to the systemPrompt field only, unless you also intend to change the model or other parameters.
    • Validate the JSON: all keys and string values in double quotes, no trailing commas, all braces balanced.
    • Keep the drafted JSON ready to paste into the DAVE form in the next step.
    Example

    The team lead copies the v2 Config JSON from their team's shared document, opens a text editor, and updates the systemPrompt field to add the instruction "Always write in the present tense." They leave temperature, maxTokens, and topP unchanged. They paste the JSON into a validator and confirm it is valid before returning to DAVE.

    Best practice

    Treat each version as a single, purposeful change. If you need to update the prompt AND switch to a new model, consider whether to do both in one version or in two sequential versions. Two versions gives you a cleaner audit trail: if the new model produces unexpected output, you know whether the prompt change or the model change caused it. One version is simpler if you are confident both changes are correct.

  3. Create the new version

    On the agent detail page, click Create Version in the Versions section header. A form panel expands with a single field: the Config (JSON) monospaced textarea.

    Paste your drafted and validated JSON into the textarea. Review it once more in context. Then click Create Version to save.

    The system automatically assigns the next sequential version number. You cannot choose or skip version numbers. The new version row appears immediately in the Versions section with its version number, today's date, and a Retire button. The version is now immutable: its Config JSON cannot be edited. If you made a mistake, you will create another new version to correct it.

    Do this
    • Click Create Version in the Versions section header.
    • Paste your validated Config JSON into the Config (JSON) textarea.
    • Read through the JSON one final time before submitting.
    • Click Create Version.
    • Confirm the new version row appears with the correct version number and today's date.
    • If you see a JSON validation error, correct the syntax and click Create Version again. The form stays open on error.
    Example

    The team lead clicks Create Version, pastes the updated JSON, and clicks Create Version to save. The Versions section now shows three rows: v1 (retired), v2 (active), and v3 (active, just created). Both v2 and v3 are currently active.

    Best practice

    Do not retire the previous version immediately after creating the new one. Leave both active while you test the new version. Retiring too early means any workflow that tries to use the old version for a new instance will fail to find it, but more importantly, you lose the ability to quickly compare behavior between versions during testing. Retire only after you have confirmed the new version works correctly.

  4. Test the new version in a draft workflow before promoting it

    A new agent version is available in the workflow editor's agent selection dropdown as soon as it is created. Before updating any production workflow to reference the new version, test it in a draft or staging workflow instance.

    Create a minimal test workflow, or use an existing draft: a Start node, a User Interaction node to supply representative input, an Agent Interaction node configured to use your agent at the new version number, and an End node. Run a test instance with input that covers the range of content the agent will see in production.

    Evaluate the output against the intent of your prompt change. If the change was to add a constraint (such as "always write in the present tense"), verify the constraint is applied consistently. If the change was to improve accuracy or tone, compare the new output to the previous version's output on the same input.

    If the output is not what you expected, return to the agent detail page, create another new version with a corrected Config JSON, and test again. The previous new version remains in the history but you can retire it to remove it from circulation.

    Do this
    • Navigate to Workflows in the sidebar and open a draft or staging workflow, or create a minimal test workflow.
    • Add or update an Agent Interaction node to reference your agent at the new version number.
    • Run a test instance with representative input.
    • Review the output against your expected behavior.
    • If the output is correct, proceed to the next step. If not, create another new version with corrected JSON and retest.
    Example

    The team lead opens their existing test workflow, updates the Agent Interaction node to reference Blog Post Summarizer v3, and runs three test instances with different article lengths. All three produce two-sentence abstracts written in the present tense. The new version behaves as intended.

    Best practice

    Test with input that represents the edges of what the agent will encounter in production, not just the easy cases. A prompt that works on a 500-word article may behave differently on a 5,000-word article or on content in a different format. The more representative your test input, the more confident you can be before promoting the new version to production workflows.

  5. Update production workflows to reference the new version

    Once the new version is confirmed to work correctly, update your production workflows to reference it. In the Workflow Editor, open each workflow that uses this agent, find the Agent Interaction node, and change the version selector from the old version to the new one. Save a new workflow version to record the change.

    Active workflow instances that are already running continue to use the version they were started with. Changing the workflow version does not affect instances that are already in progress: they run to completion using the agent version that was configured when they started. Only new instances, started after the workflow version is saved, will use the new agent version.

    This means the transition is safe by design. You do not need to wait for all active instances to complete before updating the workflow. Old instances finish with the old agent version; new instances start with the new one.

    Do this
    • Navigate to Workflows in the sidebar and open each production workflow that references this agent.
    • In the Workflow Editor, find the Agent Interaction node that references the agent.
    • Change the version selector to the new version number.
    • Save a new workflow version to record the change.
    • Repeat for each workflow that references this agent.
    • Confirm that new instances started after the workflow version change are using the new agent version by checking instance output.
    Example

    The team lead opens the two production workflows that use Blog Post Summarizer. In each one, they update the Agent Interaction node from v2 to v3 and save a new workflow version. Three instances that were already running continue to completion using v2. All new instances started after the save use v3.

    Best practice

    If multiple workflows reference the same agent, update them all before retiring the old version. A workflow that still references a retired version will fail to start new instances: the version selector will show the version as unavailable. Check all workflows that reference the agent before retiring.

  6. Retire the old version

    Once all production workflows have been updated to the new version and you have confirmed new instances are producing correct output, retire the old version. On the agent detail page, find the old version row and click its Retire button.

    Retiring marks the version with a retiredAt timestamp and displays an amber Retired badge. The Retire button disappears from the row. The version can no longer be selected for new workflow assignments. Any workflow that still references the retired version will fail to start new instances.

    Retiring is a one-way action. You cannot un-retire a version. If you later need the same configuration, create a new version with the same Config JSON. The retired version remains in the history permanently as an immutable record of what that configuration was.

    If you discover after retiring that the new version has a problem, the retired version is not available for new instances. Your options are: create a new version that restores the old Config JSON (an effective rollback), or fix the problem in another new version. Either way, active instances already running on the new version are not affected by your decision: they run to completion with the version they started on.

    Do this
    • Confirm all production workflows have been updated to the new version.
    • Confirm new instances are producing the expected output.
    • On the agent detail page, find the old version row and click Retire.
    • Confirm the amber Retired badge appears on the row and the Retire button is gone.
    • Optionally, check any remaining workflows that reference this agent to confirm none are still pointing at the now-retired version.
    Example

    After two days of production use, the team lead is confident v3 is working correctly. They open the Blog Post Summarizer detail page, find the v2 row, and click Retire. The amber Retired badge appears. The Versions section now shows: v1 (retired), v2 (retired), v3 (active). The agent's history is clean and unambiguous.

    Best practice

    Wait at least one full production cycle before retiring the old version. If your workflows run daily, wait a day. If they run weekly, wait a week. This gives you time to observe new-version output in production before removing the fallback option of creating a rollback version quickly. The cost of waiting is low: a retired version is just an inactive row in the history. The cost of premature retirement is higher: if a problem appears after you retire, your rollback path requires creating a new version rather than simply re-pointing workflows at the old one.

Why versioning a prompt is not optional

A system prompt is not a static document. It is the behavioral specification for an AI agent, and it will need to change: to fix a constraint that was too loose, to add an instruction the original prompt omitted, to adapt to a new content type, or to correct a pattern of output that does not meet the required standard.

The question is not whether the prompt will change, but whether the change will be safe and traceable. Without versioning, a prompt change is invisible: the agent's behavior shifts, output quality changes, and there is no record of what changed, when, or why. If the change causes a problem, there is no clean rollback path and no audit trail to investigate.

DAVE's versioning model makes prompt changes safe by construction. Each version is an immutable snapshot: once created, its Config JSON cannot be edited. Version numbers are auto-incremented integers assigned by the system. You cannot skip, reuse, or delete version numbers. The result is a permanent, ordered history of every configuration the agent has ever run, with the date each version was created and the date each was retired.

This history is not just useful for debugging. It is the foundation of accountability for AI behavior in a business process. When a stakeholder asks "what was the agent doing when it produced this output last Tuesday?", the answer is in the version history: find the version that was active on that date, read its Config JSON, and you have a precise answer.

How active workflow instances are protected during a version change

The most important property of DAVE's versioning model for safe prompt updates is this: changing an agent version does not affect workflow instances that are already running.

When a workflow instance starts, it records the agent version configured for each Agent Interaction node at that moment. That version reference is fixed for the lifetime of the instance. If you create a new agent version, update the workflow to reference it, and save a new workflow version, instances that were already running before the workflow version change continue to use the version they started with. They are not re-pointed at the new version mid-execution.

This means you can update agent versions and workflow configurations at any time, without waiting for a quiet period or coordinating with users who have active instances in progress. The transition is safe by design:

  • Instances started before the workflow version change: run to completion using the old agent version.
  • Instances started after the workflow version change: use the new agent version from the start.

The same protection applies to retiring a version. Retiring removes a version from the selection pool for new workflow assignments, but it does not interrupt instances that are already using it. A running instance that reaches an Agent Interaction node configured for a retired version will still execute correctly: the version's Config JSON is stored and available for the lifetime of the instance regardless of its retirement status.

This isolation between running instances and configuration changes is what makes it safe to iterate on agent prompts in a live environment without a maintenance window.

How to roll back a prompt change without disrupting active workflows

DAVE does not have a one-click rollback button. What it has is something more durable: an immutable version history and the ability to create a new version with any Config JSON you choose, including the JSON from a previous version.

If a new agent version produces incorrect output and you need to revert to the previous behavior, the process is:

  1. Do not retire the new version yet. Active instances using the new version will run to completion regardless, but retiring it now removes it from the audit trail's active pool and may cause confusion.
  2. Create a new version with the previous Config JSON. Open the agent detail page, click Create Version, and paste in the Config JSON from the version you want to restore. This becomes the next sequential version number (for example, v4 if you are rolling back from v3).
  3. Test the restored version in a draft workflow to confirm it reproduces the expected behavior.
  4. Update production workflows to reference the restored version, exactly as you would for any new version.
  5. Retire the problematic version once all workflows have been updated and new instances are running correctly on the restored configuration.

This approach is slightly more steps than a one-click rollback, but it has an important advantage: the version history remains honest. The problematic version is not erased: it is retired, with its creation date and retirement date visible in the history. Anyone reviewing the audit trail can see exactly what happened: a new version was created, it was active for a period, it was retired, and a corrective version was created. That is a more accurate record than a rollback that makes it appear the problematic version never existed.

The key point for active instances: because running instances are not affected by version changes, a rollback does not require stopping or canceling any in-progress work. Instances running on the problematic version complete normally. New instances start on the restored version as soon as the workflow is updated.

Using the Prompt Library for prompt-level versioning

Agent versioning (creating a new version with updated Config JSON) is the primary mechanism for changing an agent's prompt safely. The Prompt Library offers a complementary approach: managing prompts as independent, named templates that can be assigned to agents and updated separately from the agent's version history.

The Prompt Library is accessible from the Prompt Library tab on the Agents page. Users with the Admin or Create role can create, edit, and assign prompts. When a library prompt is assigned to an agent, the agent creator can lock it: when locked, the prompt selector for that agent is greyed out in the Workflow Editor, so workflow designers cannot override it at the node level.

The Prompt Library is useful when:

  • The same prompt is shared across multiple agents, and you want to update it in one place rather than creating new versions for each agent separately.
  • You want to separate prompt management (a content or editorial concern) from agent configuration management (a technical concern), assigning different team members to each.
  • You want to use the AI Assistant to generate or refine prompts before assigning them to an agent.

The Prompt Library does not replace agent versioning. When you change a library prompt and reassign it to an agent, the agent's behavior changes, but the change is not captured as a new agent version unless you explicitly create one. For full auditability of prompt changes, create a new agent version whenever you update the prompt, whether the prompt comes from the library or is written inline in the Config JSON.

Frequently asked questions

Can I edit an existing version's Config JSON?

No. Every version is immutable once created. If you need to change the Config JSON, create a new version. The old version remains in the history unchanged. This immutability is intentional: it ensures the version history is a reliable audit record of what configuration was running at any point in time.

What happens to running workflow instances when I create a new agent version?

Nothing. Running instances are not affected by new version creation. An instance records the agent version it was configured to use when it started, and it uses that version for its entire lifetime. New instances started after you update the workflow to reference the new version will use the new version. Instances already in progress continue with the version they started on.

Can I un-retire a version?

No. Retiring is a one-way action. Once a version is retired, it cannot be made active again. If you need the same configuration, create a new version with the same Config JSON. The retired version remains in the history permanently as a record.

What happens if I retire a version that a production workflow still references?

Existing running instances that already reference the retired version are not affected: they continue to use it until they complete. However, new instances of that workflow will fail to start because the version they are configured to use is no longer available for new assignments. Update the workflow to reference an active version before retiring, or immediately after if you need to act quickly.

How do I know which version a running instance is using?

Check the instance detail page in Workflows (or Instances if your workspace has a dedicated Instances view). The instance context records which agent version was used at each Agent Interaction node. If you need to investigate the Config JSON for that version, open the agent detail page and find the version row by number.

Is there a limit to how many versions an agent can have?

The help documentation does not state a version count limit. Create as many versions as your iteration process requires. Retire versions that are no longer needed to keep the active version list clean, but retired versions remain in the history permanently.

The Create Version button is missing. What do I do?

Your user account does not have the Admin or Create role for this tenant. The Curate role can view agent detail pages but cannot create or retire versions. Ask your tenant administrator to assign you the Admin or Create role under Admin → Settings → Users and Roles.