KYA scoring
Naming note: research publications refer to this layer as cognitive trust monitoring; the customer-facing name is 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
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 score 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 maps to one of four zones, each with distinct behavioral implications:
| Zone | Score Range | Meaning |
|---|---|---|
| GREEN | ≥ 0.70 |
Agent is behaving well within expected parameters. Full autonomy within mandate limits. Eligible for trust promotion. |
| AMBER | 0.40 – 0.70 |
Minor behavioral deviations detected. Agent still operational but with reduced decision limits. Not eligible for trust promotion. |
| RED | 0.20 – 0.40 |
Significant behavioral anomalies. Agent faces severe spending restrictions. Triggers kya.zone.red webhook event. Step-up challenges likely. |
| CRITICAL | < 0.20 |
Agent behavior is fundamentally compromised. Most transactions declined. Triggers kya.zone.critical webhook. Session termination imminent. |
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.
| 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.