KYA scoring

Overview

KYA scoring is a continuous evaluation system that monitors agent behavior across multiple dimensions. Unlike static permission models, the KYA Score adapts in real time: agents that behave consistently and within expectations earn greater autonomy, while agents showing erratic or suspicious patterns face increasing restrictions.

The KYA Score is computed on every authorization and returned with the decision as kya_score, from 0.0 to 1.0, where higher means more trustworthy. Alongside it, each agent carries a trust zone that reflects its recent behavior and scales its limits.

How it works

Two signals describe an agent's standing. Both run from 0 to 1, higher is better, and both come back on every authorization response.

The KYA Score

A weighted composite: 35% trust level + 20% transaction history + 15% decline rate + 10% dispute deflection + 20% intent quality.

With any documented intent type, a brand-new REGISTERED agent scores between about 0.44 and 0.56, depending on how complete its intent_context is, so it clears the 0.40 step-up threshold from its first transaction. The exception is an empty task_reference: the intent component falls to 0.2, which puts a new agent at 0.395 and steps the transaction up. The score rises as the agent is promoted and builds a clean history.

The trust zone

After each authorization that carries an intent_context.session_id, Mandate Labs scores the session on four behavioral signals: context degradation, confirmation bias, hallucination risk, and probing of the agent's limits. The behavioral score is one minus the weighted risk, and it maps to a zone (below). Early in a session, while evidence is thin, the score is pulled toward 0.70, so a new session starts in GREEN. The zone takes effect on the agent's next authorization, not the current one.

The six anomaly detectors

Separately from both scores, every authorization passes the intent anomaly gate, which compares the stated intent with the agent's session baseline on six detectors. With platform defaults an anomaly score of 0.20 or more steps up and 0.70 or more declines. The gate starts scoring once there is a baseline: 3 earlier transactions in the same session when intent_context.session_id is sent, otherwise 5 earlier transactions for the agent. Until then intent_anomaly_skipped is true.

Trust Zones

The behavioral score maps to one of four zones, each with distinct implications:

Zone effects

Each zone applies a limit multiplier (the API field cognitive_limit_multiplier) to the agent's mandate constraints. This multiplier effectively reduces (or maintains) the maximum amount the agent can spend per transaction relative to its configured mandate.

Trust promotion eligibility

Agents can be promoted to higher trust tiers (verified, trusted) only while in the GREEN zone. Promotion requires sustained good behavior over a minimum number of successful transactions and time period. If an agent drops below GREEN, all promotion progress is frozen until the score recovers.

Reading the KYA Score from the API

There is no separate score endpoint: both signals travel with every decision.

curl https://api.mandatelabs.ai/api/v1/agents/agt_…/metrics \
  -H "X-API-Key: mdt_live_…"

import httpx

resp = httpx.get(
    "https://api.mandatelabs.ai/api/v1/agents/agt_…/metrics",
    headers={"X-API-Key": "mdt_live_…"},
)
metrics = resp.json()
print(metrics["trust_level"])               # "VERIFIED"
print(metrics["decline_rate"])              # 0.03
print(metrics["trust_promotion_eligible"])  # False
print(metrics["promotion_criteria"])        # what is still missing for TRUSTED

const resp = await fetch("https://api.mandatelabs.ai/api/v1/agents/agt_…/metrics", {
  headers: { "X-API-Key": "mdt_live_…" },
});
const metrics = await resp.json();
console.log(metrics.trust_level);               // "VERIFIED"
console.log(metrics.decline_rate);              // 0.03
console.log(metrics.trust_promotion_eligible);  // false
console.log(metrics.promotion_criteria);        // what is still missing for TRUSTED

Example response:

{
  "agent_id": "agt_…",
  "trust_level": "VERIFIED",
  "total_transactions": 214,
  "successful_transactions": 207,
  "declined_transactions": 7,
  "escalated_transactions": 0,
  "disputes_filed": 1,
  "disputes_deflected": 49,
  "decline_rate": 0.0327,
  "dispute_deflection_rate": 0.98,
  "trust_promotion_eligible": false,
  "next_trust_level": "TRUSTED",
  "promotion_criteria": {
    "successful_transactions": { "required": 500, "actual": 207, "met": false },
    "account_age_hours": { "required": 720, "actual": 1630.5, "met": true },
    "decline_rate": { "required": "<2%", "actual": "3.27%", "met": false },
    "dispute_deflection_rate": { "required": ">90%", "actual": "98.00%", "met": true }
  }
}

Zone reason codes

When the trust zone tightens an agent's limit, the decline names it:

Configuring thresholds

You can customize trust zone boundaries and multipliers for your organization using the thresholds endpoint. Changes take effect immediately for all subsequent authorization requests.

# Customize zone boundaries and multipliers
curl -X PUT https://api.mandatelabs.ai/api/v1/thresholds \
  -H "X-API-Key: mdt_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "cts_green_threshold": 0.80,
    "cts_amber_threshold": 0.55,
    "cts_red_threshold": 0.30,
    "cts_green_multiplier": 1.0,
    "cts_amber_multiplier": 0.6,
    "cts_red_multiplier": 0.3,
    "cts_critical_multiplier": 0.05
  }'

# View current resolved thresholds
curl https://api.mandatelabs.ai/api/v1/thresholds \
  -H "X-API-Key: mdt_live_…"

import httpx

# Customize zone boundaries and multipliers
resp = httpx.put(
    "https://api.mandatelabs.ai/api/v1/thresholds",
    headers={"X-API-Key": "mdt_live_…"},
    json={
        "cts_green_threshold": 0.80,      # Stricter GREEN entry (default 0.70)
        "cts_amber_threshold": 0.55,      # Adjust AMBER boundary
        "cts_red_threshold": 0.30,        # Adjust RED boundary
        "cts_green_multiplier": 1.0,      # Keep full limit in GREEN
        "cts_amber_multiplier": 0.6,      # Stricter AMBER reduction
        "cts_red_multiplier": 0.3,        # Stricter RED reduction
        "cts_critical_multiplier": 0.05,  # Nearly zero in CRITICAL
    },
)

# View current resolved thresholds
current = httpx.get(
    "https://api.mandatelabs.ai/api/v1/thresholds",
    headers={"X-API-Key": "mdt_live_…"},
).json()
print(current)

// Customize zone boundaries and multipliers
await fetch("https://api.mandatelabs.ai/api/v1/thresholds", {
  method: "PUT",
  headers: { "X-API-Key": "mdt_live_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    cts_green_threshold: 0.80,      // Stricter GREEN entry (default 0.70)
    cts_amber_threshold: 0.55,      // Adjust AMBER boundary
    cts_red_threshold: 0.30,        // Adjust RED boundary
    cts_green_multiplier: 1.0,      // Keep full limit in GREEN
    cts_amber_multiplier: 0.6,      // Stricter AMBER reduction
    cts_red_multiplier: 0.3,        // Stricter RED reduction
    cts_critical_multiplier: 0.05,  // Nearly zero in CRITICAL
  }),
});

// View current resolved thresholds
const current = await (await fetch("https://api.mandatelabs.ai/api/v1/thresholds", {
  headers: { "X-API-Key": "mdt_live_…" },
})).json();
console.log(current);

Next steps