Skip to main content

Agent Version Management

Learn how to update your agent's prompt version without recreating the agent or changing API keys.

Overview​

Version management is a critical feature that allows you to continuously improve your agents while maintaining stability and backward compatibility.

Key Benefits​

  • ✅ API Stability - Keep same agent ID and API keys
  • ✅ Zero Downtime - Update prompts without service interruption
  • ✅ Easy Rollback - Revert to previous versions instantly
  • ✅ Testing Flexibility - Test new prompts without creating duplicates
  • ✅ Continuous Improvement - Iterate based on real usage data

How It Works​

graph LR
    A[Prompt V1] -->|Agent Created| B[Agent]
    C[Prompt V2] -->|Version Update| B
    D[Prompt V3] -->|Version Update| B
    B -->|Always Uses| E[Current Version]
    B -->|API Key Stays Same| F[External Integration]

Version Pinning​

Each agent is pinned to a specific version of a prompt:

  • Immutable Executions - Past executions always reference their original version
  • Controlled Updates - Only update when you explicitly choose to
  • Independent Agents - Multiple agents can use different versions of the same prompt

Updating Agent Versions​

Using the Dashboard​

Step 1: Navigate to Agent​

  1. Go to Agents page (/agents)
  2. Click on your agent to open the detail page
  3. Go to the Overview tab

Step 2: Open Version Selector​

  1. Find the Prompt Version section
  2. Click the Version Selector dropdown
  3. You'll see all available versions for this prompt

Step 3: Review Available Versions​

Each version shows:

  • Version Label (e.g., "V3", "Production", "Experiment-A")
  • Created Date - When this version was created
  • Status Indicator - Shows if this is the current version

Current version is marked with a badge.

Step 4: Select New Version​

  1. Click on the version you want to switch to
  2. Review the change summary (if provided)
  3. Click "Update Version" button
  4. Confirm the update in the dialog

Step 5: Verify Update​

After updating:

  • ✅ Check the Prompt Version section shows new version
  • ✅ Go to Executions tab
  • ✅ Run a test execution
  • ✅ Verify output matches expectations

Using the API​

Update an agent's version programmatically:

curl -X PATCH https://api.promptick.ai/api/agents/agent_abc123/version \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "newPromptVersionId": "version_xyz456",
    "newPromptVersionLabel": "V4"
  }'

Response:

{
  "agent": {
    "id": "agent_abc123",
    "promptVersionId": "version_xyz456",
    "promptVersionLabel": "V4",
    "updatedAt": "2025-11-18T10:20:00Z"
  }
}

Testing New Versions​

Strategy 1: Parallel Testing​

Create a test agent to validate new versions:

  1. Create Test Agent

    • Duplicate your production agent
    • Set status to "Testing"
    • Use a test API key

  2. Update Test Agent

    • Update test agent to new version
    • Keep production agent on current version

  3. Run Test Cases

    • Execute with same inputs as production
    • Compare outputs side-by-side
    • Monitor metrics (latency, cost, quality)

  4. Promote to Production

    • Once validated, update production agent
    • Monitor closely for first few hours
    • Delete test agent or keep for future testing

Strategy 2: Gradual Rollout​

Update production agent and monitor closely:

  1. Before Update

    • Note current metrics (success rate, latency, cost)
    • Ensure you can quickly rollback if needed

  2. Update Version

    • Update during low-traffic period
    • Monitor execution history in real-time

  3. Watch Metrics

    • Success/failure rates
    • Average latency
    • Token usage changes
    • Cost per execution
    • Error patterns

  4. Rollback if Needed

    • If metrics degrade, rollback immediately
    • Investigate issues before trying again

Strategy 3: A/B Testing​

Use multiple agents for controlled comparison:

  1. Create two agents:

    • Agent A: Current version
    • Agent B: New version

  2. Split traffic between them (in your application code)

  3. Track metrics for both agents separately

  4. After sufficient data, choose the better performer

  5. Update losing agent or retire it

Monitoring Version Changes​

Execution History Filtering​

After updating a version, use execution history to compare:

  1. Go to Executions tab
  2. Filter by date range:
    • Before update: Last 7 days before version change
    • After update: Last 7 days after version change
  3. Compare metrics:
    • Success rates
    • Average latency
    • Token usage
    • Cost per execution

Analytics Dashboard​

The Analytics tab shows:

  • Version Performance - Metrics broken down by prompt version
  • Trend Analysis - How metrics changed over time
  • Cost Comparison - Cost differences between versions

Rollback Procedures​

Quick Rollback (Emergency)​

If you detect issues immediately:

  1. Open agent detail page
  2. Click Version Selector
  3. Select previous version
  4. Click "Update Version"
  5. Rollback is instant - new executions use old version immediately

Planned Rollback​

