Policy configuration overview
Policies are the rules that the gateway applies to model traffic. A policy can block an attempt to override the system prompt, replace a personal identifier before the model sees it, or send a response to a person for review.
In these docs and in the Console, a policy is the runtime AI policy that a configuration enforces on model traffic. Three other kinds of rules have their own names: permission policies (IAM) control who can do which action, model access rules control which models and gateways an API token can use, and budgets limit spend. See Which "policy" is which.
You choose policies and their settings in a policy config, the policy-config.yaml file that the gateway loads. Add one rule, test it, then add the next.
Run your first policy test
- Open Prompt injection detection.
- Copy its configuration and its two test cases into
policy-config.yaml. - Run
verdictan policy lint --file policy-config.yaml. - Run
verdictan policy test --json. The attack example must be blocked and the usual question allowed. - Apply the tested file to a test agent with the config-first workflow.
The offline test does not call a model. A live request then proves that the gateway, the provider, and the policy work together.
What a policy config contains
Only pack and policies are required. Add other sections when you need them.
| Section | Required | Use |
|---|---|---|
pack | Yes | Name, version, and the enabled switch of the document |
policies.chain | Yes | The ordered list of controls that the gateway runs |
policy.<kind> | No | Settings for one control in the chain |
providers | No | Provider targets, routing, fallback, and data policies |
routes, consumer_groups | No | Path rules and client groups with their own chains and limits |
token_rate_limit, global_rate_limit, ip_rate_limit, user_rate_limit, size_limits | No | Rate and size limits |
cache, callbacks, history, testing | No | Caching, observability sinks, capture, and tests |
Lint rejects a top-level key that the schema does not define. The Declarative config reference lists every section.
Chain and control
- The policy chain is the ordered list in
policies.chain. - A policy control is one entry in the chain, such as
pii-detector. Its settings go inpolicy.<kind>.
An entry is either the name of a control, or an object with the name as its only key. The object form adds when, stage, parallel, and targeting:
policies:
chain:
- audit-logger
- pii-detector:
when:
path: /v1/chat/completions
stage: pre-requestConditional chain configuration describes when and the stages.
Phases and verdicts
Controls run in one of two phases:
- The input phase (
stage: pre-request) runs before the provider call. A control examines the request. - The output phase (
stage: pre-response) runs on the complete provider response, before your application receives it.
Each control has a default phase. For example, prompt-injection runs on input and quality-scorer runs on output. The Policy controls catalog lists the phase of each control.
Each control returns a verdict and a reason code:
| Verdict | Next control | Result |
|---|---|---|
allow | Runs | The gateway forwards the request or response. |
redact | Runs | The gateway applies the supported replacements, then forwards. Some controls only report this verdict. Read the page of the control. |
block | Does not run | The gateway returns a blocked result and the reason code. |
escalate | Does not run | The gateway returns an escalated result and opens an escalation. |
If one control in a phase returns block or escalate, that is the verdict of the phase. Otherwise, a redaction sets the verdict to redact. Examine the replacement details to see which text changed.
Ordering rules
- In one phase, controls run in the order of
policies.chain. - After a control returns
blockorescalate, the other controls of that phase do not run. audit-loggeralways returnsallow. Put it before blocking controls if every evaluated request must have the audit marker.language-validatorsupportsapply_to: input,output, orboth. Output language checks hold streamed output until it can be checked. Set the field explicitly; see Language validator.pack.enabled: falseturns off the whole document. The gateway registers no chain, routes, or providers from it.
Find a control
Type a name to filter the list of controls. The Policy controls catalog gives the phase, the request families, and a minimal configuration of each control.
Configure other parts
| Task | Page |
|---|---|
| Define provider targets, routing, and fallback | Provider configuration |
| Send traffic only to approved zero-retention targets | Zero-retention routing |
| Give paths and client groups their own rules | Routes and consumer groups |
| Limit request rate and size | Rate limit configuration |
| Send a review to a person | Escalation routing configuration |
| Validate a file from the command line | verdictan policy lint |
Related guides
- Write and test your first policy configuration: a short guide to this task, with the decisions and limits in one place.