AI Guardrails

AI Guardrails apply a policy to each agent. The policy chooses which detection categories run and what happens when one of them finds something. Each agent's policy runs in one of two modes:

• Real-time Enforcement: your application checks every prompt before it reaches the model and every response before it reaches your code. A call can be logged and allowed, allowed with a warning, blocked, or redacted.
• Scheduled Detection: ANTS scans the agent's stored traces on a schedule and records what it finds. Nothing is blocked. Results appear in AI Violations.

An agent's policy uses one mode at a time. Switching modes in the policy form resets the settings specific to the other mode.

Detection categories

Each category has a set of labels you can select. Every category starts off. When you turn a category on, all of its labels are selected, and you can then clear the ones you do not need.

The PII and PCI categories can also check card numbers and social security numbers with rules. See Card number and SSN checks.

Secrets & Credentials, Source Code and the card number and SSN rules are rule-based: they run inside ANTS, need no detection service, and keep working when the detection services are down. See Rule-based detectors when a service fails.

Pre-built detectors

ANTS ships 80 distinct pre-built detectors:

For formats specific to your organization, such as your own key prefix or order numbers, add a custom detector.

Secrets & Credentials

Secrets & Credentials finds credentials in prompts and responses. Under Detection Categories, expand Secrets & Credentials and select the families you need. The category is off until you select at least one family.

Each rule checks more than the shape of the value, to keep false alarms down. For example, a JWT must decode to JSON, and secret keys and password values must be random enough. Documented examples and placeholders are ignored: the example access key ID AKIAIOSFODNN7EXAMPLE and its example secret key from the AWS documentation, the jwt.io sample token, values that contain example or a run of x characters, and, for passwords and database URLs, placeholders such as changeme or <password>. A password assignment whose value is a variable reference, a file path or a function call is not reported.

Secrets & Credentials supports all four actions: Audit Only, Warn, Redact and Block. Redact masks only the secret value: the password in a connection string or a password assignment, the key after AccountKey= or SharedAccessKey=, the whole token for prefixed keys such as GitHub or OpenAI keys, and the whole PEM block for a private key. The text around it is kept.

A Secrets & Credentials match is sent to policy violation webhooks and SIEM push whatever its action. See Alerts from rule-based detectors.

Source Code

Source Code flags code pasted into prompts or returned by the model. It is a heuristic classifier with no model. It splits the text into blocks at blank lines and code fences, and counts a block as code from the shape of its lines (for example lines that end in ;, { or }, or start with keywords such as def, import, function or SELECT) and its density of symbols. Prose, JSON and other data, and fences tagged json, yaml, csv, markdown, xml, html, log or text, are not counted as code.

Under Detection Categories, expand Source Code and select the languages to flag: Python, JavaScript / TypeScript, Java / Kotlin, C#, C / C++, Go, Rust, Ruby, PHP, SQL, Shell and Other code. The category is off until you select at least one language.

The language comes from the code fence tag when there is one, otherwise from the code itself. When no language clearly wins, the block is labelled Other code, so select Other code as well to flag code whatever its language. Labels are reported as sourceCode.python, sourceCode.javascript, sourceCode.other and so on.

Source Code offers Audit Only, Warn and Block. It has no Redact, because a code block cannot be masked in a useful way. Under a policy whose single action is Redact, Source Code findings block the call.

Limits:

• A block must have at least 3 non-empty lines and 80 characters, or be a fenced block with at least 2 code lines. Short snippets, and a single line of code inside prose, are not flagged.
• Text that mixes prose and code is classified block by block, so a code block inside an explanation is found, but code without blank lines or fences around it may be judged together with the prose and missed.
• Pseudo-code and configuration files with code-like syntax can be flagged.
• At most 50 code blocks are reported per text. A text with more is marked as not fully scanned.

Start with Warn or Audit Only, review the results in AI Violations, then switch to Block.

Card number and SSN checks

The switch Check card numbers and SSNs with rules, below the detection categories in the policy form, adds rule-based checks to the PII and PCI categories in Real-time Enforcement. It is on for new policies. Policies that existed before the switch was introduced have it off, and keep their earlier behavior, until someone turns it on and saves the policy. In the current release the policy edit page opens only for Owner.

When the switch is on:

