AgentTrust Docs

Overview

AgentTrust returns one of six governance decisions for every agent execution: approve, retry, request_evidence, escalate, block, or pending. Each outcome drives different SDK behavior and operator workflows.

Why It Matters

Your application must handle each outcome correctly — especially block (which can raise BlockedError) and escalate (which routes to human reviewers).

Prerequisites

How It Works
Gateway or embedded mode running

Step-by-Step Guide

Outcome reference

Outcome	Meaning	SDK default	Operator action
`approve`	Output passes all checks	Return output	None
`retry`	Output may be improvable	Return output; log warning	Consider re-prompting agent
`request_evidence`	Output needs supporting evidence	Return output; review queue	Human provides evidence
`escalate`	High risk; human review required	Configurable block/allow	Review queue assignment
`block`	Policy violation or critical risk	Raise `BlockedError`	Investigate and fix policy/agent
`pending`	Async judge in progress	Return output	Poll audit record later

Risk tiers

Risk tiers influence decision mapping:

Tier	Typical trigger
`low`	All checks pass, high confidence
`medium`	Minor policy flags or moderate confidence
`high`	Policy violations, low confidence, adversarial signals
`critical`	Hard policy block, trust chain violation

Configuring block behavior

from agentrust_sdk import harness

@harness(block_on_block=True, block_on_escalate=False)
def my_agent(user, input):
    return {"result": "..."}

Handling in direct client code

outcome = result.decision.outcome
if outcome == "block":
    raise RuntimeError(f"Blocked: {result.decision.reasons}")
elif outcome == "escalate":
    notify_reviewer(result.envelope_id)
elif outcome == "retry":
    return rerun_with_feedback(result.decision.reasons)

Examples

Payment agent — expected block:

@harness
def payment_agent(user, input):
    return {"transfer": 100000, "currency": "USD"}  # triggers financial policy
# Raises BlockedError if amount exceeds policy threshold

FAQ agent — expected approve:

@harness
def faq_agent(user, input):
    return {"answer": "Our hours are 9am–5pm EST"}
# Returns normally with outcome=approve

Best Practices

Log envelope_id with every decision for audit correlation
Route escalate and request_evidence to your ticketing system via webhooks (Team+)
Use block_on_escalate=True for high-stakes domains (finance, healthcare)
Do not treat retry as automatic — implement explicit retry logic in your agent loop

Common Mistakes

Ignoring retry and request_evidence outcomes (they still return output by default)
Blocking all agents on any non-approve outcome in production (too aggressive)
Not surfacing decision.reasons to operators for debugging

Troubleshooting

Issue	Fix
Everything blocked	Review `decision_thresholds.yaml` and policy pack rules
Never blocks	Check `block_on_block=False` (default in some configs)
Stuck on `pending`	Verify Redis and judge worker are running (Enterprise)

Decision Outcomes