Reference

Exceptions Reference

SDK exception hierarchy and when each is raised.

Exceptions Reference

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,
)
ExceptionWhen raisedRecovery
BlockedErrorDecision outcome is block, or escalate with block_on_escalate=True, or failure_mode=closed on gateway errorReview decision.reasons; fix agent or policy
GatewayUnavailableErrorGateway unreachable and failure_mode=closedFix gateway or switch to open/queue
GatewayVersionErrorSDK version incompatible with gatewayUpgrade SDK or gateway
TierGateErrorTier-gated adapter/capability without sufficient tierUpgrade 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("alice", "query")
except BlockedError as e:
    return {"error": "governance_blocked", "detail": str(e)}
except GatewayUnavailableError:
    return {"error": "governance_unavailable"}

TypeScript equivalents

import { BlockedError, GatewayError } from 'agentrust-sdk';

Best Practices

  • Catch BlockedError at user-facing boundaries
  • Alert on GatewayUnavailableError in production
  • Never catch and ignore TierGateError silently
  • Log full decision.reasons with every block

Common Mistakes

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

Models Reference

ValidateRequest, ValidateResponse, and SDK data models.

TypeScript SDK Reference

Node.js SDK API — AgentTrustClient, wrap(), and types.

On this page

OverviewWhy It MattersStep-by-Step GuideException hierarchyHandling patternTypeScript equivalentsBest PracticesCommon MistakesRelated Resources