From e7ad5dd7ea03b434c19f013f880ba9d5f72089f1 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 30 Sep 2026 16:17:01 -0700 Subject: [PATCH 1/2] docs(guardrails): describe streaming and actions as the gateway runs them Post-stage guardrails were described as checking a streamed response before it reaches the caller and ending the stream on a block. Only config-file rules with guardrails.streaming.enabled act while a stream is generated; other post-stage checks run once after it has been delivered. Mask was also listed as a guardrail action, but the gateway runs it as Log; masking PII is the PII check's remediation setting. Co-Authored-By: Claude Opus 5.5 --- .../command-center/concepts/api-reference.mdx | 2 +- .../command-center/features/guardrails.mdx | 60 ++++++++++++++++--- .../command-center/features/streaming.mdx | 6 +- .../concepts/understanding-protect.mdx | 6 +- src/pages/docs/protect/index.mdx | 2 +- .../protect/reference/guardrail-checks.mdx | 8 ++- .../guardrail-fires-on-the-wrong-requests.mdx | 2 +- 7 files changed, 66 insertions(+), 20 deletions(-) diff --git a/src/pages/docs/command-center/concepts/api-reference.mdx b/src/pages/docs/command-center/concepts/api-reference.mdx index ced49af2b..0bfa71bf3 100644 --- a/src/pages/docs/command-center/concepts/api-reference.mdx +++ b/src/pages/docs/command-center/concepts/api-reference.mdx @@ -79,7 +79,7 @@ Agent Command Center returns standard HTTP error codes with structured JSON erro ### Guardrail blocked (403) -When a guardrail whose action is `block` triggers on a request, Agent Command Center returns 403. A pre-stage check returns it before the LLM is ever called; a post-stage check returns it instead of the model's response. A guardrail whose action is `warn` or `log` does not change the status: the call returns 200 with the header `x-agentcc-guardrail-triggered: true`. +When a guardrail whose action is `block` triggers on a request, Agent Command Center returns 403. A pre-stage check returns it before the LLM is ever called; a post-stage check returns it instead of the model's response. A guardrail whose action is `warn` or `log` does not change the status: the call returns 200 with the header `x-agentcc-guardrail-triggered: true`. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can return 403 or add the header; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). ```json { diff --git a/src/pages/docs/command-center/features/guardrails.mdx b/src/pages/docs/command-center/features/guardrails.mdx index 4d5b6bcbf..16502b3e2 100644 --- a/src/pages/docs/command-center/features/guardrails.mdx +++ b/src/pages/docs/command-center/features/guardrails.mdx @@ -5,7 +5,7 @@ description: "Enforce PII detection, prompt injection blocking, and content mode ## About -Guardrails are safety checks that run on every request and response flowing through Agent Command Center. They catch dangerous or unwanted content before it reaches the LLM (pre-processing) or before it reaches your users (post-processing). +Guardrails are safety checks that run on every request and response flowing through Agent Command Center. They catch dangerous or unwanted content before it reaches the LLM (pre-processing) or before it reaches your users (post-processing; for streamed responses, see [Streaming Guardrails](#streaming-guardrails)). When [caching](/docs/command-center/features/caching) is on and a request is served from an exact match hit, guardrails that check the request (Pre stage) do not run on that request. Guardrails that check the response (Post stage) still run on the cached response before it is returned. Disable caching for traffic that must be screened on every request. @@ -421,11 +421,18 @@ Use Redact or Mask to sanitize sensitive data while allowing the request to proc ## Streaming Guardrails -Guardrails work with streaming responses. Pre-processing guardrails run before streaming begins. Post-processing guardrails accumulate the full streamed response before evaluation. +When you stream a chat completion (`"stream": true` on `/v1/chat/completions`), Agent Command Center sends the response headers first, then the response in chunks as the model generates it. A guardrail's stage decides what it can still do: -- **Sync + block**: The stream terminates immediately if a violation is detected -- **Sync + warn**: A warning header is added, the stream continues -- **Async**: The guardrail runs fire-and-forget in the background: the stream is never interrupted +| Stage | When it runs on a stream | Effect | +|---|---|---| +| Pre (checks the request) | Before the stream opens | A `block` returns the 403 `content_blocked` error instead of a stream. A `warn` or `log` adds `x-agentcc-guardrail-triggered: true` to the stream's headers | +| Post (checks the response) | After the last chunk of response text, before `data: [DONE]` | Cannot stop or take back anything, because the headers and the response text have already gone out. `data: [DONE]` waits until these checks finish or time out. The result is recorded in the request log | + +The table applies to guardrails set up in the dashboard and to `config.yaml` rules, except a `config.yaml` rule with `mode: "async"`: it runs in the background, so it cannot block the request, add the header, or delay `data: [DONE]`, and it reports a failure only in the gateway's own log output. Guardrails set up in the dashboard or through the SDK always run synchronously, whatever `mode` they carry. + +Post-stage guardrails see the streamed text only on `/v1/chat/completions` and `/v1/completions`, and on a self-hosted gateway only when it records request and response bodies (`logging.request_logging.include_bodies: true`, or `otel.include_bodies: true` with `otel.enabled: true`). Otherwise they have no response text to check. + +To act on a response while it streams, run a self-hosted gateway and [check the stream as it is generated](#check-the-stream-as-it-is-generated). ```python Python @@ -437,13 +444,13 @@ client = AgentCC( control_plane_url="https://api.futureagi.com", ) -# Streaming with guardrails active on this key/org +# A pre-stage block raises here, before any chunk arrives for chunk in client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Tell me about security."}], stream=True, ): - if chunk.choices[0].delta.content: + if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) ``` @@ -455,6 +462,7 @@ const client = new AgentCC({ baseUrl: "https://gateway.futureagi.com", }); +// A pre-stage block throws here, before any chunk arrives const stream = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Tell me about security." }], @@ -468,8 +476,44 @@ for await (const chunk of stream) { ``` +### Check the stream as it is generated + +On a self-hosted gateway, the post-stage rules in [`config.yaml`](/docs/command-center/deployment/self-hosted#configuration-file) (`guardrails.rules`) can check a `/v1/chat/completions` response while the model is still generating it. This is off by default. Turn it on with `guardrails.streaming`: + +```yaml +guardrails: + enabled: true + rules: + - name: "content-moderation" + stage: "post" + mode: "sync" + action: "block" + threshold: 0.7 + streaming: + enabled: true + check_interval: 100 # Bytes of new response text between checks (default: 100) + failure_action: "stop" # "stop" (default) or "disclaimer" +``` + +Each time another `check_interval` bytes of text have arrived, the gateway holds the chunk that completes the interval and runs these rules on the whole response so far. It runs them once more when the model finishes, if text has arrived since the last check. Chunks in between are sent without waiting for a check, so up to `check_interval` bytes of text can reach the client before a check catches it, and a response shorter than `check_interval` is checked only after all of it has been sent. The stream waits while a check runs, so a smaller interval catches content sooner but runs more checks. Only `sync` rules whose action is `block` affect the stream: + +| `failure_action` | When a check fails | +|---|---| +| `stop` (default) | If a check during the stream fails, the gateway sends an error event instead of the chunk it held and ends the stream without `data: [DONE]`. If the check at the end fails, the whole response has already been sent: the error event follows it, and the stream still ends with `data: [DONE]` | +| `disclaimer` | The stream continues. If the check at the end fails, the gateway sends one more content chunk after the one with `finish_reason`: two newlines followed by `[Content warning: ]`. A check that fails during the stream adds no notice | + +With `disclaimer`, the check at the end runs only if text arrived after the last interval check. If the last chunk of text completes an interval, the response gets no notice, even when that check fails. + +The error event that `stop` sends: + +```text +data: {"error":{"message":"Content moderation triggered: violence (score: 1.00)","type":"guardrail_error","param":null,"code":"stream_blocked"}} +``` + +The HTTP status stays 200, because it was sent with the headers, and the chunks sent before the check are not taken back. + -Post-processing guardrails (stage: "post") accumulate the complete streamed response before evaluation. If a violation is detected in sync+block mode, the stream terminates and the client receives an error. Any chunks already delivered cannot be recalled. +Streaming checks use only the rules in `config.yaml`. Guardrails set up in the dashboard run only before the stream opens and after the response text has been sent, as described in [Streaming Guardrails](#streaming-guardrails), even when `guardrails.streaming.enabled` is `true`. --- diff --git a/src/pages/docs/command-center/features/streaming.mdx b/src/pages/docs/command-center/features/streaming.mdx index 5bbd1bef1..18726c8c4 100644 --- a/src/pages/docs/command-center/features/streaming.mdx +++ b/src/pages/docs/command-center/features/streaming.mdx @@ -192,7 +192,7 @@ Each event contains a delta with the next token or function call. The stream end ## Streaming with Guardrails -Post-processing guardrails accumulate chunks as they stream. If a guardrail triggers in Enforce mode, the stream terminates immediately with an error. In Monitor mode, a warning is logged but streaming continues. +Post-processing guardrails run after the response text has been sent, just before the closing `[DONE]`, so they cannot stop or change the stream, and a slow check delays `[DONE]`. A block or warning is recorded in the request log. A self-hosted gateway can also check the stream while it is generated and stop it. See [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). Pre-processing guardrails run before streaming begins. If they trigger in Enforce mode, the stream never starts. @@ -222,8 +222,8 @@ Your application receives identical SSE events regardless of the underlying prov Cache responses for faster repeated queries - - Enforce policies during streaming + + How guardrails treat streamed responses Route streaming requests across providers diff --git a/src/pages/docs/protect/concepts/understanding-protect.mdx b/src/pages/docs/protect/concepts/understanding-protect.mdx index e98c6807c..e7da40b50 100644 --- a/src/pages/docs/protect/concepts/understanding-protect.mdx +++ b/src/pages/docs/protect/concepts/understanding-protect.mdx @@ -7,8 +7,8 @@ description: "Protect screens your traffic for safety issues through guardrails A **guardrail** wraps a check and adds three settings you configure in [Agent Command Center](/docs/command-center/features/guardrails), under **Gateway** > **Guardrails**: -- An **action** for when it triggers: Block, Warn, Mask, or Log -- A **stage** for when it runs: **pre** runs before the model sees the request, **post** runs before the response reaches the caller, and **both** runs on each side +- An **action** for when it triggers: Block, Warn, or Log (masking PII is the PII check's own remediation setting, not an action) +- A **stage** for when it runs: **pre** runs before the model sees the request, **post** runs before the response reaches the caller (on a streamed response, after it has been sent; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails)), and **both** runs on each side - A **confidence threshold** for how sure the check has to be before it fires A stage of **both** isn't a third mode. It's the same check running twice, once on the way in and once on the way out. Stage belongs to the guardrail rather than to the check it wraps, which is why a single **gateway**, the Agent Command Center surface your guardrails live on, can carry a mix: some watching only what the caller sent, others only what the model sent back. @@ -20,7 +20,7 @@ Every guardrail wraps a check, and the Rules tab groups checks under two headers A["Action: Block, Warn, Mask, or Log"] + G["Guardrail"] --> A["Action: Block, Warn, or Log"] G --> S["Stage: pre, post, or both"] G --> T["Confidence threshold"] G --> C["Check"] diff --git a/src/pages/docs/protect/index.mdx b/src/pages/docs/protect/index.mdx index d9c9193fc..1243a70a6 100644 --- a/src/pages/docs/protect/index.mdx +++ b/src/pages/docs/protect/index.mdx @@ -5,7 +5,7 @@ description: "Where Protect's dashboard guardrails and SDK checks live" ## What is Protect? -**Protect** is the safety layer over your AI traffic. It runs named guardrail checks, like PII detection or prompt injection, on each request and returns one of four actions: [block, warn, mask, or log](/docs/protect/concepts/understanding-protect). +**Protect** is the safety layer over your AI traffic. It runs named guardrail checks, like PII detection or prompt injection, on each request and returns one of three actions: [block, warn, or log](/docs/protect/concepts/understanding-protect). You turn guardrails on in the dashboard under Gateway → Guardrails, where they apply to traffic passing through a gateway. If your app isn't pointed at [Agent Command Center](/docs/command-center) yet, see the [quickstart](/docs/command-center/quickstart) for swapping in the base URL and API key. You can also call `protect()` directly from your code to run checks inline on text, image, and audio inputs. Use the dashboard if traffic goes through a gateway; call `protect()` directly if it doesn't. diff --git a/src/pages/docs/protect/reference/guardrail-checks.mdx b/src/pages/docs/protect/reference/guardrail-checks.mdx index 27eac56d5..45641b2a0 100644 --- a/src/pages/docs/protect/reference/guardrail-checks.mdx +++ b/src/pages/docs/protect/reference/guardrail-checks.mdx @@ -87,17 +87,19 @@ A `topic-restriction` check groups its topics under 8 categories, most with thei Most fields below apply to every check in both the [first-party](#first-party-checks) and [provider-backed](#provider-backed-checks) tables above. A check that carries provider fields additionally has a Provider Settings section holding them, which is why `keyword-blocklist` shows its Blocked Keywords there despite being first-party. Confidence Threshold appears on every check except `futureagi-eval` and `presidio-pii`. -A check is configured from one of two dialogs: the per-check dialog covered under [Rules dialog](#rules-dialog), and the guardrail-level dialog covered under [Overview dialog](#overview-dialog). The two expose different fields: the Rules dialog offers Mask as an action option, plus a Confidence Threshold; the Overview dialog sets Stage. +A check is configured from one of two dialogs: the per-check dialog covered under [Rules dialog](#rules-dialog), and the guardrail-level dialog covered under [Overview dialog](#overview-dialog). The two expose different fields: the Rules dialog has a Confidence Threshold; the Overview dialog sets Stage. ### Rules dialog | Field | Values | Default | |---|---|---| | Enabled | Toggle | On | -| Action | Block, Warn, Mask, Log | Block | +| Action | Block, Warn, Log | Block | | Confidence Threshold | Slider from 0.0 to 1.0, marked at 0.0 / 0.5 / 1.0 | 0.8 | | Provider Settings (checks that have provider fields) | The check's provider configuration | | +A check saved with the Mask action, which older dashboards offered, runs as Log. To mask PII, set the PII check's remediation instead. + ### Overview dialog | Field | Values | Default | @@ -118,7 +120,7 @@ These apply to every check on the gateway rather than to an individual check. ## Response statuses -These are the statuses the [Agent Command Center](/docs/command-center) gateway returns on a guardrail decision. Only the Block action changes the status; Warn and Log let the call through. +These are the statuses the [Agent Command Center](/docs/command-center) gateway returns on a guardrail decision. Only the Block action changes the status; Warn and Log let the call through. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can change them; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). | Action | Status | What the caller gets | |---|---|---| diff --git a/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx b/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx index 885c96d7b..dc8c29370 100644 --- a/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx +++ b/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx @@ -22,7 +22,7 @@ Switch **Action** from Block to Warn or Log before you touch the Confidence Thre - **Warn** lets the request through, and counts toward that check's Warn total in Top Triggered Rules - **Log** lets the request through too, and still counts toward Triggers, but the check's Block and Warn totals stay flat, for a quieter pass while you compare several changes -**Mask** is also on the select, but it's a different use case outside this tuning flow. Set **Action** back to Block once you're satisfied with where the threshold lands. +Older dashboards also offer **Mask**, which runs as Log. Set **Action** back to Block once you're satisfied with where the threshold lands. ## Move its Confidence Threshold From ff2c176dca1f9f553dfcb6b50494e157091bb33d Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 4 Oct 2026 14:38:15 -0700 Subject: [PATCH 2/2] docs(guardrails): correct post-stage block statuses and drop the Mask change Only a pre-stage Block returns 403. A post-stage Block from a dashboard guardrail returns 200 with x-agentcc-guardrail-triggered, and a synchronous config.yaml post rule makes /v1/chat/completions return 500. Update api-reference, guardrail-checks, understanding-protect and the Enforcement Modes table to match. Note that the gateway doesn't apply a guardrail's Stage setting today (each check runs at its built-in stage) and align the Built-in Guardrail Types table with that. Revert the Mask action list change, which belongs with the dashboard change that removes Mask. Co-Authored-By: Claude Opus 5.5 --- .../command-center/concepts/api-reference.mdx | 2 +- .../docs/command-center/features/guardrails.mdx | 16 ++++++++-------- .../protect/concepts/understanding-protect.mdx | 8 ++++---- src/pages/docs/protect/index.mdx | 2 +- .../docs/protect/reference/guardrail-checks.mdx | 11 +++++------ .../guardrail-fires-on-the-wrong-requests.mdx | 2 +- 6 files changed, 20 insertions(+), 21 deletions(-) diff --git a/src/pages/docs/command-center/concepts/api-reference.mdx b/src/pages/docs/command-center/concepts/api-reference.mdx index 0bfa71bf3..ccc38d2ec 100644 --- a/src/pages/docs/command-center/concepts/api-reference.mdx +++ b/src/pages/docs/command-center/concepts/api-reference.mdx @@ -79,7 +79,7 @@ Agent Command Center returns standard HTTP error codes with structured JSON erro ### Guardrail blocked (403) -When a guardrail whose action is `block` triggers on a request, Agent Command Center returns 403. A pre-stage check returns it before the LLM is ever called; a post-stage check returns it instead of the model's response. A guardrail whose action is `warn` or `log` does not change the status: the call returns 200 with the header `x-agentcc-guardrail-triggered: true`. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can return 403 or add the header; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). +When a pre-stage guardrail whose action is `block` triggers, Agent Command Center returns 403 before the LLM is ever called. A post-stage guardrail checks the model's response, and today a `block` from it does not return 403. On a non-streamed response, a guardrail set up in the dashboard lets the response through with status 200 and the header `x-agentcc-guardrail-triggered: true`, and a synchronous `config.yaml` rule makes `/v1/chat/completions` return a 500 `internal_error` ("no response from provider") instead of the response. A guardrail whose action is `warn` or `log` does not change the status: the call returns 200 with the header `x-agentcc-guardrail-triggered: true`. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can return 403 or add the header; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). ```json { diff --git a/src/pages/docs/command-center/features/guardrails.mdx b/src/pages/docs/command-center/features/guardrails.mdx index 16502b3e2..46a21035f 100644 --- a/src/pages/docs/command-center/features/guardrails.mdx +++ b/src/pages/docs/command-center/features/guardrails.mdx @@ -25,26 +25,26 @@ When [caching](/docs/command-center/features/caching) is on and a request is ser ## Built-in Guardrail Types -Agent Command Center includes 16 guardrail types covering common safety scenarios. +Agent Command Center includes 16 guardrail types covering common safety scenarios. The Stage column is the stage each type runs at when you set it up in the dashboard; today the gateway uses it whatever stage the guardrail is set to. A rule in `config.yaml` runs at the `stage` the rule sets. | Guardrail Type | Stage | What it detects | |---|---|---| | PII Detection | Pre | Emails, SSNs, credit cards, phone numbers, addresses | | Prompt Injection | Pre | Attempts to override system prompts or extract instructions | -| Content Moderation | Pre/Post | Hate speech, threats, sexual content, violence | +| Content Moderation | Pre | Hate speech, threats, sexual content, violence | | Secret Detection | Pre | API keys, passwords, tokens, credentials | | Hallucination Detection | Post | Factually incorrect or fabricated information | | Topic Restriction | Pre | Blocks requests on restricted topics | | Language Detection | Pre | Enforces allowed languages | -| Data Leakage Prevention | Pre/Post | Prevents sensitive data from being processed | -| Blocklist | Pre/Post | Custom word/phrase blocklists | +| Data Leakage Prevention | Post | Prevents sensitive data from being processed | +| Blocklist | Pre | Custom word/phrase blocklists | | System Prompt Protection | Pre | Prevents system prompt extraction attempts | | Tool Permissions | Pre | Validates tool/function call permissions | | Input Validation | Pre | Validates input format and structure | | MCP Security | Pre | Validates MCP protocol security | -| Custom Expression Rules | Pre/Post | Custom logic via expressions | -| Webhook (BYOG) | Pre/Post | Custom guardrails via webhook | -| Future AGI Evaluation | Post | Future AGI's proprietary evaluation models | +| Custom Expression Rules | Pre | Custom logic via expressions | +| Webhook (BYOG) | Pre | Custom guardrails via webhook | +| Future AGI Evaluation | Pre | Future AGI's proprietary evaluation models | --- @@ -73,7 +73,7 @@ Choose how Agent Command Center handles guardrail violations. | Mode | HTTP Status | Behavior | |---|---|---| -| Enforce | 403 | Request blocked, error returned to client | +| Enforce | 403 (pre-stage checks) | Request blocked, error returned to client. A block from a post-stage check does not return 403 today; see [Guardrail blocked (403)](/docs/command-center/concepts/api-reference#guardrail-blocked-403) | | Monitor | 200 | Request proceeds, warning logged | | Log | 200 | Request proceeds, violation logged silently | diff --git a/src/pages/docs/protect/concepts/understanding-protect.mdx b/src/pages/docs/protect/concepts/understanding-protect.mdx index e7da40b50..d5655ae49 100644 --- a/src/pages/docs/protect/concepts/understanding-protect.mdx +++ b/src/pages/docs/protect/concepts/understanding-protect.mdx @@ -7,20 +7,20 @@ description: "Protect screens your traffic for safety issues through guardrails A **guardrail** wraps a check and adds three settings you configure in [Agent Command Center](/docs/command-center/features/guardrails), under **Gateway** > **Guardrails**: -- An **action** for when it triggers: Block, Warn, or Log (masking PII is the PII check's own remediation setting, not an action) +- An **action** for when it triggers: Block, Warn, Mask, or Log - A **stage** for when it runs: **pre** runs before the model sees the request, **post** runs before the response reaches the caller (on a streamed response, after it has been sent; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails)), and **both** runs on each side - A **confidence threshold** for how sure the check has to be before it fires -A stage of **both** isn't a third mode. It's the same check running twice, once on the way in and once on the way out. Stage belongs to the guardrail rather than to the check it wraps, which is why a single **gateway**, the Agent Command Center surface your guardrails live on, can carry a mix: some watching only what the caller sent, others only what the model sent back. +A stage of **both** isn't a third mode. It asks for the same check to run twice, once on the way in and once on the way out. As a setting, stage belongs to the guardrail rather than to the check it wraps, which is why a single **gateway**, the Agent Command Center surface your guardrails live on, can carry a mix: some watching only what the caller sent, others only what the model sent back. Today the gateway doesn't apply the setting: it runs each check at its built-in stage, so Data Leakage Prevention and Hallucination Detection check the response, and the others check the request. -The threshold runs from 0.0 to 1.0: raising it makes the check fire only on higher-confidence matches, lowering it makes it fire more readily. Threshold and action are independent settings. The threshold decides how often a check fires; the action decides what the caller experiences when it does. Loosening a threshold on a check set to Log changes nothing a caller can see. Only Block changes the gateway's response status, to `403`; Warn and Log let the call return `200`. For the status each action produces, see [Guardrail checks](/docs/protect/reference/guardrail-checks#response-statuses). +The threshold runs from 0.0 to 1.0: raising it makes the check fire only on higher-confidence matches, lowering it makes it fire more readily. Threshold and action are independent settings. The threshold decides how often a check fires; the action decides what the caller experiences when it does. Loosening a threshold on a check set to Log changes only whether the call carries the `x-agentcc-guardrail-triggered` header. Today only a Block from a pre-stage check changes the gateway's response status, to `403`; a Block from a post-stage check, Warn, and Log let the call return `200`. For the status each action produces, see [Guardrail checks](/docs/protect/reference/guardrail-checks#response-statuses). Every guardrail wraps a check, and the Rules tab groups checks under two headers that mark a single split: where the check runs. **Rule-Based Checks** are [first-party](/docs/protect/reference/guardrail-checks): they run inside Protect without an external provider. **AI-Powered Checks** call a provider you configure under **Provider Settings** in that check's own settings. A["Action: Block, Warn, or Log"] + G["Guardrail"] --> A["Action: Block, Warn, Mask, or Log"] G --> S["Stage: pre, post, or both"] G --> T["Confidence threshold"] G --> C["Check"] diff --git a/src/pages/docs/protect/index.mdx b/src/pages/docs/protect/index.mdx index 1243a70a6..d9c9193fc 100644 --- a/src/pages/docs/protect/index.mdx +++ b/src/pages/docs/protect/index.mdx @@ -5,7 +5,7 @@ description: "Where Protect's dashboard guardrails and SDK checks live" ## What is Protect? -**Protect** is the safety layer over your AI traffic. It runs named guardrail checks, like PII detection or prompt injection, on each request and returns one of three actions: [block, warn, or log](/docs/protect/concepts/understanding-protect). +**Protect** is the safety layer over your AI traffic. It runs named guardrail checks, like PII detection or prompt injection, on each request and returns one of four actions: [block, warn, mask, or log](/docs/protect/concepts/understanding-protect). You turn guardrails on in the dashboard under Gateway → Guardrails, where they apply to traffic passing through a gateway. If your app isn't pointed at [Agent Command Center](/docs/command-center) yet, see the [quickstart](/docs/command-center/quickstart) for swapping in the base URL and API key. You can also call `protect()` directly from your code to run checks inline on text, image, and audio inputs. Use the dashboard if traffic goes through a gateway; call `protect()` directly if it doesn't. diff --git a/src/pages/docs/protect/reference/guardrail-checks.mdx b/src/pages/docs/protect/reference/guardrail-checks.mdx index 45641b2a0..41054867a 100644 --- a/src/pages/docs/protect/reference/guardrail-checks.mdx +++ b/src/pages/docs/protect/reference/guardrail-checks.mdx @@ -87,19 +87,17 @@ A `topic-restriction` check groups its topics under 8 categories, most with thei Most fields below apply to every check in both the [first-party](#first-party-checks) and [provider-backed](#provider-backed-checks) tables above. A check that carries provider fields additionally has a Provider Settings section holding them, which is why `keyword-blocklist` shows its Blocked Keywords there despite being first-party. Confidence Threshold appears on every check except `futureagi-eval` and `presidio-pii`. -A check is configured from one of two dialogs: the per-check dialog covered under [Rules dialog](#rules-dialog), and the guardrail-level dialog covered under [Overview dialog](#overview-dialog). The two expose different fields: the Rules dialog has a Confidence Threshold; the Overview dialog sets Stage. +A check is configured from one of two dialogs: the per-check dialog covered under [Rules dialog](#rules-dialog), and the guardrail-level dialog covered under [Overview dialog](#overview-dialog). The two expose different fields: the Rules dialog offers Mask as an action option, plus a Confidence Threshold; the Overview dialog sets Stage. ### Rules dialog | Field | Values | Default | |---|---|---| | Enabled | Toggle | On | -| Action | Block, Warn, Log | Block | +| Action | Block, Warn, Mask, Log | Block | | Confidence Threshold | Slider from 0.0 to 1.0, marked at 0.0 / 0.5 / 1.0 | 0.8 | | Provider Settings (checks that have provider fields) | The check's provider configuration | | -A check saved with the Mask action, which older dashboards offered, runs as Log. To mask PII, set the PII check's remediation instead. - ### Overview dialog | Field | Values | Default | @@ -120,11 +118,12 @@ These apply to every check on the gateway rather than to an individual check. ## Response statuses -These are the statuses the [Agent Command Center](/docs/command-center) gateway returns on a guardrail decision. Only the Block action changes the status; Warn and Log let the call through. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can change them; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). +These are the statuses the [Agent Command Center](/docs/command-center) gateway returns on a guardrail decision. Today only a Block from a pre-stage check changes the status; a Block from a post-stage check, Warn, and Log let the call through. On a streamed response the status and headers are sent when the stream starts, so only a pre-stage check can change them; see [Streaming Guardrails](/docs/command-center/features/guardrails#streaming-guardrails). | Action | Status | What the caller gets | |---|---|---| -| Block | `403` | An error body with `"type": "guardrail_error"` and `"code": "content_blocked"`. A pre-stage check returns it before the model is ever called | +| Block, pre-stage check | `403` | An error body with `"type": "guardrail_error"` and `"code": "content_blocked"`, returned before the model is ever called | +| Block, post-stage check | `200` | The normal response, plus the header `x-agentcc-guardrail-triggered: true`. Only `data-leakage-prevention` and `hallucination-detection` run post-stage, whatever Stage is set to | | Warn | `200` | The normal response, plus the header `x-agentcc-guardrail-triggered: true` | | Log | `200` | The normal response, plus the header `x-agentcc-guardrail-triggered: true` | diff --git a/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx b/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx index dc8c29370..885c96d7b 100644 --- a/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx +++ b/src/pages/docs/protect/troubleshooting/guardrail-fires-on-the-wrong-requests.mdx @@ -22,7 +22,7 @@ Switch **Action** from Block to Warn or Log before you touch the Confidence Thre - **Warn** lets the request through, and counts toward that check's Warn total in Top Triggered Rules - **Log** lets the request through too, and still counts toward Triggers, but the check's Block and Warn totals stay flat, for a quieter pass while you compare several changes -Older dashboards also offer **Mask**, which runs as Log. Set **Action** back to Block once you're satisfied with where the threshold lands. +**Mask** is also on the select, but it's a different use case outside this tuning flow. Set **Action** back to Block once you're satisfied with where the threshold lands. ## Move its Confidence Threshold