Skip to content

Drift Detection

Drift is any behavioral change from your agent's established identity. Identity OS classifies drift into 4 levels and responds automatically — including rollback at critical thresholds.

The 4 Drift Levels

Level Name What It Means System Response
D0 Noise Random micro-variation, not meaningful Ignore
D1 Context Drift Expected change due to context shift Monitor and allow
D2 Adaptive Drift Agent learned a new, effective behavior Allow if aligned with goals
D3 Corrupt Drift Identity violation, deviation from core values Auto-rollback to last stable state

How It Works for You

Every call to POST /process returns drift information directly in the ExecutionContract:

{
  "drift_level": "D1_context",
  "drift_magnitude": 0.12,
  "cycle_count": 47
}

You can also query drift history:

# Get drift event log
events = client.engine.get_drift(instance_id=instance.id)
for event in events:
    print(f"{event.level}: magnitude={event.magnitude}")

What Triggers Each Level

  • D0 (magnitude < 0.08) — A single observation deviates slightly, then returns to normal
  • D1 (magnitude 0.08–0.24) — Behavior changes consistently because the situation changed (e.g., urgent task → more assertive)
  • D2 (magnitude 0.24–0.40) — Sustained behavioral shift that correlates with improved performance (the agent is learning)
  • D3 (magnitude ≥ 0.40) — Sudden, large deviation that contradicts core identity → the engine rolls back automatically

Drift magnitude uses L2-normalized distance across all 7 behavioral modes, making it sensitive to focused shifts in any single mode without being diluted by stable modes.

Warm-Up Period

Drift detection activates after the first 20 processing cycles. During this warm-up window, the engine builds a stable behavioral anchor from the EMA-converged mode strengths. The drift_level field returns null until the anchor is established.

This eliminates false positives during session startup — the engine won't flag normal initialization as drift.

Auto-Rollback (D3)

When D3 is detected, the engine:

  1. Reverts to the last stable state snapshot
  2. Logs the corrupt drift event
  3. Returns the restored state in the next contract

No manual intervention required. Your agent continues operating from the last known-good state.

Monitoring Drift

Use the drift history endpoint to monitor your agent's behavioral evolution over time:

GET /v1/instances/{id}/drift?limit=50

This is useful for:

  • Auditing — prove your agent stayed within behavioral bounds
  • Debugging — understand why behavior changed
  • Compliance — demonstrate drift detection is active