• Card numbers found by the models are kept only when they have 13 to 19 digits and pass the Luhn checksum. The card network is not checked for these, so cards from any network the models find are kept. Order numbers, tracking numbers and other long IDs that fail the checksum are dropped.
• Social security numbers found by the models are kept only when they follow Social Security Administration rules: the area is not 000, 666 or 900 to 999, the group is not 00, the serial is not 0000, and the number is not one that was never issued, such as 123-45-6789, 078-05-1120 or 219-09-9999, or one digit repeated. ITINs (area 900 to 999 with an ITIN group) found by the models are kept.
• A card number rule runs when the PCI category has credit card number selected, and an SSN rule runs when the PII category has social security number selected. They also find values the models missed. Their findings follow the PCI or PII action.

The card number rule accepts 13 to 19 digits, unbroken or grouped with single spaces or with dashes, that pass the Luhn checksum and match the prefix and length of a known network: Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, Mir, RuPay, Elo, Verve or Maestro. A card next to a CVV, an expiry date or another number is still found. The rule does not find card numbers that mix separators, such as 4539-5787 6362-1486, that use dots, or that sit inside a longer run of digits. Matches are labelled pci.card_number.

Known test card numbers, such as 4111 1111 1111 1111 and 4242 4242 4242 4242, are labelled pci.test_pan with a lower confidence score, so you can tell them apart from real cards. They follow the PCI action like any card.

The SSN rule always accepts ###-##-####. It accepts ### ## ####, ###.##.#### and 9 digits in a row only when a word such as SSN, social security, SS# or taxpayer id comes shortly before the number. It applies the Social Security Administration rules above and does not report ITINs. Matches are labelled pii.us_ssn.

The switch does not change Scheduled Detection: there, card numbers and social security numbers are reported as the models find them, without these checks.

Real-time Enforcement covers a narrower set of entity labels than Scheduled Detection. In real time, ANTS matches: person names, email, phone number, social security number, date of birth, address, driver license and passport numbers; card numbers, CVV, bank account and routing numbers; and medical record numbers, health insurance IDs, diagnoses, medications, medical procedures, hospital names and doctor names. Your other selected labels, such as IBAN, SWIFT code, lab result, symptom and allergy, are applied only by Scheduled Detection. Custom detectors run in both modes.

Real-time Enforcement

Real-time Enforcement applies the agent's policy wherever ANTS checks a call inline:

Actions

Under Action when violations are detected, choose one action for the whole policy, or set an action for each detection category.

By default one action applies to every category:

Redaction changes only the text that contained the detected values. Everything else in the request is sent unchanged: with the wrapped clients, the system prompt and the earlier turns of the conversation reach the model exactly as your application sent them.

Custom detectors carry their own action. See Custom detector actions.

Actions per category

Turn on Set action per category to choose a different action for each detection category. For example, block card numbers, redact email addresses, warn on jailbreak attempts and only log person names.

You can set an action for PII, PCI, PHI, Ethics & Bias, Safety, Secrets & Credentials and Source Code. Redact is offered for the categories that detect values: PII, PCI, PHI and Secrets & Credentials. Ethics & Bias, Safety and Source Code flag text as a whole, so they offer Audit Only, Warn and Block. Custom detectors keep the action set on each detector. A policy whose per-category actions were saved before Secrets & Credentials and Source Code existed uses its single action for those two categories until you set them.

When one check finds violations in categories with different actions, the strictest action applies, in the order Block, Redact, Warn, Audit Only. Only the values found by Redact categories are masked; values found by Warn or Audit Only categories are passed on as they are. The result also lists the built-in categories that warned, even when a stricter action decided the result.

The single action is the default: a policy without Set action per category applies its one action to every category, and behaves exactly as before. When you turn the setting on, each category starts from your current single action.

Warned and Audit Only violations are recorded in AI Violations, with the result Warning for warned checks. For the built-in categories, only blocked checks are sent as SIEM push alerts and policy violation webhooks. Custom detector and Secrets & Credentials matches are sent whatever their action. See Alerts from custom detectors and Alerts from rule-based detectors.

Who receives the Warning result

A check that warns returns WARNING only to callers that ask for it:

• The ANTS Python SDK 3.7.0 and later.
• REST API callers that send "acceptsWarning": true.

Other callers, including the Java and JavaScript SDKs and the Python SDK before 3.7.0, receive PASS for a warned check. The warning is still recorded in AI Violations with the result Warning.

Warn does not ask the user for a reason before continuing. Warn with user justification is on the roadmap.

Blocked Response Message

When a policy can block, set a Blocked Response Message. It is returned to the caller whenever a call is blocked. The default is "Guardrail violation detected. Try again with a different prompt."

