AgentTrust Docs

Overview

Queue mode (AGENTRUST_FAILURE_MODE=queue) buffers validation requests to a local SQLite database when the gateway is unreachable. When connectivity returns, you replay buffered records to the gateway using drain_queue() or the CLI.

Why It Matters

Air-gapped, field, or intermittently connected deployments need governance audit records without blocking agent execution during outages.

Prerequisites

pip install agentrust-py
export AGENTRUST_FAILURE_MODE=queue

Step-by-Step Guide

1. Enable queue mode

export AGENTRUST_FAILURE_MODE=queue
export AGENTRUST_QUEUE_DB=~/.agentrust/queue.db  # default

2. Agent runs during outage

Validations are written to SQLite. Agent receives synthetic approve and continues.

3. Replay when gateway returns

Python API:

from agentrust_sdk import drain_queue

sent, failed = drain_queue()
print(f"Replayed {sent}, failed {failed}")

drain_queue() is the only public replay entry point. It replays every buffered record against AGENTRUST_GATEWAY_URL and returns (sent, failed); successfully replayed rows are deleted from the queue database.

CLI:

agentrust queue status   # show buffered count
agentrust queue replay   # drain buffer to gateway

4. Inspect buffered records

agentrust export writes audit records, not queued ones. To inspect the queue itself, use the CLI counter or read the SQLite file directly:

agentrust queue status                       # buffered record count

sqlite3 ~/.agentrust/queue.db \
  "SELECT id, queued_at, attempts FROM queue ORDER BY id LIMIT 20;"

Examples

Air-gap workflow:

import os
os.environ["AGENTRUST_FAILURE_MODE"] = "queue"

from agentrust_sdk import harness, AgentTrustClient, drain_queue

@harness
def field_agent(user, input):
    return {"data": collect_sensor_data()}

# Run offline for hours/days... (keyword args — @harness reads them by name)
field_agent(user="operator", input="read sensors")

# When back online:
sent, failed = drain_queue()

Best Practices

Monitor queue size with agentrust queue status
Replay promptly when gateway is available (audit lag compliance)
Use dedicated AGENTRUST_QUEUE_DB path in containerized deployments
Do not rely on queue mode for real-time blocking — it's approve-and-buffer

Common Mistakes

Expecting automatic replay without calling drain — see the note on auto-drain below
Using queue mode in TypeScript SDK (Python only)
Filling disk with unbounded queue — monitor and replay regularly

Troubleshooting

Issue	Fix
Queue not draining	Verify gateway reachable; check API key
Replay failures	`agentrust export` reads the audit databases, not the queue — inspect `~/.agentrust/queue.db` directly, or watch the warning logs `drain_queue()` emits per failed record
Empty queue but records expected	Confirm `AGENTRUST_FAILURE_MODE=queue` was set during outage

Automatic draining

When AGENTRUST_FAILURE_MODE=queue and a queue database already exists, constructing an AgentTrustClient kicks off one background drain attempt in a daemon thread. That is a best-effort convenience, not a guarantee: it runs once per client construction and its result is only logged. Treat agentrust queue replay (or drain_queue()) as the authoritative way to flush the buffer.

Queue Replay