AgentTrust Docs

Overview

When the AgentTrust gateway is unreachable, the SDK's AGENTRUST_FAILURE_MODE setting determines whether your agent continues, stops, or buffers validations locally. Three modes are available: open, closed, and queue.

Why It Matters

Choosing the wrong failure mode can either silently skip governance (compliance risk) or halt production agents during gateway maintenance (availability risk).

Prerequisites

Remote gateway configured via AGENTRUST_GATEWAY_URL
Understanding of your availability vs compliance requirements

Step-by-Step Guide

Mode comparison

Mode	Gateway unreachable behavior	Agent continues?
`open` (default)	Log warning; return synthetic `approve`	✅ Yes
`closed`	Raise `GatewayUnavailableError` / `BlockedError`	❌ No
`queue`	Buffer to local SQLite; return synthetic `approve`	✅ Yes

Configure

export AGENTRUST_FAILURE_MODE=open    # default
export AGENTRUST_FAILURE_MODE=closed  # fail-closed
export AGENTRUST_FAILURE_MODE=queue   # buffer for replay

Open mode (default)

# Agent runs normally; governance is skipped with a warning log
# Best for: production where agent availability > governance during outages

Closed mode

from agentrust_sdk import AgentTrustClient
from agentrust_sdk.decorator import BlockedError, GatewayUnavailableError

client = AgentTrustClient(failure_mode="closed")
# Raises GatewayUnavailableError if gateway is down
# Best for: staging, compliance-critical paths

Queue mode

import os
os.environ["AGENTRUST_FAILURE_MODE"] = "queue"
os.environ["AGENTRUST_QUEUE_DB"] = "~/.agentrust/queue.db"

# Validations buffered when gateway is down
# Replay when gateway returns — see Queue Replay guide

Kill-switch (separate from failure mode)

export AGENTRUST_ENABLED=false
# All governance paths become no-ops — instant rollback

Examples

Staging — fail closed:

AGENTRUST_GATEWAY_URL=https://staging.internal:8000
AGENTRUST_FAILURE_MODE=closed

Production — fail open:

AGENTRUST_GATEWAY_URL=https://agentrust.internal:8000
AGENTRUST_FAILURE_MODE=open
AGENTRUST_RETRY_ATTEMPTS=5

Air-gap — queue:

AGENTRUST_FAILURE_MODE=queue
# ... later when gateway is reachable:
agentrust queue replay

Best Practices

Use closed in staging to catch gateway misconfigurations before production
Use open in production unless regulations require fail-closed
Use queue for intermittent connectivity (field deployments, air-gap)
Combine with AGENTRUST_RETRY_ATTEMPTS (requires [retry] extra)
Test failure modes in staging by stopping the gateway container

Common Mistakes

Using closed in production without alerting on GatewayUnavailableError
Expecting queue mode to auto-replay without calling drain_queue() or CLI
Confusing AGENTRUST_ENABLED=false (kill-switch) with failure mode

Troubleshooting

Symptom	Fix
Silent governance skip	Check `failure_mode=open` + gateway down
All requests blocked	Gateway down + `failure_mode=closed`
Queue growing	Run `agentrust queue replay` when gateway is up

Failure Modes