Shadow Mode

Run the full governance pipeline on real agent actions without enforcing decisions. See what GaaS would do before turning it on.

Why Shadow Mode

No governance system should go from zero to enforcement without a trial period. Shadow mode lets you observe the pipeline — validation, enrichment, policy evaluation, and decision assembly — on real traffic, while your agents continue to operate freely. Deliberation (stage 4) is bypassed in shadow mode for performance; all other stages execute identically to live mode.

You get real governance decisions tagged as shadow. You see what would have been blocked, what would have been modified, what would have triggered escalation. You can review, submit feedback, and refine your membrane — all before a single action is actually blocked.

How to Enable

Option 1: Query Parameter

Add ?mode=shadow to any intent submission:

POST /v1/intents?mode=shadow

Submit an intent for shadow evaluation — full pipeline, no enforcement

The intent is processed through stages 1–3 and 5 (validation, enrichment, policy evaluation, and decision assembly). Deliberation (stage 4) is skipped in shadow mode for performance. The response is structurally identical to a live decision — same verdict format, same risk assessment — but the pipeline_mode field is set to shadow and no enforcement occurs.

Option 2: Membrane Lifecycle

When you onboard via the quickstart endpoint, your membrane starts in SHADOW mode automatically. All intents evaluated against that membrane run through shadow mode by default until you explicitly activate live mode.

Per-intent control. Shadow mode can be set per-intent with the ?mode=shadow query parameter, regardless of the membrane's state. This means you can run shadow on some intents while others go through live evaluation.

Membrane Lifecycle

The membrane moves through three defined states:

1

DRAFT

Membrane is being generated. Not yet evaluating intents.

2

SHADOW

Full pipeline evaluation on real traffic. Decisions are logged but not enforced. This is the default after quickstart onboarding.

3

LIVE

Governance decisions are enforced. Agents must act on verdicts.

Reversible. You can move from LIVE back to SHADOW at any time. All audit records from both modes are preserved.

What Happens Differently

Behavior Live Shadow
Full pipeline evaluation Yes Yes
Decision returned to caller Enforced Informational
Escalations created Yes No
Learning observations Tagged live Tagged shadow
Dashboard live metrics Included Excluded
Shadow stats updated No Yes
Audit trail recorded Yes Yes
Response pipeline_mode live shadow
Critical safety exception. If GaaS detects an action in shadow mode that would trigger a Tier 1 critical block in live — for example, sending regulated data over an unencrypted channel — it breaks silence and alerts you immediately. Safety does not wait for the shadow period to end.

Monitoring Shadow Decisions

Decision Stream

The conversational dashboard supports filtering the decision stream by pipeline mode. Ask:

"Show me shadow decisions from the last 7 days"

Or query the API directly:

GET /v1/dashboard/decisions?pipeline_mode=shadow&time_range=last_7d

Shadow Stats

Each membrane tracks aggregate shadow statistics: total shadow decisions, verdict distribution, average risk score, contradiction rate, and policy coverage.

GET /v1/membranes/{membrane_id}/shadow/stats

Aggregate shadow mode statistics for a membrane

Submitting Feedback

While reviewing shadow decisions, flag false positives or false negatives. The learning engine uses this feedback to refine your membrane before you go live.

Transitioning to Live

When you're ready to activate enforcement, follow this migration checklist:

STEP 1

Review Shadow Data

Focus on:

STEP 2

Submit Feedback

Mark incorrect decisions through the dashboard or the learning API. The learning engine factors this into calibration.

STEP 3

Verify Coverage

Check shadow statistics to ensure you've collected sufficient data across all agent action patterns: 

GET /v1/membranes/{membrane_id}/shadow/stats

Aim for at least 100 shadow decisions covering all critical action types before activating live mode.

STEP 4

Notify Stakeholders

Alert your team that governance enforcement will begin. Ensure operators know how to review escalations and handle blocked actions.

STEP 5

Activate Live Mode

When confident, switch to live mode: 

POST /v1/membranes/{membrane_id}/activate

{
  "activation": {
    "mode": "live"
  }
}
Instant rollback. If anything looks wrong after going live, revert to shadow mode with a single call. Your agents continue operating, and governance decisions become informational again immediately.

Related Pages