Configuration Versioning

Every change to agent configurations is automatically tracked. The versioning system provides complete audit history, field-level diffs, and rollback capabilities — with zero impact on agent runtime performance.

Architecture

Two levels of versioning work together:

Level	Table	Trigger	Purpose
Per-resource	config_history	Automatic (PostgreSQL)	Track every INSERT/UPDATE/DELETE on agents, schemas, triggers, MCP servers
Agent snapshot	builder_versions	On publish	Capture complete agent state for full rollback

┌─────────────────────────────────────────────────────────────────┐
│                      Agent Lifecycle                            │
│                                                                 │
│  edit schema ──► config_history v2 (auto)                       │
│  edit trigger ──► config_history v3 (auto)                      │
│  publish ────────► builder_versions snapshot #1 (auto)          │
│  edit persona ──► config_history v4 (auto)                      │
│  publish ────────► builder_versions snapshot #2 (auto)          │
│                                                                 │
│  rollback to snapshot #1 ──► restores agent + schemas +         │
│                               triggers + MCP servers            │
└─────────────────────────────────────────────────────────────────┘

---

Per-Resource History

What Is Tracked

Resource	Table	Tracked Fields
Agents	builder_agents	name, bio, commercial_name, llm_config, tags, type, visibility, metadata, status
Schemas	builder_agent_schemas	schema_data, schema_type, is_active, metadata, validation_rules
Triggers	builder_agent_triggers	name, trigger_type, trigger_config, enabled, description
MCP Servers	builder_mcp_servers	name, endpoint, transport, auth_method, config, status

What Is NOT Tracked

Statistical/runtime fields are excluded to avoid noisy version history:

updated_at, trigger_count, last_triggered_at, total_interactions, success_rate, avg_response_time, last_interaction, last_connected_at, last_error, tools_count

Version Record Structure

Each version record contains:

Field	Type	Description
id	UUID	Record ID
resource_type	string	agent | schema | trigger | mcp_server
resource_id	UUID	ID of the changed resource
agent_id	UUID	Parent agent (for aggregation)
tenant_id	UUID	Tenant isolation
version	integer	Sequential per resource (1, 2, 3...)
operation	string	INSERT | UPDATE | DELETE
data_before	JSON	State before change (null on INSERT)
data_after	JSON	State after change (null on DELETE)
changed_fields	string[]	Fields that changed (UPDATE only)
changed_by	UUID	User who made the change (when available)
changelog	string	Optional note (auto-filled on rollback)
created_at	timestamp	When the change occurred

---

Agent Snapshots

When an agent is published, a snapshot captures the complete state:

Component	Content
agent_snapshot	Full agent record (name, bio, llm_config, tags, metadata...)
schemas_snapshot	All active schemas at publish time
triggers_snapshot	All triggers linked to the agent
mcp_servers_snapshot	All MCP servers linked to the agent

Snapshots are sequential per agent (version_number: 1, 2, 3...).

Snapshot Rollback

Rolling back a snapshot restores the entire agent to the published state:

1. Agent fields are restored (bio, llm_config, tags, etc.)
2. Current schemas are deactivated; snapshot schemas are reactivated
3. Triggers are updated/recreated from snapshot data
4. MCP servers are updated/recreated from snapshot data

Each individual restoration triggers automatic per-resource versioning — providing full traceability even during rollback.

warning

Snapshot rollback is a destructive operation that overwrites current agent configuration. It does not affect active sessions or conversation history.

---

REST API Endpoints

Per-Resource History

Method	Endpoint	Auth	Description
GET	/api/agents/:agentId/versions/:resourceType/:resourceId	JWT / API Key	List versions of a resource
GET	/api/agents/:agentId/versions/:resourceType/:resourceId/:version	JWT / API Key	Get specific version details
GET	/api/agents/:agentId/versions/:resourceType/:resourceId/compare?from=X&to=Y	JWT / API Key	Field-by-field diff
POST	/api/agents/:agentId/versions/:resourceType/:resourceId/rollback	JWT only	Rollback resource to a version
GET	/api/agents/:agentId/history	JWT / API Key	Agent change timeline

Snapshots

Method	Endpoint	Auth	Description
GET	/api/agents/:agentId/snapshots	JWT / API Key	List publish snapshots
GET	/api/agents/:agentId/snapshots/:snapshotId	JWT / API Key	Get snapshot details
POST	/api/agents/:agentId/snapshots/:snapshotId/rollback	JWT only	Restore agent to snapshot

Query parameters (list endpoints): limit (default 20/50), offset (default 0), resource_type (history only).

Rollback body: { "target_version": 1 } (per-resource only).

---

MCP Builder Tools

The versioning system is accessible via 8 MCP tools in the Versioning domain:

Per-Resource History

Tool	Description
list_versions	List all versions of a resource with pagination
get_version	Get details of a specific version (before/after data)
compare_versions	Field-by-field diff between two versions
rollback_version	Restore a single resource to a previous version
list_agent_history	Combined timeline of all changes for an agent

Snapshots

Tool	Description
list_snapshots	List all published snapshots of an agent
get_snapshot	Full snapshot details (all 4 components)
rollback_snapshot	Restore entire agent to a published state

Example: Compare Two Versions

Using compare_versions to see what changed between version 1 and 3 of an agent:

{
  "resource_type": "agent",
  "resource_id": "2378a810-...",
  "from_version": 1,
  "to_version": 3
}

Response:

{
  "success": true,
  "comparison": {
    "from_version": 1,
    "to_version": 3,
    "diff": {
      "bio": {
        "from": "Original bio text",
        "to": "Updated bio text"
      }
    },
    "changed_field_count": 1
  }
}

Example: Rollback Agent to Previous Version

Using rollback_version to restore an agent's bio to version 1:

{
  "resource_type": "agent",
  "resource_id": "2378a810-...",
  "target_version": 1
}

Response:

{
  "success": true,
  "message": "Resource restored to version 1",
  "restored": { "id": "2378a810-...", "bio": "Original bio text" },
  "restored_to_version": 1,
  "new_version": 4
}

The rollback creates a new version (4) with the restored data — the original version history is preserved.

---

Tenant Isolation

All versioning operations enforce multi-tenant isolation:

• config_history records include tenant_id for filtering
• All queries validate resource ownership before returning data
• Cross-tenant access returns "Resource not found" (no information leakage)
• Trigger records validate tenant_id directly; others validate via agent_id → tenant_agents

---

Zero Runtime Impact

The versioning system has no impact on agent execution performance:

• The PostgreSQL trigger fires AFTER the operation (non-blocking)
• The trigger includes an exception handler (never fails the parent operation)
• The agent loop reads only is_active=true schemas — no queries touch config_history or builder_versions
• Snapshots on publish are fire-and-forget (never block the publish operation)