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 — Assigns a per-agent risk score based on multiple factors
3. Anomaly detection — Identifies unusual behavioral patterns that may indicate compromise or misconfiguration
4. Behavioral topology — Maps the live relationships between agents, tools, and resources
5. Trend analysis — Tracks how drift, risk, and anomaly metrics change over time

All ML insights are accessible via the dashboard at Compliance > ML Insights and via the REST API.

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

Score Range	Classification	Typical Cause
0.0 - 0.15	Normal	Agent operating within expected patterns
0.15 - 0.35	Low drift	Minor variations — new feature rollout, seasonal changes, configuration update
0.35 - 0.60	Moderate drift	Significant behavioral change — new tool integration, expanded scope, or potential issue
0.60 - 0.80	High drift	Major deviation — likely indicates compromise, misconfiguration, or unauthorized scope expansion
0.80 - 1.0	Critical drift	Agent behavior is completely different from baseline — investigate immediately

Drift Score Alerts

Configure drift score thresholds in Settings > ML > Drift Alerts:

{
  "drift_alerts": {
    "enabled": true,
    "alert_threshold": 0.35,
    "hold_threshold": 0.60,
    "deny_threshold": 0.80,
    "notification_channels": ["slack", "email"]
  }
}

When an agent's drift score exceeds a threshold, the configured action is applied to all subsequent actions from that agent until the drift score drops below the threshold or a human reviews and acknowledges the drift.

Drift Score via API

curl "https://api.mitrity.com/api/v1/ml/drift?agent_id=agt_sales-bot" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": {
    "agent_id": "agt_sales-bot",
    "agent_name": "sales-bot",
    "current_drift_score": 0.23,
    "baseline_established": true,
    "baseline_period": {
      "start": "2026-02-01T00:00:00Z",
      "end": "2026-02-08T00:00:00Z",
      "events_in_baseline": 12450
    },
    "drift_components": {
      "action_distribution": 0.18,
      "tool_usage": 0.12,
      "temporal_pattern": 0.31,
      "resource_access": 0.22,
      "payload_size": 0.08,
      "delegation_pattern": 0.15
    },
    "trend": "stable",
    "last_updated": "2026-03-01T14:00:00Z"
  },
  "meta": {
    "request_id": "req_drift001",
    "timestamp": "2026-03-01T14:00:00Z"
  }
}

The drift_components breakdown shows which aspects of behavior are contributing most to the drift score. In this example, the temporal pattern component (0.31) is the highest contributor — the agent may be operating at different hours than usual.

Risk Scoring

Per-Agent Risk Assessment

The risk score is a composite metric that combines multiple factors into a single 0.0-1.0 assessment of the agent's overall risk level.

Risk Factors

Factor	Weight	Description
Drift score	25%	Current behavioral drift from baseline
Permission breadth	15%	Number of tools and operations the agent has access to
Credential access	15%	Number and sensitivity of credentials the agent can access
DLP events	15%	Recent DLP events involving this agent
Injection events	10%	Recent injection detection events targeting this agent
Delegation depth	10%	Maximum delegation chain depth initiated by this agent
Policy violations	10%	Recent policy deny/alert events for this agent

Risk Score Tiers

Score Range	Tier	Action
0.0 - 0.25	Low	Standard monitoring
0.25 - 0.50	Medium	Enhanced monitoring, review permissions quarterly
0.50 - 0.75	High	Weekly review, consider restricting permissions
0.75 - 1.0	Critical	Immediate review, consider disabling the agent

Risk Scores via API

curl "https://api.mitrity.com/api/v1/ml/risk?environment_id=env_production" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "agent_id": "agt_sales-bot",
      "agent_name": "sales-bot",
      "risk_score": 0.32,
      "risk_tier": "medium",
      "factors": {
        "drift_score": 0.23,
        "permission_breadth": 0.45,
        "credential_access": 0.30,
        "dlp_events": 0.10,
        "injection_events": 0.05,
        "delegation_depth": 0.20,
        "policy_violations": 0.15
      },
      "trend": "increasing",
      "trend_delta": 0.04,
      "last_updated": "2026-03-01T14:00:00Z"
    },
    {
      "agent_id": "agt_data-bot",
      "agent_name": "data-bot",
      "risk_score": 0.67,
      "risk_tier": "high",
      "factors": {
        "drift_score": 0.58,
        "permission_breadth": 0.70,
        "credential_access": 0.65,
        "dlp_events": 0.80,
        "injection_events": 0.20,
        "delegation_depth": 0.10,
        "policy_violations": 0.45
      },
      "trend": "stable",
      "trend_delta": 0.01,
      "last_updated": "2026-03-01T14:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_risk001",
    "timestamp": "2026-03-01T14:00:00Z",
    "total": 2
  }
}

Risk Trends

curl "https://api.mitrity.com/api/v1/ml/risk/trends?agent_id=agt_sales-bot&days=30&granularity=daily" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": {
    "agent_id": "agt_sales-bot",
    "agent_name": "sales-bot",
    "granularity": "daily",
    "data_points": [
      { "date": "2026-02-01", "risk_score": 0.18, "drift_score": 0.12 },
      { "date": "2026-02-02", "risk_score": 0.19, "drift_score": 0.14 },
      { "date": "2026-02-03", "risk_score": 0.22, "drift_score": 0.18 },
      { "date": "2026-02-28", "risk_score": 0.31, "drift_score": 0.22 },
      { "date": "2026-03-01", "risk_score": 0.32, "drift_score": 0.23 }
    ]
  },
  "meta": {
    "request_id": "req_risk002",
    "timestamp": "2026-03-01T14:05:00Z"
  }
}

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

