AgentTrust Docs

Overview

Exception types raised by the AgentTrust Python SDK.

Why It Matters

Proper exception handling prevents silent governance bypass and enables correct user-facing error messages.

Step-by-Step Guide

Exception hierarchy

from agentrust_sdk import (
    BlockedError,
    TierGateError,
    GatewayUnavailableError,
    GatewayVersionError,
)

Exception	When raised	Recovery
`BlockedError`	`@harness` saw a `block` outcome (or `escalate` / `request_evidence` with `block_on_review=True`)	Read `e.outcome`, `e.reason`, `e.envelope_id`; fix the agent or the policy
`GatewayUnavailableError`	Gateway unreachable and `AGENTRUST_FAILURE_MODE=closed`	Fix the gateway, or switch to `open` / `queue`
`GatewayVersionError`	SDK version incompatible with gateway	Upgrade SDK or gateway
`TierGateError`	Only when `parent_envelope_id` is passed without the `trust_chain` capability and `raise_on_tier_gate=True` (default `False`). Framework adapters do not raise it — they raise plain `RuntimeError`.	Upgrade subscription

Handling pattern

from agentrust_sdk import harness, BlockedError, GatewayUnavailableError

@harness(block_on_block=True)
def agent(user, input):
    return run_llm(input)

try:
    agent(user="alice", input="query")
except BlockedError as e:
    return {
        "error": "governance_blocked",
        "outcome": e.outcome,
        "detail": e.reason,
        "envelope_id": e.envelope_id,
    }
except GatewayUnavailableError:
    return {"error": "governance_unavailable"}

TypeScript equivalents

import {
  AgentTrustError,
  BlockedError,
  GatewayUnavailableError,
  TierGateError,
} from 'agentrust-sdk';

The TypeScript SDK has no GatewayVersionError; a 426 from the gateway surfaces as a plain Error, and under failureMode: 'open' it is swallowed and a pass-through response is returned.

Best Practices

Catch BlockedError at user-facing boundaries
Alert on GatewayUnavailableError in production
Never catch and ignore TierGateError silently — and remember adapters raise RuntimeError, not TierGateError
Log e.reason and e.envelope_id with every block

Common Mistakes

Catching Exception broadly and continuing
Confusing BlockedError (governance decision) with GatewayUnavailableError (infra)

Exceptions Reference