Common Expression Language (CEL)
The CEL rail checks a tool call’s arguments, or a tool result’s content, against Common Expression Language (CEL) expressions that you write per tool. CEL is a small, side-effect-free expression language used for policy rules in systems such as Kubernetes admission policies and Envoy. Each expression evaluates to true when the tool is being used in a way you want to block.
Unlike Regex Detection, which matches text patterns, CEL expressions address the structured fields of a tool call directly, so one rule can combine several arguments. Unlike Tool Safety Check, the check is deterministic and calls no model. It is scoped per tool through the same rails.tool_call.per_tool and rails.tool_result.per_tool dispatch mechanism as both.
Installation
The CEL rail requires the optional cel extra, which installs the common-expression-language package and is available on Python 3.11 and later:
If the extra is not installed, a configuration that uses the CEL rail fails to load with an error naming the extra.
Configure the Rail
To use the CEL rail, you should:
-
Write the expressions for each tool in the
rails.config.celsection of theconfig.ymlfile, undertool_callto check tool calls andtool_resultto check tool results: -
Scope the check to the tool in the
tool_callandtool_resultrails sections of theconfig.ymlfile:The
cel check tool callflow evaluates the tool’stool_callexpressions against each call to the tool, and thecel check tool resultflow evaluates itstool_resultexpressions against each result the tool returns. A tool without a CEL flow underper_toolis not checked by the rail, but a tool whose CEL flow has no expressions configured for its direction fails closed. -
Declare the tool in the main model’s
parameters.tools, or per request: inoptions.llm_params.toolswith the Python API, or in thetoolsfield of a chat completions request to the server, which the server currently accepts only for non-streaming requests on a configuration withpassthrough: true.cel check tool callblocks a call to an undeclared tool before any expression runs. Refer to Tool Calling for the full declaration reference.
The cel check tool call and cel check tool result rails execute the evaluate_tool_call_cel and evaluate_tool_result_cel actions respectively.
Expression Variables
Each expression can read the following variables:
Nested arguments are available at any depth, for example args.options.recursive or args.files.exists(f, f.path.startsWith("/etc")).
A tool result that contains JSON text is still a string, so check it with string functions such as contains() and matches().
How Expressions Are Evaluated
The rail evaluates every expression configured for the tool:
- If any expression evaluates to
true, the rail blocks the tool call or result. The block lists the expressions that matched in itsmatched_expressionsmetadata. The metadata never includes the checked arguments or content. - If no expression evaluates to
true, the rail allows the tool call or result. - If any expression fails to evaluate, for example because it reads an argument the call did not include, or it returns a value that is not a boolean, the rail fails closed, even if another expression matched. The tool call or result is blocked and reported as a rail failure rather than a policy decision, and the logged error lists each expression that failed with its error type.
- If the tool has no expressions configured for the direction its flow runs in, the rail also fails closed, since there is nothing to validate the tool call or result against.
Write Expressions
Expressions use CEL syntax, including comparisons, && and ||, the in operator, the exists() and all() macros, and string functions such as contains(), startsWith(), endsWith(), and matches(), which uses RE2 regular expression syntax. The rail also provides the cel-go extension functions, such as lowerAscii(), split(), and lists.range().
When you write expressions, keep the following in mind:
- Guard optional arguments with
has(), for examplehas(args.mode) && args.mode == "append". Without the guard, a call that omits the argument fails to evaluate. - If a tool can return either a string or a list of content blocks, check the type first, for example
type(result) == string && result.contains("password"). - Each expression must evaluate to a boolean. An expression such as
args.commandthat returns a string fails to evaluate.
The rail checks each expression’s syntax when the configuration loads, so a syntax error fails the load. Everything else is checked when an expression is evaluated: the CEL library the rail uses resolves variable and function names only at evaluation, and args and result hold the values of each tool call or result, so whether a field exists or has the expected type is known only then. A mistake found at evaluation makes the rail fail closed, so test your expressions against representative tool calls and results before deploying them.
Complete Example
The following configuration blocks recursive forced deletes in run_shell, writes to /etc or /root and appends to .bashrc through write_file, and any run_shell result that contains a private key:
The expressions on this page illustrate how the rail works; they are not complete security policies. Write and test expressions for the actual threats your tools face.
This configuration doesn’t declare run_shell or write_file. Declare them in the main model’s parameters.tools, or per request: in options.llm_params.tools with the Python API, or in the tools field of a chat completions request to the server, which the server currently accepts only for non-streaming requests on a configuration with passthrough: true. Otherwise cel check tool call blocks every call to them before any expression runs. Refer to Tool Calling for the declaration format.
Schema Validation
cel check tool call runs behind @tool_call_validation: a call to a tool the model has not declared, or whose arguments violate the tool’s declared JSON schema, is blocked before any expression is evaluated. cel check tool result has no such gate, matching regex detection’s asymmetry between the two directions.
Engine Support
Per-tool checks are an IORails-only capability by design. For the full per-rail matrix, refer to Rail Engine Support.