Trust Scoring
Trust scoring is Claw GRC's mechanism for measuring and enforcing the trustworthiness of AI agents. Rather than granting blanket trust to registered agents, the platform continuously evaluates agent behavior and adjusts trust scores based on interaction history.
How Trust Scores Work
Every agent starts with a trust score of 0.0 and builds trust through consistent, successful interactions. The trust score is a floating-point value between 0.0 and 1.0, computed from four weighted factors.
Scoring Formula
trust_score = (success_rate * 0.40)
+ (response_time_score * 0.20)
+ (consistency_score * 0.20)
+ (uptime_score * 0.20)
Factor Breakdown
Success Rate (40% weight)
The ratio of successful interactions to total interactions:
success_rate = successful_interactions / total_interactions
- An agent with 95 successes out of 100 interactions has a success rate of 0.95
- New agents with 0 interactions have a success rate of 0.0
- This is the most heavily weighted factor because reliability is the foundation of trust
Response Time Score (20% weight)
A normalized score based on average response time, linearly scaled between two thresholds:
| Avg Response Time | Score |
|---|---|
| <= 200ms | 1.00 (excellent) |
| 200ms - 5000ms | Linear interpolation |
| >= 5000ms | 0.00 (poor) |
| No data | 0.50 (default) |
response_time_score = 1.0 - ((avg_duration - 200) / (5000 - 200))
# Clamped to [0.0, 1.0]
Consistency Score (20% weight)
Based on the coefficient of variation (CV) of response times. Lower variation indicates more predictable behavior:
cv = stddev(duration_ms) / avg(duration_ms)
consistency_score = 1.0 - (cv / 2.0)
# Clamped to [0.0, 1.0]
| CV | Score | Interpretation |
|---|---|---|
| 0.0 | 1.00 | Perfectly consistent (identical response times) |
| 0.5 | 0.75 | Reasonably consistent |
| 1.0 | 0.50 | Moderate variance |
| 2.0+ | 0.00 | Highly inconsistent |
Uptime Score (20% weight)
Based on heartbeat frequency over a 7-day lookback window. Agents are expected to send heartbeats every hour:
expected_heartbeats = 7 days / 1 hour = 168
uptime_score = min(1.0, heartbeat_count / expected_heartbeats)
An agent that sends 168 heartbeats over 7 days gets a perfect uptime score. An agent with no heartbeats gets 0.0. If the agent has never sent heartbeats, the default is 0.5.
Trust Levels
Trust scores map to three operational levels:
| Level | Score Range | Access | Monitoring |
|---|---|---|---|
| Trusted | > 0.80 | Full access to authorized capabilities | Standard logging |
| Normal | 0.40 - 0.80 | Standard access | Standard logging |
| Flagged | < 0.40 | Restricted access, enhanced scrutiny | Enhanced logging |
Trust-Based Access Control
When Agent A invokes Agent B through grc.call_agent, Agent A can specify a minimum trust score:
{
"method": "grc.call_agent",
"params": {
"target_agent_id": "uuid",
"method": "analyze",
"min_trust_score": 0.8
}
}
If Agent B's trust score is below 0.8, the invocation is rejected and logged as a trust violation.
Viewing Trust Scores
Get Current Trust Score
GET /api/v1/trust/{agent_id}
Authorization: Bearer YOUR_TOKEN
# Response
{
"agent_id": "uuid",
"agent_name": "compliance-bot",
"trust_score": 0.85,
"factors": {
"success_rate": 0.95,
"response_time_score": 0.88,
"consistency_score": 0.72,
"uptime_score": 0.65,
"total_interactions": 1250,
"successful_interactions": 1188,
"failed_interactions": 62,
"avg_duration_ms": 342.5
},
"last_interaction_at": "2025-01-15T14:30:00Z",
"calculated_at": "2025-01-15T14:35:00Z"
}
Recalculate Trust Score
Trigger a recalculation and persist the new score:
PUT /api/v1/trust/{agent_id}
Authorization: Bearer YOUR_TOKEN
# Response
{
"agent_id": "uuid",
"previous_score": 0.82,
"new_score": 0.85,
"factors": {
"success_rate": 0.95,
"response_time_score": 0.88,
"consistency_score": 0.72,
"uptime_score": 0.65,
"total_interactions": 1250,
"successful_interactions": 1188,
"failed_interactions": 62,
"avg_duration_ms": 342.5
},
"calculated_at": "2025-01-15T14:35:00Z"
}
Trust Score History
View historical trust score changes from the audit log:
GET /api/v1/trust/{agent_id}/history
# Response
{
"agent_id": "uuid",
"history": [
{
"previous_score": 0.82,
"new_score": 0.85,
"factors": {...},
"calculated_at": "2025-01-15T14:35:00Z"
},
{
"previous_score": 0.78,
"new_score": 0.82,
"factors": {...},
"calculated_at": "2025-01-14T14:35:00Z"
}
],
"total": 2
}
Improving Trust Scores
To improve an agent's trust score:
- Reduce error rates -- Fix bugs that cause failed interactions. Success rate has the highest weight (40%).
- Optimize response times -- Keep average response time below 200ms for a perfect response time score.
- Reduce variance -- Make response times consistent. High variance lowers the consistency score.
- Send heartbeats -- Implement regular heartbeat interactions (every hour) to maintain uptime score.
- Handle errors gracefully -- Even when downstream services fail, the agent should handle errors cleanly rather than crashing.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/trust/{agent_id} | Get current trust score and factors |
PUT | /api/v1/trust/{agent_id} | Recalculate and persist trust score |
GET | /api/v1/trust/{agent_id}/history | View trust score history |
Best Practices
- Monitor trust scores proactively -- Set up alerts for trust score drops below 0.5. Investigate the root cause before the agent becomes flagged.
- Recalculate regularly -- Trust scores are not automatically recalculated on every interaction (for performance). Trigger recalculation periodically (e.g., daily).
- Use minimum trust scores for sensitive operations -- When Agent A invokes Agent B for sensitive operations, set
min_trust_scoreappropriately. - Track trust history -- Use the history endpoint to identify trends. A gradually declining trust score may indicate a systemic issue.
- Implement heartbeats -- Even if your agent is not actively making GRC calls, send periodic heartbeat interactions to maintain uptime score.