docs / concepts
Guardrails
A guardrail is a policy check the runtime enforces outside the model. The model can be persuaded; the runtime cannot. This page explains what checks exist, where they execute, what they cost, and the two failure modes you must choose deliberately.
The mental model
Prompt instructions are requests. An agent told "never touch rate tables" will comply right up until a cleverly phrased ticket, a long context window, or an unlucky sample convinces it otherwise. Guardrails move the rule out of the conversation and into the runtime: the tool call that violates policy is rejected before execution, and the rejection is a span in the trace like anything else.
Guardrails are seatbelts, not self-driving. They bound the blast radius of a bad decision; they do not make a badly designed agent good. Evals do that — slowly, with data.
Boundaries and check types
Checks attach at four boundaries, and come in two families with very different costs:
- Structural checks — JSON Schema validation on tool arguments, tool and field allowlists, budget caps on tokens/spend/wall-clock. Deterministic, always on, free, effectively zero latency.
- Classifier screens — PII, prompt injection, off-policy content. These run on our hosted screening model at $0.08 per 1,000 checks, ~40 ms p95, executed in parallel with the step wherever the verdict isn't needed to proceed.
Observe → dry-run → enforce
Every policy has a mode, and the safe rollout path uses all three in order:
- observe — checks run and log verdicts; nothing is blocked. Use it to measure a policy against live traffic.
- dry-run — like observe, but verdicts surface in the would-have-blocked report and alerting, so reviewers rehearse the real workflow.
- enforce — blocks execute, the on_block branch runs, and every block is recorded (and, if you configure it, auto-added to an eval set).
A production-shaped policy, in enforce, with the rollout affordances visible:
Latency and cost budget
Strict screening (pre and post every model call) on a 6-call support run adds 12 checks: about $0.00096 per run and, because screens run concurrently with the step, typically under 100 ms of critical-path latency per run. The configurator prices the levels against your volumes — on economy fleets, strict guardrails often cost more than the model itself. That is not a bug in the math; it is what buying safety for cheap inference looks like.
Fail-open vs fail-closed
If the screening service itself is degraded, what should your run do? There is no right answer, only a choice you must make per policy:
- fail-closed (default for write paths) — the step blocks until the check can run or the run escalates. Correct when a bad write is worse than a slow answer.
- fail-open — the step proceeds, unscreened, and the trace flags it. Correct for read-only or latency-critical paths where a delayed answer is the real harm.
Trellis makes you set on_check_unavailable explicitly on every enforced policy. Defaults chosen for you are incidents waiting for a postmortem.
What guardrails can't do
- They can't verify truth. A screen catches PII and injection patterns; it cannot tell a correct refund from a plausible-sounding wrong one. That's eval territory.
- Classifier screens have error rates. Ours are published per screen in the console; treat "screened" as risk reduction, not certification.
- They can't fix ambiguous tool design. If one endpoint both reads and writes, no allowlist can separate the two — split the tool.
Next: grow the eval suites that catch what guardrails can't — eval-driven agent development.