Modes and Failure Behavior

This is the reference for configuring gateway resiliency and enforcement behavior. Use this guide to understand how your agents will behave when policies match or when the NjiraAI platform is unreachable.

Enforcement Modes

NjiraAI provides discrete modes to safely test and roll out policies to live traffic.

Shadow Mode (shadow)

Use Shadow mode to safely prove out new policies before enforcing them on live workflows.

• Behavior: The gateway evaluates traffic and computes verdicts, but never blocks or modifies the underlying request.
• Console: Verdicts are logged as would-have-blocked in the Traces view.
• Use Case: Initial production rollouts and regression testing on real-world traffic.

Active Mode (active)

Use Active mode when your shadow metrics confirm the policy is safe and accurately scoped.

• Behavior: Fully applies BLOCK and MODIFY verdicts. If blocked, the upstream request is halted.
• Console: Verdicts are logged as enforced decisions.
• API Value: When integrating via the API or SDK, configure this mode using the string "active".

Terminology note: active is the canonical mode value in configuration and API payloads. Enforce is acceptable shorthand for the behavior, but it is not a mode string to send.

Dry Run Mode (dry_run)

Use Dry Run mode to pass traffic locally without reaching the cloud.

• Behavior: No network calls are made to the Njira API. All requests are locally allowed and generate no traces.
• Use Case: Local unit testing, CI/CD smoke tests, or offline debugging.

Incident Response: Outage Handling

What happens when the Njira API is unavailable due to network timeouts or cloud connectivity issues? The NJIRA_FAIL_STRATEGY environment variable controls this fallback.

Fail Open (fail_open)

• Behavior: The agent request or tool call is allowed to proceed immediately.
• Recorded Reason: NJIRA_UNAVAILABLE
• Trade-off: Prioritizes operational uptime over strict safety. Recommended for consumer-facing chat or high-availability internal tools.

Fail Closed (fail_closed)

• Behavior: The agent request or tool call is strongly blocked. An error is returned to the agent.
• Recorded Reason: NJIRA_UNAVAILABLE
• Trade-off: Prioritizes absolute safety over availability. Recommended for high-risk capabilities like money movement or PII handling.

Recommended Rollout Playbook

When integrating a new agent or deploying critical safety guards, follow this operational sequence:

1. Test Environment (dry_run or shadow)
   • Verify SDK initialization and middleware placement.
   • Run unit tests in dry_run.
2. Shadow Rollout (shadow + fail_open)
   • Bind the agent environment to shadow mode.
   • Run live traffic for 1-2 weeks.
   • Monitor the would-have-blocked metric for false positives.
3. Active Enforcement (active + fail_open)
   • Switch the binding to active.
   • The agent is now protected. If Njira drops, the workflow remains up.
4. Strict Enforcement (active + fail_closed)
   • (Optional) Once latency and reliability are proven, tighten the failure strategy on critical tools to prevent any bypass.

Configuration Reference

SDK / Environment

Variable / Setting	Acceptable Values	Default Fallback
NJIRA_MODE	shadow, active, dry_run	shadow
NJIRA_FAIL_STRATEGY	fail_open, fail_closed	fail_open
NJIRA_TIMEOUT_MS	Integer (milliseconds)	5000

TypeScript Configuration

const njira = new NjiraAI({
  apiKey: "...",
  mode: "active",        // Canonical active mode value
  failStrategy: "fail_closed",
  timeoutMs: 3000,
});

Python Configuration

njira = NjiraAI(
    api_key="...",
    mode="active",       # Canonical active mode value
    fail_strategy="fail_closed",
    timeout_ms=3000,
)