What is checked

Real-time Enforcement checks the text of prompts and responses. The contents of uploaded files are not inspected; file content inspection is on the roadmap.

Checks that find a violation are recorded and appear in AI Violations, with source SDK for the Python SDK and the REST API, and Connector for the Portkey connector and the Budget AI gateway. Saving a policy refreshes the cached copy, so the next check uses the new settings.

The detection record never stores a matched secret: secret values are masked in the stored text, and rule-based findings are stored with their label and position only.

Set up Real-time Enforcement

Python SDK

Wrapped clients

The ants-platform Python SDK includes drop-in wrappers for common model clients. Each wrapper checks the input before the model call and the output after it. A BLOCKED result raises GuardrailViolationError. A SANITIZED result replaces only the content of the checked message with the masked version before it is sent to the model or returned to you; the system prompt and the other messages are left as they are. A WARNING result does not raise, and the call proceeds with the request and response unchanged.

str(err) is the Blocked Response Message when one is set. err.direction is "input" or "output".

To show a warning to the user, pass on_guardrail_warning to the wrapper (Python SDK 3.7.0 and later). It is called with the direction and the result whenever a check lets the call continue with warned categories: a WARNING result, or a SANITIZED result where a Warn category fired as well. It runs before the model call for input and before the response is returned for output. It is not called for checks that pass with no warning or are blocked.

The handler must be a regular function, not async. If it raises, the error is logged to the ants_platform.guardrails logger and the call continues as if the handler had returned.

The wrappers check complete responses. Streamed responses are not checked on output, so for streamed calls only input warnings are reported.

All wrappers take ants_api_key, agent_id, agent_name and an optional ants_base_url for your ANTS URL. In Python 3.7.0 and later they also check the tool calls in each model response against the agent's tool permissions and raise ToolNotAllowedError for a blocked call; pass enforce_tools=False to turn this off. Calls that pass or are sanitized are also sent to ANTS as traces. Blocked calls do not create a trace; the guardrail record in AI Violations is the record of the block.

Calling the checks yourself

Use AntsGuardrailsClient when you want to control the flow. It returns a result and does not raise on its own.

Each result has result (PASS, WARNING, BLOCKED or SANITIZED), sanitized_text, risk_score, risk_level (LOW, MEDIUM, HIGH, CRITICAL), violations (scanner, details, action), warned_categories (the built-in categories that warned, empty otherwise), guardrail_action and blocked_message.

Tool calls

The SDKs also check an agent's tool calls against its tool permissions: in Python with guard_tool, framework guards for LangChain, CrewAI, OpenAI Agents and LangGraph, and an MCP session guard; in JS with guardTool, framework guards and an MCP client guard; in Java with AntsToolGuard. A tool call that breaks a rule is blocked when the agent's policy is Block or Redact, and recorded and allowed under Audit Only or with no policy. See Agent Tool Governance and the Python, JS/TS and Java SDK pages.

REST API

Any language can call the same check over HTTP with project API keys (HTTP Basic auth):

A request with longer text is refused with a validation error and nothing is checked.

The response contains result (PASS, WARNING, BLOCKED or SANITIZED), sanitizedText, riskScore, riskLevel, violations (with the detected entities), guardrailAction and, when the call is blocked, blockedMessage. When any built-in category warned, warnedCategories lists them (pii, pci, phi, ethicsBias, safety, secrets, sourceCode). With Set action per category on, categoryActions lists the action of each category, including secrets and sourceCode, and each violation's action is AUDIT_ONLY, WARN, REDACT or BLOCK. If your client parses these fields into a fixed list of category keys, make sure it accepts secrets and sourceCode. Custom detector matches are reported as a violation from the scanner custom-detector, with each entity's label set to the detector's Label on detections.

Rule-based findings are reported as violations from the scanners t0-secrets, t0-source-code, t0-pci (card number rule) and t0-pii (SSN rule). Each entity carries the rule's label, such as secrets.aws_access_key, and its position in the text (chunkStart, chunkEnd). Its text is always empty, so the API never returns the matched value.

Long text

A check through the SDK or the REST API accepts up to 1,000,000 characters of text.

