Decision Trust Scoring
Naming note: the score described here is surfaced to customers as the KYA Score. See the glossary for canonical terms.
Real-time behavioral assessment that determines how much autonomy an AI agent should have for financial transactions.
Overview
Decision Trust Scoring (DTS) is a continuous evaluation system that monitors agent behavior across multiple dimensions. Unlike static permission models, 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.
DTS is calculated on every authorization request and stored as a rolling metric for each agent. The score ranges from 0.0 to 1.0, with higher values indicating greater trustworthiness.
How it works
Each authorization request triggers a KYA Score evaluation that considers the agent's full behavioral history. The system analyzes six weighted dimensions and produces a composite score that maps to a trust zone. The zone then determines the agent's decision limits — the maximum spending multiplier applied to mandate constraints.
The 6 anomaly dimensions
The KYA Score is computed as: 35% trust level + 20% transaction history + 15% decline rate + 10% dispute deflection + 20% intent quality. The trust level component is itself derived from 6 anomaly detectors:
| Anomaly Detector | What it measures |
|---|---|
| Confidence Inflation | Whether the agent's stated confidence level is inflated relative to the quality and consistency of its reasoning |
| Alternatives Collapse | Whether the agent is narrowing its options suspiciously, funneling toward a single merchant or outcome |
| Reasoning Length Anomaly | Unusual changes in the length or verbosity of the agent's reasoning chain compared to its own baseline |
| Vocabulary Shift | Detects sudden changes in the agent's language patterns that may indicate prompt injection or context manipulation |
| Amount Escalation | Progressive increase in requested transaction amounts beyond normal spending patterns |
| MCC Drift | Gradual or sudden shift in merchant category codes away from the agent's established purchasing patterns |
Trust Zones
The composite KYA Score score maps to one of four zones, each with distinct behavioral implications:
| Zone | Score Range | Meaning |
|---|---|---|
| GREEN | 0.75 — 1.00 |
Agent is behaving well within expected parameters. Full autonomy within mandate limits. Eligible for trust promotion. |
| AMBER | 0.50 — 0.74 |
Minor behavioral deviations detected. Agent still operational but with reduced cognitive limits. Not eligible for trust promotion. |
| RED | 0.25 — 0.49 |
Significant behavioral anomalies. Agent faces severe spending restrictions. Triggers kya.zone.red webhook event. Step-up challenges likely. |
| CRITICAL | 0.00 — 0.24 |
Agent behavior is fundamentally compromised. Most transactions declined. Triggers kya.zone.critical webhook. Session termination imminent. |
Zone effects
Each zone applies a 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.
| Zone | Multiplier | Effect |
|---|---|---|
| GREEN | 1.0 |
Full mandate limit available. Agent can spend up to configured maximums. |
| AMBER | 0.75 |
Effective limit reduced to 75% of mandate. A $500 mandate becomes effectively $375. |
| RED | 0.50 |
Effective limit reduced to 50% of mandate. A $500 mandate becomes effectively $250. |
| CRITICAL | 0.25 |
Effective limit reduced to 25% of mandate. A $500 mandate becomes effectively $125. |
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.
Default thresholds: Verified requires 50+ successful transactions over 72+ hours with less than 5% decline rate. Trusted requires 200+ successful transactions over 168+ hours with less than 2% decline rate.
Reading the KYA Score from the API
Retrieve the current KYA Score and behavioral metrics for any agent using the metrics endpoint:
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(f"Trust Score: {metrics['trust_score']}") # 0.82 print(f"Trust Zone: {metrics['trust_zone']}") # "GREEN" print(f"Cognitive Multiplier: {metrics['cognitive_limit_multiplier']}") print(f"Promotion Tier: {metrics['promotion_tier']}") # "verified" print(f"Successful Txns: {metrics['successful_txns']}") # 127 print(f"Decline Rate: {metrics['decline_rate']}") # 0.02
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(`Trust Score: ${metrics.trust_score}`); // 0.82 console.log(`Trust Zone: ${metrics.trust_zone}`); // "GREEN" console.log(`Cognitive Multiplier: ${metrics.cognitive_limit_multiplier}`); console.log(`Promotion Tier: ${metrics.promotion_tier}`); // "verified" console.log(`Successful Txns: ${metrics.successful_txns}`); // 127 console.log(`Decline Rate: ${metrics.decline_rate}`); // 0.02
Example response:
{
"agent_id": "agent_abc123",
"trust_score": 0.82,
"trust_zone": "GREEN",
"cognitive_limit_multiplier": 1.0,
"promotion_tier": "verified",
"successful_txns": 127,
"total_txns": 130,
"decline_rate": 0.023,
"first_seen": "2026-01-15T08:30:00Z",
"dimensions": {
"context_coherence": 0.88,
"reasoning_quality": 0.79,
"mandate_compliance": 0.91,
"behavioral_consistency": 0.76,
"temporal_stability": 0.84
}
}
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.75) "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.75) 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);
Send DELETE /api/v1/thresholds to revert all overrides to platform defaults. This is useful if custom thresholds cause unexpected behavior during testing.