Failure modes

A check can fail for reasons unrelated to the prompt: a network error, a timeout, or an unavailable dependency. The system's failure mode decides what happens next.

Mode	Setting	On failure
Fail-open	Default; Strict Security (Fail-Closed) off	The request continues
Fail-closed	Strict Security (Fail-Closed) on	The request is blocked

Shadow Mode always behaves as fail-open. A policy block (for example pii_blocked) is never a failure: it is enforced in both modes.

Guard API responses

Situation	Fail-open	Fail-closed
Dependency failure during the check	200, allowed: true, bypassed: true, header X-AgentID-Status: BYPASSED_INFRA_ERROR	503, allowed: false, reason system_failure or system_failure_db_unavailable
Required personal-data detection unavailable	Falls back to the deterministic detection layer	200, allowed: false, reason pii_detection_unavailable
Rate-limit or quota service unavailable	Request continues	200, allowed: false, reason ending in _unavailable
Automatic circuit breaker open	503, reason circuit_breaker	503, reason circuit_breaker

Always read allowed; do not rely on the HTTP status alone.

Integrations

Node.js, Vercel AI SDK and Python SDKs

• The SDKs follow the system's setting unless you set it in code (strictMode / failureMode in Node.js, strict_mode / failure_mode in Python).
• On a timeout or network error in fail-open mode, guard() returns allowed: true with a reason such as timeout_fallback or guard_unreachable. In fail-closed mode it returns allowed: false (for example network_error_strict_mode).
• Fail-open does not mean "send raw data" for the Node.js wrappers: from agentid-sdk 0.1.40, wrapOpenAI and withAgentId keep local masking of personal data and secrets when Guard or the configuration endpoint is unreachable. If you call guard() directly, a fail-open verdict has no transformed_input; mask locally (for example with protectMessageHistory) before you send the text.
• In fail-closed mode the wrappers can run a local fallback check; a local hit still blocks.
• Guard calls are retried on network errors, timeouts and 5xx responses, up to three attempts in total.

Browser extension

The extension follows the system's live setting. Before it can read the system configuration it uses its bootstrap protection mode: Fail Closed for managed deployments unless set otherwise, Fail Open for manual setup. In fail-closed mode, guard, network or configuration failures stop the prompt from being sent. A slow check is retried once in the fast minimal mode; the extension does not send an unmasked prompt because of a slow check.

Claude plugin

Bundles follow the system's Guardrails setting (Claude systems start fail-open):

• Fail-open: Claude continues.
• Fail-closed: protected document reads and calls that can carry data off the device (shell, web, MCP actions other than reads) do not run when AgentID cannot inspect them. Local tools, prompts and responses continue.

Claude Desktop companion

The companion follows the system's setting. With fail-closed, a prompt is not sent when AgentID is unreachable, and also when a Claude Desktop update stops the companion from detecting the prompt box.

Choosing a mode

• Choose fail-closed where sending unchecked data is worse than an interrupted user: regulated data, healthcare, finance, legal.
• Choose fail-open where availability matters most and SDK-side masking or the browser's minimal retry gives you a safety net.
• Calibrate new systems in Shadow Mode, then switch to Active Guard and pick the failure mode.