Home / Core concepts

Risk engine

Thirteen named signals, weighted into an explainable score that policy can test — with no model you cannot interrogate.

Risk runs as stage 8 of the pipeline, before approval, because a policy rule can test the risk score and the signals that produced it. The output is a level, a score from 0 to 100, and the list of signals that fired with their individual contributions.

#The signals

Several of these are baseline signals — they compare against what this agent has done before, not against a global average. A finance agent that moves large amounts all day has a high baseline and does not trip UNUSUAL_AMOUNT; a read-only agent that suddenly moves one does.

That also means a brand-new agent trips the "new" signals on almost everything it does. That is correct behaviour and worth planning for: run new agents in OBSERVE or SIMULATE long enough to establish a baseline before promoting.

#What a risk assessment returns

jsonCopy
{
  "level": "HIGH",
  "score": 72,
  "signals": [
    {
      "type": "UNUSUAL_AMOUNT",
      "weight": 30,
      "explanation": "Amount 120000 is 4.2× this agent's trailing median of 28500."
    },
    {
      "type": "UNUSUAL_DESTINATION",
      "weight": 22,
      "explanation": "payments-eu.partner.example.com has not been contacted by this agent before."
    },
    {
      "type": "TIME_ANOMALY",
      "weight": 20,
      "explanation": "03:14 UTC is outside this agent's usual 08:00–19:00 activity."
    }
  ]
}

On a decision, explanation.risk.top_signals carries the three highest-weighted explanations, so the reason a request was escalated is in the response the agent already received.

#Using risk in policy

This is the point of computing it.

jsonCopy
{
  "id": "rule-high-risk-approval",
  "name": "High risk needs a human",
  "priority": 600,
  "enabled": true,
  "when": {
    "kind": "condition",
    "id": "c-risk-score",
    "field": "risk.score",
    "operator": "gte",
    "value": 70
  },
  "then": {
    "decision": "REQUIRE_APPROVAL",
    "reason": "Risk score is at or above the review threshold.",
    "approval": { "routingMode": "SINGLE", "requiredApprovals": 1, "ttlSeconds": 900 }
  }
}

Testing a specific signal is often better than testing the score, because it says what you actually mean:

jsonCopy
{
  "id": "rule-new-destination-large-amount",
  "name": "Block large amounts to unseen destinations",
  "priority": 820,
  "enabled": true,
  "when": {
    "kind": "group",
    "id": "g-new-dest-large",
    "operator": "and",
    "children": [
      {
        "kind": "condition",
        "id": "c-signal-new-dest",
        "field": "risk.signals",
        "operator": "contains",
        "value": "UNUSUAL_DESTINATION"
      },
      { "kind": "condition", "id": "c-large", "field": "amount", "operator": "gt", "value": 50000 }
    ]
  },
  "then": {
    "decision": "BLOCK",
    "reason": "Large amounts to a destination this agent has never used are refused."
  }
}

Three fields are available: risk.level, risk.score and risk.signals. The velocity and history counters the signals are built from are exposed separately too — velocity.actions_last_minute, history.tool_used_before and the rest — so you can write a rule on the raw observation rather than on the derived signal when that is clearer.

#Tuning

httpCopy
PUT /v1/risk/configuration

Signal weights and level thresholds are yours. Tuning is an audited change requiring risk:configure.

Approach it from the evidence rather than from intuition:

1. Run in OBSERVE or SIMULATE and let real traffic accumulate.
2. Open the Risk Center and look at the score distribution and the signal breakdown.
3. A signal firing on nearly everything is not discriminating — lower its weight or fix the underlying baseline.
4. A signal that never fires is either weighted too low or genuinely not relevant to your traffic.
5. Set thresholds where the distribution has a natural gap.

#Risk events

Every assessment that crosses a threshold writes a risk event with its signal evidence attached.

httpCopy
GET /v1/risk/events
GET /v1/risk/overview

The overview is what the Risk Center renders: counts by level, the signal breakdown, the highest-risk tools, the destinations in play, policy violations and credential anomalies. Events can be acknowledged with risk:acknowledge, so "we have looked at this" is recorded rather than remembered.

#Related