Versioning
AiQarus uses immutable versioning to ensure audit trails always reference the exact agent configuration that was used.
Why Immutability Matters
When you need to audit an agent’s past behavior, you must know exactly what configuration it was running. If definitions could be modified after the fact:
- Audit trails would be meaningless
- You couldn’t reproduce past behavior
- Compliance would be impossible
- Debugging would be unreliable
The Versioning Model
Agent Definition (v1) → Run A
│ Run B
│ Run C
▼
Agent Definition (v2) → Run D
│ Run E
▼
Agent Definition (v3) → Run FEach run references a specific, immutable version.
Agent States and Transitions
┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────┐
│ DRAFT │─────▶│ ACTIVE │─────▶│ DEPRECATED │─────▶│ ARCHIVED │
└──────────┘ └──────────┘ └──────────────┘ └──────────┘
│ │
│ │
│ └───────────────┐
│ ▼
└──────────────────────────▶ NEW DRAFT (v2)| State | Description | Can Edit | Can Run | Can Version |
|---|---|---|---|---|
| Draft | Work in progress | ✓ | ||
| Active | Production-ready | ✓ | ✓ | |
| Deprecated | Superseded | |||
| Archived | No longer used |
Creating a New Version
When you need to change an active agent:
Step 1: Create New Version
From the agent detail page:
┌─────────────────────────────────────────────────────────────────────┐
│ Customer Support Triage Agent │
│ Version: 3 (Active) │
│ │
│ [Run] [View History] [Create New Version] [Deprecate] │
│ │
└─────────────────────────────────────────────────────────────────────┘Click Create New Version.
Step 2: Edit Configuration
A new draft is created with all settings copied from the current version:
┌─────────────────────────────────────────────────────────────────────┐
│ Customer Support Triage Agent │
│ Version: 4 (Draft) - Based on v3 │
│ │
│ System Prompt: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ You are a customer support triage agent... │ │
│ │ │ │
│ │ [Make your changes here] │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ [Save Draft] [Activate] [Discard] │
│ │
└─────────────────────────────────────────────────────────────────────┘Step 3: Test (Optional)
Draft agents can be tested in a sandbox environment before activation.
Step 4: Activate
When ready, click Activate:
- v4 becomes Active
- v3 is automatically deprecated
- Triggers using the agent now use v4
- Manual runs default to v4
Version History
View all versions of an agent:
┌─────────────────────────────────────────────────────────────────────┐
│ Version History: Customer Support Triage Agent │
│ │
│ v4 Active Jan 15, 2026 "Added priority escalation" │
│ v3 Deprecated Jan 10, 2026 "Improved category detection" │
│ v2 Deprecated Dec 20, 2025 "Added Slack integration" │
│ v1 Archived Dec 1, 2025 "Initial version" │
│ │
│ [Compare Versions] │
│ │
└─────────────────────────────────────────────────────────────────────┘Comparing Versions
See what changed between versions:
┌─────────────────────────────────────────────────────────────────────┐
│ Compare: v3 → v4 │
│ │
│ System Prompt: │
│ ───────────── │
│ - Always categorize tickets into: billing, technical, general │
│ + Always categorize tickets into: billing, technical, general, │
│ + account, escalation │
│ │
│ Constraints: │
│ ──────────── │
│ - max_steps: 15 │
│ + max_steps: 20 │
│ │
│ Capabilities: │
│ ───────────── │
│ + slack_send_urgent_message (added) │
│ │
└─────────────────────────────────────────────────────────────────────┘Running Specific Versions
By default, runs use the active version. To run a specific version:
Via UI
┌─────────────────────────────────────────────────────────────────────┐
│ Run Agent: Customer Support Triage │
│ │
│ Version: [v4 (Active) ▼] │
│ ├─ v4 (Active) │
│ ├─ v3 (Deprecated) - for comparison only │
│ └─ v2 (Deprecated) - for comparison only │
│ │
└─────────────────────────────────────────────────────────────────────┘Via API
mutation RunAgent($input: RunAgentInput!) {
runAgent(input: {
agentId: "agent_123"
version: 3 # Specific version
input: { ... }
}) {
id
status
}
}Running deprecated versions is useful for debugging but should not be used in production workflows.
Audit Trail Integration
Every run’s audit trail includes the exact version used:
{
"trace_id": "trace_789",
"event_type": "run_started",
"payload": {
"agent_id": "agent_123",
"agent_version": 4,
"agent_definition_hash": "sha256:a1b2c3d4..."
}
}The agent_definition_hash is a SHA-256 hash of the complete agent configuration, providing cryptographic proof of what was running.
Best Practices
Use Descriptive Version Notes
When creating a new version, document what changed:
Good: "Added Slack escalation for urgent tickets, increased max_steps to handle complex cases"
Bad: "Updated agent"Don’t Modify Active Agents
If you need to make changes:
- Create a new version (draft)
- Test the draft
- Activate when ready
Never try to bypass immutability.
Archive Old Versions
Deprecated versions consume space. After sufficient time (check your retention policy), archive them:
- Archived versions remain viewable for audit
- They don’t appear in version selectors
- They can be restored if needed
Version for Significant Changes Only
Not every tweak needs a new version. Consider:
- New version: Changed behavior, new capabilities, modified constraints
- Same version: Fixed typo in description, updated documentation