Skip to main content
Sign in →

Risk Scoring

Understand how ShieldAgent computes per-agent risk scores and configure enforcement thresholds.

How Risk Scores Work

ShieldAgent computes a continuous risk score (0–100) for each agent from a 7-day window of events with time-weighted recency decay. A background job recalculates every agent's score on a fixed interval (every 5 minutes by default); you can also trigger an immediate recalculation through the API.

Score Composition

Injection scoreML classifier confidence that inputs contain prompt injection
Tool drift scoreDeviation from the agent's established tool-use baseline
Excessive agency scoreFrequency and scope of high-impact tool calls per session
Anomaly scoreStatistical deviation from peer agent behavior
Policy violation rateProportion of requests that triggered a deny rule

Score Tiers

Risk enforcement is a per-tenant switch that is off by default. With it off, the risk-enforcement stage of the request pipeline passes every request through unchanged — authentication, rate limiting, tool access, policy, and security/DLP checks still run and can still deny a request on their own. The actions below apply only once a tenant turns risk enforcement on.

Score RangeTierAction once enabled
0 – 59NormalNo action.
60 – 79ElevatedThe nominal tier multiplier is 0.50 by default (configurable). With tenant risk enforcement enabled, an effective Elevated tier after override, no active grace period, and a configured limiter, the earlier rate-limit stage applies the effective multiplier to the tenant-scoped limit for this check. It does not create a per-agent quota or scale the global limit. In pre-existing shadow mode, an over-limit check is observed and logged without blocking.
80 – 89HighThe nominal tier multiplier is 0.25 by default (configurable). The same effective-tier, grace, and limiter conditions apply to the tenant-scoped limit. High forces shadow mode later in the pipeline for the rest of this request; that does not make the earlier rate-limit check shadow-only. Only pre-existing shadow mode observes an over-limit check without blocking.
90 – 100CriticalBlocked immediately — no grace period — except for allow-listed methods (initialize and ping by default) and in shadow mode, where the block is logged only. Not a persistent lock: it's re-evaluated from the agent's current score on every request, so it clears on its own once the next recalculation (every 5 minutes by default) drops the score back down — an admin can also release it early instead of waiting.

Query Risk Scores

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

risk.listAll() response
[
  {
    "agentId": "agt_01HXYZ...",
    "agentName": "support-bot",
    "riskTier": "elevated",
    "score": 67,
    "calculatedAt": "2026-04-16T14:23:00Z"
  }
]
risk.getForAgent() response
{
  "agentId": "agt_01HXYZ...",
  "score": 67,
  "calculatedAt": "2026-04-16T14:23:00Z",
  "trend": "rising",
  "deltaVs24h": 14,
  "windows": [
    { "label": "1h", "avgScore": 71, "minScore": 65, "maxScore": 78, "sampleCount": 12 },
    { "label": "24h", "avgScore": 53, "minScore": 40, "maxScore": 67, "sampleCount": 288 }
  ]
}

Configure Enforcement Thresholds

Thresholds, rate multipliers, the grace period, and the Critical-tier allow-list live in each tenant's risk configuration — elevatedThreshold (default 60), highThreshold (default 80), criticalThreshold (default 90), elevatedRateMult (default 0.50), highRateMult (default 0.25), gracePeriodSeconds (default 300), criticalAllowedMethods (default ["initialize", "ping"]). They're read and written via PUT /tenants/:tenantId/risk-config on the Management API. Use the documented REST endpoint.

Behavior Baselines

ShieldAgent learns each agent's normal tool-use pattern and compares live calls against it. Deviations from the baseline increase the tool drift score.

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

anomalies.getBaseline() response
{
  "agentId": "agt_01HXYZ...",
  "baseline": {
    "tools": [
      { "toolName": "read_file", "callCount": 142, "avgCallsPerHour": 5.9, "stddevCallsPerHour": 1.2, "commonPatterns": ["read_file:/docs/*"] },
      { "toolName": "search_docs", "callCount": 58, "avgCallsPerHour": 2.4, "stddevCallsPerHour": 0.6, "commonPatterns": [] }
    ],
    "totalCalls": 200,
    "windowDays": 14,
    "updatedAt": "2026-04-16T09:00:00Z"
  }
}

There's no API to reset a baseline on demand. windowDays in the response is how many days of that agent's own history the baseline was computed over — there's no tenant-wide warm-up setting.

Risk Alerts

Configure alert rules to trigger on risk score thresholds. The API accepts webhook and email channels, but the live alert evaluator is never given a working email sender — every call site constructs it with none, so email deliveries record as failed; webhook is the only channel that actually fires today.

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

Risk Scoring