ML Insights

ML insights show you how your agents behave, beyond what your rules check. MITRITY uses machine learning to analyze agent behavior continuously and automatically. It detects subtle behavioral anomalies, quantifies risk, and shows the relationships between agents, tools and resources.

Use ML insights to understand your AI agent governance posture from data, as your agents change.

Overview

ML insights provide five capabilities:

• Drift scoring: a score from 0 to 1 on each audit event that says how unusual the action looked.
• Risk scoring: ranks agents by their average drift score, with a trend.
• Anomaly detection: identifies unusual behavioral patterns that may indicate compromise or misconfiguration.
• Topology: maps each agent to the tools, credentials and policy it uses, and to the agents it delegates to.
• Trend analysis: tracks how drift, risk and anomaly metrics change over time.

The Insights page in the dashboard and the /api/v1/insights endpoints report them.

Drift Scoring

What Drift Measures

The drift score is a number from 0 to 1 on each audit event. It says how unusual the action looked, and where it comes from depends on the kind of agent:

• Runtime agents: the edge computes it with DriftGuard, its local ML model, when the edge runs with ml.enabled (off by default) and a model loaded. DriftGuard returns an anomaly score over a sliding window of the most recent actions.
• SaaS-embedded agents: the connector sets it with a fixed heuristic, from whether the event type is new for the agent and whether the agent's events come in a burst.

A score of 0 also means that no score was computed: ML is off, or the window is not full yet. Core Concepts gives the exact inputs and values.

How the Drift Score is Computed

There is no per-agent learning period. DriftGuard is one model, trained by MITRITY and sent to the edge. It scores each action against the window of recent actions the edge has seen, and that window holds ml.buffer_size actions (256 by default). Until the window is full, the drift score is 0. The connector heuristic compares an event with the event types the agent showed in the last 30 days.

Interpreting Drift Scores

These are the bands the Audit Log's Drift column shows: green up to 0.4, amber above 0.4 and red above 0.7. Connector scores fall in two of them: 0.20 is within normal range, and 0.72, 0.75 and 0.90 are significant.

Acting on Drift: DriftGuard

DriftGuard is set on the policy an agent runs. When an action's drift score is above the policy's drift_guard_threshold, drift_guard_mode decides what happens:

curl -X PUT https://api.mitrity.com/api/v1/policies/{policy_id} \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"drift_guard_mode": "enforce", "drift_guard_threshold": 0.8}'

An action that DriftGuard blocks appears in the audit log with blocked_by set to drift_guard. The policy's override_mode still applies: under log_only, a DriftGuard block is recorded and the action is allowed.

Drift Trends via API

curl "https://api.mitrity.com/api/v1/insights/drift-trends?days=30" \
  -H "Authorization: Bearer mk_your-api-key"

days is the look-back window (default 14, max 90). The response has one entry per day with governed activity, across all of your agents:

[
  { "date": "2026-02-28", "avg_score": 0.14, "max_score": 0.62, "event_count": 1840 },
  { "date": "2026-03-01", "avg_score": 0.17, "max_score": 0.71, "event_count": 2105 }
]

avg_score and max_score are the day's average and highest drift score across audit events. event_count is the number of events that day.

Risk Scoring

Per-Agent Risk Assessment

An agent's risk score is the average drift score across its audit events, from 0.0 to 1.0. Its trend compares the average of the last 7 days with the 7 days before. The trend is increasing or decreasing when the average moved by more than 10%, and stable otherwise.

Risk Score Tiers

The Insights page colors each agent's risk score with these bands. The actions are recommendations.

Risk Scores via API

curl "https://api.mitrity.com/api/v1/insights/agent-risks?limit=10" \
  -H "Authorization: Bearer mk_your-api-key"

limit is the number of agents to return (default 10, max 50), highest risk score first:

[
  {
    "agent_id": "agt_data-bot",
    "agent_name": "data-bot",
    "risk_score": 0.67,
    "anomaly_count": 12,
    "last_anomaly_at": "2026-03-01T03:15:00Z",
    "trend": "stable"
  },
  {
    "agent_id": "agt_sales-bot",
    "agent_name": "sales-bot",
    "risk_score": 0.32,
    "anomaly_count": 3,
    "last_anomaly_at": "2026-02-27T16:40:00Z",
    "trend": "increasing"
  }
]

anomaly_count and last_anomaly_at cover the agent's audit events with a drift score above 0.5. last_anomaly_at is null when there are none.

Summary via API

curl https://api.mitrity.com/api/v1/insights/summary \
  -H "Authorization: Bearer mk_your-api-key"

{
  "total_anomalies": 47,
  "avg_drift_score": 0.18,
  "active_models": 4,
  "agents_monitored": 23
}

• total_anomalies counts audit events with a drift score above 0.5.
• avg_drift_score averages the drift score of every audit event.
• active_models counts the active ML models available to your tenant.
• agents_monitored counts the agents with audit events.

Anomaly Detection

Overview

Anomaly detection uses unsupervised ML models to identify behavioral patterns that fall outside normal distributions. The drift score rates each action as it happens. Anomaly detection instead identifies patterns that are unusual across all agents in your tenant.

Anomaly Types

Anomalies via API

The API reports anomalies as counts. An anomaly is an audit event with a drift score above 0.5.

• GET /api/v1/insights/summary returns the tenant's total (total_anomalies).
• GET /api/v1/insights/agent-risks returns each agent's anomaly_count and last_anomaly_at.

The events themselves are in the audit log, each with its drift_score.

Dashboard Topology

Live Topology

