Guardrails and Policies
A policy is a pluggable unit of behavior that runs in the gateway's request or response pipeline. Policies handle cross-cutting concerns: authentication, rate limiting, header manipulation, content moderation, and LLM-specific controls such as prompt decoration, semantic caching, and guardrails. Several policies can be chained on the same resource.
Policies are built into the gateway image, not installed at runtime. Which policies a Gateway can offer is fixed when its image is built; what you choose in the console is which of those policies to apply, and with what settings.
Where Policies Come From​
Every policy originates in one of two places:
- Hub policies are published to the WSO2 API Platform Policy Hub and referenced by Go module path. These are the policies a stock gateway image ships with.
- Local policies are your own implementations, referenced by file path when the image is built. See Use a Custom Gateway Image.
Both kinds are compiled into the image by the same build. Once the gateway is running, nothing distinguishes them except where their source came from.
How Agent Manager Learns Which Policies Exist​
Agent Manager does not read the gateway image. It is told what the gateway has:
- The gateway controller connects to Agent Manager over its internal endpoint and authenticates with its registration token.
- It pushes a policy manifest: the set of policy definitions compiled into its image, with each policy's name, version, display name, description, and parameter schemas.
- Agent Manager caches that manifest and serves it back to the console.
The manifest is re-pushed on a heartbeat, so the cached copy reflects whatever the gateways are currently running. Because every gateway in a deployment normally runs the same policy bundle, the cache holds one copy shared across all of them rather than one per gateway.
A policy is offered only when every gateway in scope reports it. If gateways disagree on a policy's version, as happens during a rolling upgrade, the lowest reported version is used, so a policy already applied does not disappear mid-rollout.
The Three Configuration Layers​
Most confusion about policies comes from conflating these. A policy can be present at one layer and absent at the next, and each layer fails differently.
| Layer | Set where | Scope | Failure when missing |
|---|---|---|---|
| Build time | build.yaml, compiled into the image | The image | Policy never appears anywhere |
| System parameters | Helm values on the gateway extension release | Whole deployment | Policy appears but fails at request time |
| Policy parameters | Console, when you apply the policy | One resource | Policy is rejected when you try to apply it |
Build time decides which policies exist at all.
System parameters are the deployment-wide settings a policy needs to reach an external service, such as an endpoint, a region, or an API key. They are shared by every use of that policy and are supplied as Helm values, never through the console. A policy whose system parameters are missing is still offered in the console and still applies cleanly; it fails when a request reaches it. See Configure Guardrail System Parameters.
Policy parameters are the per-use settings you fill in when applying a policy to an LLM Service Provider or MCP Proxy, such as the regex to match, the token ceiling, or the categories to block.
Policies that need no external service, such as the regex and word-count guardrails, have no system parameters at all. They work as soon as the image contains them.
Visibility in the Console​
What the console offers is narrower than what the gateways report, and the two pickers narrow it differently.
The LLM guardrail picker treats the gateway-reported list as authoritative. It consults the Policy Hub only to borrow friendly display names for built-in policies, and a Hub failure never blocks the list. A custom policy appears here as soon as your gateways report it.
The MCP policy picker intersects the gateway-reported list with the public Policy Hub catalog. A policy that is not published to the Hub is filtered out even when every gateway reports it, so custom MCP policies do not appear.
Separately, guardrails that depend on an external service are hidden behind capability flags on the Agent Manager release, so an operator who has not configured the backing service does not see a policy that cannot yet work. These flags only filter the console list; they do not stop the policy being applied through the API.
Relationship to Other Concepts​
- Gateway: the component policies run in. A gateway's policy set is fixed by its image.
- LLM Service Provider and MCP Proxy: the resources policies are applied to.