• Text up to 50,000 characters is checked in one pass.
• Longer text is checked in overlapping windows of 50,000 characters, four at a time. The overlap means a value that crosses a window edge is still found.
• The results are merged into one: entity positions refer to the full text, each detected value is reported once, and AI Violations gets one record for the whole check.
• With Redact, the masks are laid over the full text. If ANTS cannot place them reliably, it never returns the text unmasked: text up to 100,000 characters is checked again in one pass, and if that is not possible the result is BLOCKED with a violation from the scanner redaction.
• The rule-based detectors (Secrets & Credentials, Source Code and the card number and SSN rules) are not split into windows. They scan the full text once, so a secret anywhere in the text is found whatever its position. See Rule-based detectors when a service fails for their limits.

A check stops after 25 seconds. Windows that have not finished by then count as failed. If a window that did finish found a value whose action is Block, the result is BLOCKED. Otherwise the check fails open and returns PASS, as described in When a detection service fails.

When a detection service fails

Circuit breakers

Each detection service has its own circuit breaker: PII, PCI, PHI, Ethics & Bias and Safety. By default, after 5 failures in a row from one service, ANTS stops calling that service for 60 seconds, then lets one check through to test whether it has recovered. If that check gets an answer, the service is used again. Your ANTS deployment can change the threshold and the pause.

Only real service failures count: no answer, a timeout, a server error, rate limiting, or an answer ANTS cannot read. A request the service rejects, a check your application cancelled and a check cut short by a time limit do not count. A category the policy does not use is not called and does not affect its breaker.

Because the breakers are separate, one failing service does not switch off the others. A policy that uses PII and Safety keeps getting Safety results while the PII service is down, and a policy that only uses Safety is not affected at all. Custom detectors and the rule-based detectors run inside ANTS and do not use these services.

Rule-based detectors when a service fails

Secrets & Credentials, Source Code and the card number and SSN rules run inside ANTS, before the detection services are called, in every Real-time Enforcement path: the SDK and REST API (including long text), the Portkey connector and the Budget AI gateway. They do not depend on the detection services, so their results apply even when a service is down, slow or paused by its breaker:

• A rule-based finding with Block still blocks the call.
• A rule-based finding with Redact still masks the value.
• Warn and Audit Only findings are still recorded.

Each check gives the rule-based detectors a small budget, because they run inline: by default 50 milliseconds and the first 1 MiB of text, and each rule stops after 1,000 matches. Your ANTS deployment can change the time and size limits. A scan that hits a limit, or a rule engine that cannot start, never returns partly masked text: every rule-based category whose action is Redact blocks the call instead, whether or not it found anything yet. Other actions apply to what was found.

What your callers see

With no policy for the agent, SDK and REST API checks return PASS and the Portkey hook passes.

Checks through the SDK, the REST API and the Portkey connector always fail open. A per-policy choice to fail closed is on the roadmap; the Budget AI gateway already offers it per project (Forward the request or Refuse the request).

If the guardrails API itself is unreachable or returns an HTTP error, the Python SDK raises the HTTP error before the model is called. Catch it in your code if you want a different behavior.

Scheduled Detection

Select the Scheduled Detection tab in the policy to scan stored traces instead of enforcing inline.

• Schedule Interval: Hourly, Daily (default) or Weekly. Each run scans the agent's traces received since the previous run, with the selected labels and the agent's custom detectors.
• Confidence Threshold: 0 to 100 percent. Higher values reduce false positives but may miss some detections.
• PagerDuty Alerting: send incidents for this agent's detections to a PagerDuty service, with a chosen severity (Critical, High, Low or Info). Requires the PagerDuty integration.

Detections are listed in AI Violations. Scheduled detections open incidents automatically when the ServiceNow integration has incident creation turned on, and in PagerDuty when the PagerDuty integration has incident creation turned on and the agent's PagerDuty Alerting is on. Real-time Enforcement records do not open incidents.

Scheduled Detection runs Secrets & Credentials and Source Code with the custom detectors, on the input and output of each new trace. They only report: nothing is blocked or changed, and their results are listed with source Scheduled and the result Pass. The card number and SSN checks are not applied in Scheduled Detection.

See PII Detection for the full Scheduled Detection setup.

Alerts from rule-based detectors

Secrets & Credentials and Source Code findings are sent to policy violation webhooks and SIEM push with the categories Secrets & Credentials and Source Code. The labels are rule labels such as secrets.aws_access_key or sourceCode.python, never the matched values.

Card number and SSN rule findings are part of the PCI and PII categories and are alerted like them, with labels such as pci.card_number and pii.us_ssn.