The dashboard home shows a live, interactive graph of your agents and what they are connected to:

• Agents (AGENT in the legend): every agent in the current environment.
• Tools (SERVICE): linked to the agents permitted to use them.
• Credentials (KEY): linked to the agents granted them.
• Policies (POLICY): linked to the agents that run them.
• Delegations between agents: solid for a pair that delegated in the last 24 hours, dashed for a pair that is allowed to delegate but has not recently.

Hover over a node for its details, or search for one by name.

Use Cases for Topology

• Permission review: spot agents with unexpectedly broad tool access.
• Impact analysis: before you remove a tool or credential, see which agents depend on it.
• Incident investigation: trace a suspicious action through the agents, the tools they use and the delegations between them.
• Onboarding: understand your existing agents before you add new ones.

Models

MITRITY analyzes behavior with models in two tiers.

Tier 1: Local (Gateway / Sidecar)

These models run locally on the gateway or sidecar, for real-time, low-latency analysis:

The DriftGuard model is small enough to run at the edge. It is updated through the heartbeat channel, and can be hot-swapped without downtime.

Tier 2: Control Plane (Centralized)

These models run on the MITRITY control plane, for deeper, cross-agent analysis:

On the pricing page, DeepTrace names the control-plane ML as a whole. In this table and in Settings > Anomaly Detection, it is the per-agent sequence model.

Model Updates

• DriftGuard (local): when the edge runs with ml.enabled, updated through the heartbeat channel and hot-swapped with zero downtime.
• Control Plane models: updated through control plane deployments. Updates have no impact on gateway operation.
• Training data: models are trained on anonymized, aggregated data across the platform. No tenant-specific data is used to train shared models.

Model Preferences

Pro and Enterprise tenants can enable or disable individual control plane models in Settings > Anomaly Detection. You choose which ML analyses run for your organization.

Available models by plan:

Good to know:

• DriftGuard runs on the gateway or sidecar only when it runs with ml.enabled and a model loaded. What a drift score does is set per policy (DriftGuard: Off, Log or Enforce). It cannot be toggled in Settings.
• Narrator is not a model you toggle either, so it is not in the table above.
• Disabling a model stops its analysis for your tenant only. Other tenants are not affected.
• Changes take effect immediately.
• In Settings > Anomaly Detection, the Owner and Manager roles toggle models, and the Member and Viewer roles see the current state. Through the API, the Member role can toggle a model too.

Starter plan tenants do not have access to control plane model preferences. Upgrade to Pro to enable per-model configuration.

Explainable AI

Narrator explains an event in your audit log in plain language: what happened, what was decided and why. In the Audit Log, expand an event to see its investigation narrative and the factors behind it. It is available on every plan, to anyone who can read the event.

The narrative is built from a template, not written by a model. It reads the event as recorded:

• when it happened, which agent acted, what it tried to do, and which policy evaluated it;
• what was decided (allowed, alerted, held, blocked or timed out) and what that means, including the reason a delegation was blocked when the gateway recorded one;
• the event's drift score, as a percentage, with a band: low below 40%, moderate from 40% and high from 70%;
• the enforcement mode the policy was in.

Beside the narrative, the panel lists the factors behind the decision, each with a fixed weight:

The weights are set by rules, not learned from data, so they show what the narrative took into account rather than a statistical attribution. The panel names the template it used, template-v1.

Explanation Examples

A blocked action reads like this:

On March 1, 2026 at 03:15 UTC, agent data-bot attempted to perform db_mutate: public.temp_exports (event type: agent_action). This action was evaluated against the production-data policy.

The governance engine blocked this action because it violated the configured policy rules. The agent was prevented from executing the requested operation, and the event was flagged for review.

Behavioral analysis detected a drift score of 72%, indicating high deviation from the agent's baseline behavior. This score reflects how far the current action diverges from the agent's historical activity patterns.

The policy was operating in enforce mode at the time of this event.

Its factors are drift_score 0.72, decision_severity 1.0, event_type 0.3 and policy_match 0.4.

Best Practices

Run DriftGuard on Log Before Enforcing

Run DriftGuard on Log before you switch it to Enforce. The edge's drift score stays 0 until its window of recent actions is full (256 actions by default), so watch how the scores look for your agents before you let DriftGuard block.

Investigate High Drift Before Reacting

A high drift score does not necessarily indicate a security issue. Common benign causes include:

• New feature deployments that change the agent's action distribution
• Timezone or schedule changes
• Infrastructure migrations (new resource URLs)
• Seasonal business patterns

Look at the agent's recent actions in the audit log to understand the cause before you act.

Use Risk Scores for Prioritization

With many agents, risk scores help you focus attention on the agents that need it most. Sort by risk score and review high-risk agents first.

Review the Topology Regularly

The agent-tool-resource topology provides a comprehensive view of your governance surface. Review it monthly to identify unexpected relationships, unused permissions, and potential attack paths.

Combine ML Insights with Manual Review

ML insights support the people who make decisions; they do not replace them. Use drift scores, risk assessments and anomaly detection to guide your investigations, but always apply human judgment to the final decision.

Leverage Trend Data for Compliance

Risk and drift trends over time are strong compliance evidence. Include trend data in your compliance reports to show continuous monitoring and improvement.

Related Documentation

• Compliance Reports: generate compliance reports with ML insights data
• Injection Detection: ML-driven injection detection
• Delegation Chains: delegation pattern analysis
• Threat Intelligence: threat feed with ML-generated indicators
• Gateway & Sidecar Deployment: DriftGuard model architecture