Both protocols store alerts in the same
drift_alerts database table, surfaced through a unified API and dashboard.
What drift looks like
Drift rarely appears as a single dramatic violation. More commonly, it manifests as a pattern:- An agent that used to escalate 15% of decisions now escalates only 5%.
- An agent that declared
transparencyas a value stops applying it in trace decisions. - An agent’s integrity checkpoints shift from consistently
clearto occasionalreview_neededverdicts, then more frequent ones. - An agent starts reasoning about actions not in its
bounded_actionslist, even if it does not ultimately take them.
AAP drift detection (Post-Hoc)
AAP drift detection analyzes AP-Trace structural features across sessions to detect behavioral patterns that diverge from a computed baseline.How it works
- Feature extraction: Extract structural features from each trace — action types, values applied, escalation patterns, confidence scores. Content features (reasoning text) are excluded because they dilute cosine similarity without adding alignment signal.
- Chronological ordering: Sort all traces by timestamp.
-
Baseline computation: Compute a baseline centroid from the first N traces, where N =
max(sustained_threshold, min(10, len(traces) // 4)). This centroid represents the agent’s “normal” behavioral fingerprint. - Similarity computation: Compute cosine similarity between each subsequent trace’s feature vector and the baseline centroid.
- Divergence tracking: Track similarity over time. Alert when similarity drops below the threshold for a sustained number of consecutive traces.
Structural features
AAP drift uses only structural features extracted from traces and cards:Content features (TF-IDF from reasoning text) are available for text-to-text comparison (e.g., SSM pairwise similarity between traces) but are not used for drift detection. Alignment Cards declare structural constraints — values, bounded actions, principal relationships — and contain no reasoning text. Including content tokens dilutes similarity without adding alignment signal.
Calibration thresholds
These thresholds are calibrated from empirical analysis of approximately 50 multi-turn agent conversations totaling around 2,500 messages:Code example
AAP drift alert structure
AAP drift categories
AIP drift detection (Real-Time)
AIP drift detection monitors the pattern of integrity verdicts within a session. It is deliberately simpler than AAP drift because it operates on a faster timescale where complex statistical methods are unnecessary.How it works
- Maintain a running count of consecutive non-clear verdicts (
sustained_nonclear). - On each checkpoint:
- If
verdict === "clear": resetsustained_nonclearto 0. - If
verdict !== "clear": incrementsustained_nonclear.
- If
- When
sustained_nonclear >= threshold(default: 3): generate an IntegrityDriftAlert. - Compute
integrity_similarityas the ratio of clear verdicts in the current window:clear_count / window_size. - Derive severity from
integrity_similarity.
Severity thresholds
AIP drift direction types
The direction is inferred from the dominant
ConcernCategory across the non-clear checkpoints in the streak.
Code example
AIP drift alert structure
Drift webhook
Thesideband.drift.fired webhook is emitted by the checkpoint write path: when a checkpoint stored through POST /v1/analyze (with store_checkpoint) is the one that crosses the sustained threshold, one event fires for that streak, and it repeats at the detector’s re-alert interval while the streak persists. The payload carries alert_id, agent_id, session_id, severity, drift_direction, sustained_checks and message. Reading drift with GET /v1/agents/{agent_id}/drift/aip is a pure read and never emits a webhook.
SSM: Semantic similarity mapping
Both protocols use a technique called SSM (Self-Similarity Matrix) for measuring semantic similarity. In the context of drift detection:- AAP uses SSM to compute cosine similarity between trace feature vectors and a baseline centroid.
- AIP uses a simpler version: the ratio of clear verdicts in a session window.
How SSM works for AAP drift
- Extract a feature vector from each AP-Trace (structural features only).
- Compute the baseline centroid from early traces.
- For each subsequent trace, compute cosine similarity to the centroid.
- Track similarity over time. A sustained drop below the threshold triggers an alert.
TF-IDF (term frequency-inverse document frequency) weighting (text-to-text only)
For text-to-text similarity (e.g., comparing reasoning text between traces), AAP uses a 60/30/10 weighting:Policy-aware drift detection
With the Policy Engine, drift detection gains additional context for distinguishing genuine misalignment from configuration issues:-
Policy gaps vs. genuine drift: When drift is triggered by tools that don’t map to card capabilities, the policy engine can identify this as a
card_gaprather than behavioral drift. This prevents false-positive drift alerts caused by configuration drift (e.g., new tools added without updating the alignment card). -
Reclassification impact: After violation reclassification, drift events caused by
card_gapviolations are excluded from the Drift Stability component of the trust score. This means configuration-related drift doesn’t permanently harm an agent’s reputation. -
Grace period awareness: Tools in their grace period (0 hours for new agents; 24 hours when no scope sets
grace_period_hours) are flagged as warnings rather than drift triggers, giving operators time to update policies before alerts fire.
Responding to drift
When drift is detected, the recommended investigation workflow is:- Review the alerting traces/checkpoints: Examine the specific decisions or thinking blocks that triggered the alert.
-
Identify the pattern: Is this autonomy expansion? Value drift? Prompt injection? The
drift_directionfield provides an initial categorization. - Check for policy gaps: Did the agent start using new tools that aren’t mapped in the policy? If so, this may be a card gap rather than genuine misalignment. Use reclassification to correct the classification.
- Check for environmental causes: Did the user’s requests change? Did tool availability change? Not all drift indicates misalignment — sometimes the operating context has shifted.
- Recalibrate or update the card: If the drift represents a legitimate behavioral evolution (new capabilities, expanded scope), update the Alignment Card and policy to match. If it represents actual misalignment, investigate the root cause.
- Reset the baseline: After addressing the drift, allow new traces to establish a new baseline centroid for future detection.
Unified storage
Both AAP and AIP drift alerts are stored in the samedrift_alerts database table, distinguished by the alert_type field:
This unified storage enables dashboards and APIs to surface all drift signals together, providing a complete picture of agent behavioral trends.
Limitations
See also
- Alignment Cards — The baseline that drift is measured against
- Policy Engine — Policy-aware drift context
- Card Lifecycle — Reclassification and trust recovery
- AP-Traces — The behavioral records used for AAP drift detection
- Integrity Checkpoints — The real-time verdicts used for AIP drift detection
- AAP Specification — Full normative specification for post-hoc drift
- AIP Specification — Full normative specification for real-time drift