Type	Description
temporal_anomaly	Agent active at unusual times (e.g., 3 AM on a Saturday when the agent normally operates weekdays)
volume_anomaly	Unusually high or low action volume compared to the global distribution
sequence_anomaly	Unusual sequence of actions (e.g., repeated read-delete-read cycles)
resource_anomaly	Access to resources not typically accessed by any agent in the tenant
velocity_anomaly	Actions performed at an unusual rate (much faster or slower than normal)
payload_anomaly	Unusual payload sizes or structures compared to historical patterns

Anomaly Detection via API

curl "https://api.mitrity.com/api/v1/ml/anomalies?days=7&min_confidence=0.7" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "anom_8k2m",
      "type": "sequence_anomaly",
      "confidence": 0.89,
      "agent_id": "agt_data-bot",
      "agent_name": "data-bot",
      "description": "Repeated read-delete-read-delete cycle on the same resource, 47 iterations in 10 minutes. This pattern has not been observed before.",
      "details": {
        "action_sequence": ["db.read", "db.delete", "db.read", "db.delete"],
        "resource": "public.temp_exports",
        "iterations": 47,
        "duration_seconds": 600
      },
      "related_events": ["evt_abc123", "evt_def456"],
      "detected_at": "2026-03-01T03:15:00Z"
    },
    {
      "id": "anom_9j3n",
      "type": "temporal_anomaly",
      "confidence": 0.76,
      "agent_id": "agt_sales-bot",
      "agent_name": "sales-bot",
      "description": "Agent active at 02:30 UTC on Saturday. This agent has no recorded activity on weekends in the past 30 days.",
      "details": {
        "observed_time": "2026-03-01T02:30:00Z",
        "expected_active_hours": "08:00-18:00 Mon-Fri (Europe/Stockholm)",
        "weekend_activity_last_30d": 0
      },
      "related_events": ["evt_ghi789"],
      "detected_at": "2026-03-01T02:35:00Z"
    }
  ],
  "meta": {
    "request_id": "req_anom001",
    "timestamp": "2026-03-01T14:00:00Z",
    "next_cursor": null,
    "total": 2
  }
}

Anomaly Filters

Parameter	Type	Description
type	enum	Filter by anomaly type
agent_id	string	Filter by agent
min_confidence	float	Minimum confidence score (0.0-1.0)
days	integer	Look back period in days (default: 7, max: 90)
limit	integer	Results per page (default: 25, max: 100)

Dashboard Topology

Live Agent-Tool-Resource Graph

The dashboard topology at Compliance > ML Insights > Topology provides a live, interactive graph of all relationships between agents, tools, and resources in your tenant.

Graph elements:

• Agent nodes: Colored by risk score (green = low, yellow = medium, red = high)
• Tool nodes: Colored by category
• Resource nodes: Sized by access frequency
• Edges: Weighted by interaction frequency, colored by decision type (green = allow, red = deny, yellow = alert)

Interactive features:

• Click on any node to see details (permissions, recent events, risk factors)
• Filter by environment, agent, tool category, or time range
• Highlight specific delegation chains
• Toggle between live view (last 1 hour) and historical view (selectable time range)

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 the path of a suspicious action through agents, tools, and resources
• 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:

Model	Purpose	Inference Time	Size
DriftGuard	Action sequence classification, injection detection	<0.5ms	~2MB

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	Purpose	Plan
DeepTrace (LSTM)	Extended action sequence analysis, cross-agent behavioral pattern recognition	Pro, Enterprise
TrustGraph (GNN)	Agent-tool-resource relationship analysis, delegation chain topology	Enterprise
ColdStart (VAE)	Anomaly detection via reconstruction error	Pro, Enterprise
Narrator (XAI)	Human-readable explanations of risk scores and anomalies	Pro, Enterprise

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:

Model	Pro	Enterprise
DeepTrace (LSTM)	Yes	Yes
CrossAgent (Transformer)	Yes	Yes
ColdStart (VAE)	Yes	Yes
TrustGraph (GNN)	—	Yes

Key details:

• DriftGuard (TCN) 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.
• Owner and Manager roles can toggle models. Member and Viewer roles can view the current state but cannot make changes.

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

Drift Analysis via API

Get a detailed drift analysis for an agent:

curl "https://api.mitrity.com/api/v1/ml/drift/analysis?agent_id=agt_sales-bot&days=30" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": {
    "agent_id": "agt_sales-bot",
    "agent_name": "sales-bot",
    "analysis_period": {
      "start": "2026-02-01T00:00:00Z",
      "end": "2026-03-01T00:00:00Z"
    },
    "current_drift_score": 0.23,
    "drift_trend": [
      { "date": "2026-02-01", "score": 0.08 },
      { "date": "2026-02-08", "score": 0.12 },
      { "date": "2026-02-15", "score": 0.15 },
      { "date": "2026-02-22", "score": 0.20 },
      { "date": "2026-03-01", "score": 0.23 }
    ],
    "top_contributors": [
      {
        "component": "temporal_pattern",
        "contribution": 0.31,
        "explanation": "Agent is now active 2 hours later than baseline (10:00 vs 08:00 start)"
      },
      {
        "component": "resource_access",
        "contribution": 0.22,
        "explanation": "Agent is accessing 3 new database tables not in the baseline: public.exports, public.temp_data, public.staging"
      },
      {
        "component": "action_distribution",
        "contribution": 0.18,
        "explanation": "write_crm_* actions increased from 12% to 28% of total actions"
      }
    ],
    "recommendations": [
      "Review the 3 new database tables being accessed — confirm they are within the agent's mission scope",
      "The temporal shift may be due to a timezone configuration change — verify agent deployment settings"
    ]
  },
  "meta": {
    "request_id": "req_drift002",
    "timestamp": "2026-03-01T14:10:00Z"
  }
}

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