ML Insights

MITRITY uses machine learning to provide continuous, automated analysis of agent behavior. The ML insights system goes beyond rule-based policies to detect subtle behavioral anomalies, quantify risk, and visualize the relationships between agents, tools, and resources. This gives you a data-driven understanding of your AI agent governance posture that evolves with your agents.

Overview

The ML insights system provides five capabilities:

1. Drift scoring — Measures how much an agent's behavior deviates from its established baseline
2. Risk scoring — Ranks agents by their average drift score, with a trend
3. Anomaly detection — Identifies unusual behavioral patterns that may indicate compromise or misconfiguration
4. Topology — Maps each agent to the tools, credentials and policy it uses and to the agents it delegates to
5. 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

Drift score quantifies how much an agent's recent behavior deviates from its behavioral baseline — the pattern of actions, tool usage, timing, and resource access that the agent typically exhibits. A drift score of 0.0 means the agent is behaving exactly as expected. A score of 1.0 means the agent's behavior is completely different from its baseline.

How the Baseline is Built

The baseline is built from the agent's first 7 days of observed behavior (configurable). During this learning period, the ML model observes:

• Action type distribution (which actions the agent performs and how often)
• Tool usage patterns (which tools are used in which combinations)
• Temporal patterns (when the agent is active, daily/weekly cycles)
• Resource access patterns (which resources are accessed and at what rate)
• Payload size distribution (typical request and response sizes)
• Delegation patterns (which agents are delegated to and how often)

After the learning period, the model continuously compares current behavior against the baseline and generates a drift score.

Interpreting Drift Scores

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 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 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, and 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: increasing or decreasing when the average moved by more than 10%, otherwise stable.

Risk Score Tiers

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, and agents_monitored counts the agents with audit events.

Anomaly Detection

Overview

The anomaly detection system uses unsupervised ML models to identify behavioral patterns that fall outside normal distributions. Unlike drift scoring (which compares against a per-agent baseline), anomaly detection identifies patterns that are unusual across all agents in your tenant.

Anomaly Types

Anomalies via API

The API reports anomalies as counts, where 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), and 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: Visually identify agents with unexpectedly broad tool access
• Impact analysis: Before removing 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 the existing agent ecosystem before adding new agents

Models

MITRITY uses a two-tier model system for behavioral analysis:

Tier 1: Local (Gateway / Sidecar)

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

The DriftGuard model is updated via the heartbeat channel and can be hot-swapped without downtime.

Tier 2: Control Plane (Centralized)

Models that run on the MITRITY control plane for deeper, cross-agent analysis:

Model Updates

• DriftGuard (local): Updated via heartbeat channel. Hot-swap with zero downtime. Update frequency: weekly or as needed.
• Control Plane models: Updated via control plane deployment. No impact on gateway operation during updates.
• Training data: Models are trained on anonymized, aggregated data across the platform. No tenant-specific data is used for training shared models.

Model Preferences

Pro and Enterprise tenants can enable or disable individual control plane models from Settings > Anomaly Detection. This allows you to tailor which ML analyses run for your organization.

Available models by plan:

Key details:

• DriftGuard is always active on the gateway/sidecar and controlled via intent policies — it cannot be toggled from Settings.
• Disabling a model stops its analysis for your tenant only. Other tenants are not affected.
• Changes take effect immediately.
• In Settings > Anomaly Detection, Owner and Manager roles toggle models, and 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

The Narrator module generates human-readable explanations for ML-driven insights. Instead of opaque scores, you get natural language explanations of why a risk score is elevated, what is driving drift, or why an anomaly was detected.

Explanation Examples

Risk score explanation:

"The data-bot agent has a high risk score (0.67) primarily because of elevated DLP events (0.80 factor) — 8 sensitive data exfiltration attempts were detected in the past 7 days, 5 of which involved PII-tagged fields. Additionally, the agent's permission breadth (0.70) is in the top 10% of all agents, with access to 12 tools across 4 categories."

Drift explanation:

"The sales-bot agent's drift score increased from 0.12 to 0.23 over the past 2 weeks. The primary driver is a temporal pattern shift — the agent is now starting operations 2 hours later than its baseline (10:00 vs 08:00). A secondary driver is increased write operations to the CRM (28% of actions vs 12% baseline), which may indicate expanded scope."

Anomaly explanation:

"A sequence anomaly was detected for data-bot: a repeated read-delete cycle (47 iterations in 10 minutes) on the public.temp_exports table. This pattern has no precedent in the agent's history or any other agent in the tenant. The repetitive nature suggests either a bug (infinite loop) or intentional data destruction."

Explanations are generated using SHAP (SHapley Additive exPlanations) values from the ML models, then translated into natural language narratives.

Best Practices

Establish Baselines Before Enforcing

Allow the ML model at least 7 days to establish a behavioral baseline before configuring drift-based enforcement. Enforcing on an incomplete baseline generates false positives.

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

Investigate the drift components to understand the cause before taking action.

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 are a tool for humans, not a replacement. 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 provide powerful compliance evidence. Include trend data in your compliance reports to demonstrate 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