Agents

Agent Cloning & Versioning

Agents can be cloned and versioned. Cloning creates a full copy of an agent including its config, system prompt, and memory snapshot. Versioning tracks the lineage of changes over time with rollback support, so you can recover from a bad config change or compare how an agent behaved across prompt iterations.

Cloning an agent

Clone an existing agent with a single API call. The clone is created as a new independent agent with a new ID and starts at version 1:

bash
POST /agents/:id/clone
{
  "newId": "research-agent-v2",       # Optional — auto-generated if omitted
  "displayName": "Research Agent (Experimental)",
  "includeMemory": true              # Whether to copy the memory snapshot
}

# Response
{
  "agentId": "research-agent-v2",
  "clonedFrom": "research-agent",
  "version": 1,
  "createdAt": "2025-11-14T10:00:00Z"
}

The following are always copied from the source agent:

  • Full agent configuration (model, tool allow list, spawn settings, quotas, self-healing config)
  • System prompt template
  • Domain registrations
  • Memory snapshot (if includeMemory: true; default is true)

The following are not copied: active sessions, runtime state, conversation history, and event bus subscriptions. The clone starts clean.

Versioning

Every time an agent's configuration is saved — whether through the API, the dashboard, or a config file reload — a new immutable version is created automatically. The current active config is always the latest version. Previous versions are retained indefinitely unless explicitly deleted.

bash
# List all versions for an agent
GET /agents/:id/versions

# Response
[
  { "version": 3, "createdAt": "2025-11-14T09:55:00Z", "note": "Tuned system prompt for conciseness" },
  { "version": 2, "createdAt": "2025-11-13T14:20:00Z", "note": "Added web_search to allow list" },
  { "version": 1, "createdAt": "2025-11-12T08:00:00Z", "note": "Initial version" }
]

You can attach a human-readable note to a version by including a versionNote field when saving the config via the API. Notes are optional but recommended for tracking intent.

Diffing versions

Compare any two versions of an agent to see exactly what changed between them. The diff covers the full agent config including the system prompt:

bash
GET /agents/:id/versions/:v1/diff/:v2

# Example: diff version 1 against version 3
GET /agents/research-agent/versions/1/diff/3

# Response — JSON Patch format (RFC 6902)
[
  { "op": "replace", "path": "/systemPromptTemplate", "from": "...old...", "value": "...new..." },
  { "op": "add",     "path": "/tools/allowed/-",       "value": "web_search" }
]

Rolling back

Roll back an agent to any previous version with a single call. The rollback creates a new version entry (rather than overwriting history) so the rollback itself is auditable:

bash
POST /agents/:id/rollback/:version

# Example: roll research-agent back to version 1
POST /agents/research-agent/rollback/1

# Response
{
  "agentId": "research-agent",
  "rolledBackTo": 1,
  "newVersion": 4,       # Rollback creates version 4 with v1's config
  "createdAt": "2025-11-14T10:15:00Z"
}

The rolled-back agent is immediately active. Running sessions are not interrupted — they complete their current turn with the old config and pick up the new config on the next turn.

Use cases

Cloning and versioning enable several workflows that are difficult to manage with a single mutable agent:

  • A/B testing agents — clone an agent, modify the system prompt in the clone, and route a percentage of traffic to each. Compare health scorecard metrics to determine which version performs better before promoting.
  • Safe experimentation — make aggressive changes to a clone without affecting the production agent. Promote the clone to production only after validating its behavior in staging traffic.
  • Disaster recovery — if a config change causes a reliability drop, roll back to the last known-good version immediately without needing to reconstruct the previous configuration manually.