Webhooks with no category filter receive Secrets & Credentials and Source Code alerts once a policy turns those categories on. To keep a webhook off them, select its categories.

Custom detectors

Custom detectors find data that is specific to your organization, such as order numbers, customer IDs or internal project code names. Each detector is a regular expression or a keyword list, with its own action. Use them for formats the built-in categories do not know.

Detectors belong to a project. You create a detector once and switch it on in the policy of each agent that should use it. A project can have up to 50 detectors, and one agent's policy can use up to 50.

Who can manage them

Listing detectors needs the AI Guardrails permission at Read. Adding, editing, testing and deleting them needs Read & Write, which Owner and Security & Compliance have. Detectors are managed inside the guardrail form, which in the current release opens only for Owners. Every detector create, update and delete is written to the audit log.

Add a detector

Edits to a detector apply to every agent that uses it as soon as you save the detector. Deleting a detector removes it from every agent in the project.

Regular expression rules

Patterns use RE2 syntax, which runs in time proportional to the length of the text, so a pattern cannot stall a check. When you save or test a detector, ANTS refuses a pattern that:

Other points:

• ^ and $ match the start and end of the whole message, not of each line. ^ORD-\d+$ only matches when the entire message is that order number. To find a value inside a message, leave the anchors out: ORD-\d{6}.
• Matching is not case sensitive unless you turn on Case sensitive.
• Each detector reports at most 10,000 matches in one text. A Redact detector that reaches that limit blocks the text instead, so unmasked values never pass.

Keyword lists

Keywords match whole words and phrases. A keyword matches only when the characters on both sides of it are not letters, digits or underscores, so Zeus matches "Project Zeus launch" and "Zeus." but not "Zeusville". Special characters in a keyword are matched literally.

Custom detector actions

Each detector has its own action, set under When found:

When several detectors match, or a detector and a built-in category both find something, the strictest action applies, in the order Block, Redact, Warn, Audit Only. Only matches from Redact detectors (and values from Redact categories) are masked.

A detector's action applies whatever the policy's own action, with one exception: when the policy uses the single action Audit Only, a detector set to Block is recorded but does not stop the call. To let a custom detector block, set the policy's action to Block or Redact, or turn on Set action per category.

A detector set to Warn makes the result WARNING, but it is not listed in warnedCategories or warned_categories, which only name built-in categories.

Where custom detectors run

In Scheduled Detection, each run scans the input and output of the agent's new traces with the detectors switched on in its policy, on the policy's Schedule Interval. A new policy's first run covers the agent's existing traces; turning a detector on in an existing policy covers traces received since the policy's previous run, not older ones. A run scans up to 5,000 traces for custom detectors and continues from there on the next run. Matches are recorded as scheduled results: Block, Redact and Warn detectors are recorded with the result Warning, and Audit Only detectors with Pass, because nothing was blocked or changed.

Results in AI Violations

Checks and scheduled scans with custom detector matches are listed in AI Violations under the Custom filter. The Detections column shows each matching detector as Custom: <label>, using its Label on detections, and Detection Details lists the detectors that matched. Scheduled matches are listed with source Scheduled. The detection record does not store the matched values, so the list shows the detector, not what it matched.

Alerts from custom detectors

Custom detector matches are sent to policy violation webhooks and SIEM push with the category Custom, whatever the detector's action. The labels are the detectors' Label on detections values.

Webhooks with no category filter receive Custom alerts. To keep a webhook off them, select its categories.

Troubleshooting

• The detector never matches. Select Test with real sample text. Check anchors: ^ and $ apply to the whole message. Check Case sensitive. Check that the detector is switched on in this agent's policy and that the policy was saved.
• A Block detector does not block. The policy's single action is Audit Only. See Custom detector actions.
• Nothing is found while a detection service is down. When every detection service the policy uses is unavailable and no rule-based detector found anything, the check fails open and custom detectors are not applied either. See When a detection service fails.
• Saving is refused. The error names the rule; see Regular expression rules. "A project can have at most 50 custom detectors" means the project limit is reached; delete a detector you no longer use. "A custom detector with this name already exists" means the name is taken in this project.

Regular expressions and keyword lists are the two supported methods. Exact data match and document fingerprinting are on the roadmap.

Next steps

• AI Violations: review what the guardrails found.
• Policy Violation Webhooks and SIEM Push: send violations to your security tools.
• Drift Alerts: detection rates are compared with each agent's declared controls.
• Roles & Access: control who can change policies and see flagged content.