If you're proactively reverting:

  1. Review execution history to identify last good version
  2. Note the version label (e.g., "V2")
  3. Use Version Selector to switch back
  4. Document why you rolled back (for future reference)
  5. Monitor to ensure issues are resolved

Rollback Checklist​

Before rolling back:

  • Identify the issue (error rate, quality, cost, latency)
  • Confirm which version was working correctly
  • Note current version label for documentation
  • Verify previous version is still available
  • Perform rollback
  • Test immediately after rollback
  • Monitor metrics for 1-2 hours
  • Document the incident

Best Practices​

1. Version Labels Matter​

Use clear, descriptive version labels:

Good Labels:

  • Production-Stable - Currently deployed version
  • V3-Shorter-Responses - Describes what changed
  • Experiment-Formal-Tone - Indicates testing purpose
  • 2025-11-18-Update - Date-based versioning

Bad Labels:

  • Version 1, Version 2 (not descriptive)
  • Test (what kind of test?)
  • New (new becomes old quickly)

2. Document Changes​

Keep notes about each version:

  • What changed compared to previous version
  • Why the change was made
  • Expected impact on outputs
  • Any known issues or limitations
tip

Add version notes in the prompt description field so they're visible when selecting versions.

3. Test Before Production​

Never update a production agent without testing:

  1. Create test agent
  2. Update test agent first
  3. Run comprehensive tests
  4. Verify quality and metrics
  5. Only then update production

4. Monitor After Updates​

After updating any agent:

  • Watch execution history for first hour
  • Check error rates
  • Review sample outputs
  • Monitor cost changes
  • Be ready to rollback

5. Gradual Updates​

For critical agents:

  • Update during low-traffic periods
  • Start with less critical agents first
  • Give each update time to prove itself
  • Don't update multiple agents simultaneously

6. Keep Version History​

Don't delete old prompt versions:

  • You might need to rollback weeks later
  • Old versions serve as documentation
  • Useful for understanding evolution
  • Required for compliance/auditing

Common Scenarios​

Scenario 1: Fixing a Bug​

Problem: Agent outputs contain a consistent error

Solution:

  1. Create new prompt version fixing the bug
  2. Create test agent with new version
  3. Verify bug is fixed
  4. Update production agent
  5. Monitor to ensure fix works

Scenario 2: Improving Quality​

Problem: Outputs are correct but could be better

Solution:

  1. Create new version with improvements
  2. Run A/B test with both versions
  3. Compare quality metrics
  4. Update to better version
  5. Keep old version for potential rollback

Scenario 3: Reducing Costs​

Problem: Agent costs are too high

Solution:

  1. Create new version with shorter prompts
  2. Test that quality remains acceptable
  3. Compare token usage and costs
  4. If cost reduction is significant without quality loss, update
  5. Monitor to ensure cost savings are real

Scenario 4: Emergency Rollback​

Problem: New version is causing failures

Solution:

  1. Immediately rollback to previous version
  2. Investigate root cause
  3. Fix the issue in a new version
  4. Test thoroughly before trying again

Version Management API​

For automated version management:

Check Current Version​

GET /api/agents/{agentId}

Returns agent details including promptVersionId and promptVersionLabel.

List Available Versions​

GET /api/prompts/{promptId}/versions

Returns all versions for the prompt.

Update Version​

PATCH /api/agents/{agentId}/version

Updates the agent's prompt version.

Automation Example​

// Automated version update script
async function updateAgentVersion(agentId, newVersionId, newVersionLabel) {
  // 1. Get current version
  const agent = await getAgent(agentId);
  const currentVersion = agent.promptVersionId;

  // 2. Update to new version
  await updateVersion(agentId, newVersionId, newVersionLabel);

  // 3. Run validation tests
  const testPassed = await runValidationTests(agentId);

  // 4. Rollback if tests fail
  if (!testPassed) {
    console.error('Tests failed, rolling back...');
    await updateVersion(agentId, currentVersion, agent.promptVersionLabel);
    throw new Error('Version update failed validation');
  }

  console.log('Version updated successfully');
}

Troubleshooting​

"Cannot update to same version"​

Error: Trying to update to the currently active version

Solution: Select a different version or verify which version is currently active

"Version not found"​

Error: Specified version doesn't exist

Solution:

  • Verify version ID is correct
  • Ensure version belongs to the same prompt
  • Check that version hasn't been deleted

"Agent not found"​

Error: Agent ID is invalid

Solution:

  • Verify agent ID
  • Ensure you have access to this agent
  • Check that agent hasn't been deleted

Updates Not Taking Effect​

Problem: Agent still using old version after update

Solution:

  • Refresh the page
  • Verify update succeeded (check version in Overview tab)
  • New executions should use new version (check execution detail)
  • Old executions still show old version (this is expected)

Next Steps​

Need help? Check our FAQ or contact support.