Queue Replay

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-sdk
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, maybe_drain_on_success

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

# Auto-drain on successful validation (background)
maybe_drain_on_success()  # called internally after successful validate

CLI:

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

4. Inspect buffered records

agentrust export ./queued.jsonl

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...
field_agent("operator", "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 (partial auto-drain on success only)
• Using queue mode in TypeScript SDK (Python only)
• Filling disk with unbounded queue — monitor and replay regularly

Troubleshooting

Related Resources

• Failure Modes
• CLI: queue
• Environment Variables