Checking Messages Against Rails
The check_async() and check() methods validate messages against input and output rails without triggering full LLM generation. Use these methods instead of generation options when you only need to run rails without generating a response. If you need to run generation while selectively disabling rail categories, see Generation Options: Disabling Rails.
Both the LLMRails and IORails engines implement these methods.
The Guardrails facade forwards each call to the selected engine.
Both engines take messages and rail_types and return a RailsResult.
IORails also runs tool-call and tool-result rails in a check, and takes a tools argument for them.
For more information, refer to Tool Rails (IORails Only).
For engine-specific rail selection and execution behavior, refer to Engine Differences.
Method Signatures
Both methods accept the same parameters and return a RailsResult object.
check_async()
The primary asynchronous method for checking messages against rails.
check()
Synchronous wrapper around check_async().
Parameters:
Returns: RailsResult object containing validation results.
Calling the synchronous check() from inside a running event loop raises RuntimeError on both engines. Use await check_async(...) in async code.
Rail Type Selection
The methods determine which rails to execute based on the message roles or an explicit rail_types parameter.
Automatic Detection (Default)
When rail_types is not provided, the methods automatically determine which rails to run based on the message roles:
The methods ignore other message roles such as system, context, tool when determining which rails to run but still include them in the validation context.
Explicit Rail Types
You can override automatic detection by passing a list of RailType values:
On either engine, passing an empty list (rail_types=[]) runs no rails and returns a passed result.
Requesting a rail type that has no configured flows raises
RailTypeNotConfiguredError (HTTP 422 on the /v1/checks endpoint). For
example, passing rail_types=[RailType.OUTPUT] on a config that only defines
input flows will raise an error instead of silently returning a passed result.
Tool Rails (IORails Only)
IORails runs tool rails in a check when you name their rail types in rail_types.
This lets an agent harness validate the tool calls its model produced, and the tool results it is about to send back, without generating a response.
A tool check runs the rails that generation runs for the same direction: the global validator (tool call validation or tool result validation) and any per_tool rails.
The global validator enforces the declared-tool allowlist and argument schemas for every call.
A per_tool rail on tool calls enforces them too, but only for the calls it checks, before its own check runs.
A per_tool rail checks only the tools it is listed under, so with per_tool rails alone, a call to any other tool, declared or not, passes.
A tool check never calls the main model.
Pass the tools your model was offered in tools, in the OpenAI Chat Completions tool shape, whatever the main model’s engine:
Keep the following behavior in mind:
- Tool rails run only when you name them.
When
rail_typesis omitted, a check runs input and output rails as described in Automatic Detection. It logs an INFO message when the configuration has tool rails and the messages carry tool calls or tool results. toolsreplaces the tools declared in the main model’sparameters.tools, schemas included; it does not add to them. When you omittools, the configured tools are the allowlist.tools=[]declares no tools, sotool call validationblocks every call.- A
toolsentry that is not a Chat Completions function tool, with afunctionobject and a non-emptyname, raisesInvalidCheckRequestErrorrather than being dropped. - Only a
tool_callcheck readstools. Passingtoolsto any other check, including one that leavesrail_typesto automatic detection, raisesInvalidCheckRequestErrorrather than ignoring them. - A
tool_callcheck validates only the last assistant message. Earlier calls were validated when they were produced, and atool_resultcheck validates how results link to them. - A tool check needs no
mainmodel. It reads the messages andtoolsin the Chat Completions format, whatever the main model’s engine. - A tool rail type counts as configured when its configuration section lists
flowsorper_toolrails:rails.tool_callfortool_call, andrails.tool_resultfortool_result. Otherwise the check raisesRailTypeNotConfiguredError. - When you name several rail types, they run in the order generation runs them:
tool_result,input,tool_call, thenoutput. The check stops at the first block. - Tool checks fail closed.
A call whose arguments are not a JSON object blocks, and so does a legacy
function_callon the last assistant message. The other calls on that message are still validated, sotool_violationslists every failing call in call order, not only the one that could not be parsed. - Legacy
role: "function"messages are not validated by the tool-result rails, in checks or in generation. LLMRailsdoes not run tool rails in a check. Requesting a tool rail type, or passingtools, raisesRailTypeNotSupportedErrorrather than ignoring the request.
For configuration and the validation rules, refer to Tool Calling.
RailsResult
The RailsResult object contains the outcome of the rails check.
RailStatus Enum
The RailStatus enum represents the three possible outcomes of a rails check.
Tool Violations
When a tool rail blocks, tool_violations lists each tool call or tool result that failed, so an agent harness can drop, repair, or re-request that item.
The global validators check every item, so one check can report several violations, and reason repeats the first one’s reason.
When a tool rail fails rather than deciding, the check returns the internal-error message, and reason is that rail’s failure even when an earlier item has its own violation.
Each tool call or tool result reports at most one violation: the first check it fails.
Switch on violation_type, which is a closed set, and never on the reason text, which can change between releases.
An argument_path names only what the schema declares: property names from its properties, and array indices.
For a missing required property, it names that property from the schema.
A key the model chose appears as *, for example a key inside a map-shaped argument such as /contacts/*.
An unexpected property rejected by additionalProperties: false is reported at the object that holds it, without its name.
So neither argument_path nor reason contains an argument value or a key the model wrote.
For the same reason, unexpected_arguments reports how many arguments the call supplied, not their names.
Which Content Is Reported
The content field reports the direction the caller asked about.
A check that runs output rails reports the assistant text.
A check that runs input rails only reports the user text.
A tool_call check reports the assistant text, unless input rails run in the same check, in which case it reports the user text so that an input rewrite stays visible.
A tool_result check reports the user text.
Both engines compare the reported text against its original value to decide between PASSED and MODIFIED.
For content lists on LLMRails, the comparison uses generation’s existing Python string representation of the list.
An unchanged list returns PASSED; the result’s content remains a string, including through /v1/checks.
This preserves the response contract and does not provide structured multimodal round-tripping or add image inspection to text-only rails.
When a check runs both directions and only the user message is rewritten, the status is PASSED, because the reported assistant text is unchanged.
MODIFIED names no rail: a rewrite is not a rail blocking the request, and several rails can contribute to the final text.
Tool rails never rewrite, so a check that runs only tool rails is PASSED or BLOCKED.
Usage Examples
The following examples demonstrate common patterns for validating messages with check_async().
Validating User Input
Check a single user message against input rails and handle each possible status.
Validating a Full Conversation
Pass both user and assistant messages to run input and output rails together.
Including Context
Pass context variables alongside user or assistant messages to provide additional information for rail evaluation.
Context messages use the context role with a dictionary value for content.
For more information about context variables, refer to Core Classes: Passing Context.
Checking on the IORails Engine
Construct the Guardrails facade to run checks on the IORails engine.
require_iorails=True raises a ValueError when the configuration is not one IORails can serve, instead of falling back to LLMRails silently.
check_async() starts the engine on first use, in the same way generate_async() does, so no explicit startup() call is required.
Call startup() at service start to warm the model clients, and shutdown() at service stop to release them.
For more information, refer to Engine Feature Support.
Engine Differences
Both engines take messages and rail_types, but each engine executes a check differently:
Blocked Content
On LLMRails, the blocked content is the bot message the Colang flow defines, so a configuration that customizes bot refuse to respond sees its own wording.
On IORails, a blocked check returns the engine’s fixed refusal message, I'm sorry, I can't respond to that., which the configuration cannot change.
That is the same string the built-in rails use by default, so an unmodified configuration produces the same text on both engines.
IORails also distinguishes a policy block from a rail execution failure.
When a rail fails to execute, the check returns BLOCKED with I'm sorry, an internal error has occurred. instead of the refusal message.
This distinction prevents the application from reporting an operational failure as a content refusal.
That wording matches the sentence the Colang runtime produces on LLMRails when an action fails.
On IORails, a blocked check also sets reason, which explains the block for logs and diagnostics.
When a rail fails to execute, reason names the rail that failed.
It adds the model provider’s error message, with credentials and URLs removed, only when the failure came from a model call.
The full error goes to the logs and is recorded as an exception on the rail’s guardrails.action trace span.
Each rail words its own reason, so the text can change between releases.
In every case, treat status as the decision and content as the message to display.
Do not match on the message text or on reason.
Missing Content for a Requested Direction
IORails skips a direction when the messages carry no content for it, and reports PASSED.
An explicit rail_types=[RailType.OUTPUT] on a message list with no assistant text runs no output rails.
Similarly, rail_types=[RailType.INPUT] with no user text runs no input rails.
This keeps a rail that requires the missing text from raising and surfacing as a false block.
A PASSED result from IORails means no rail blocked the messages.
This result includes the case where a requested direction had nothing to check.
When your application requires that a rail actually ran, assert that the message you are validating is present and non-empty before calling check_async().
Observability for IORails Checks
check_async() is instrumented like generate_async() on the IORails engine.
- Tracing produces one
guardrails.requestSERVER span per check, with oneguardrails.railINTERNAL span per rail that runs and aguardrails.actionspan per action. The check makes no main-model call, so the tree has no top-levelchat {model}CLIENT span. LLM calls from rail actions still appear beneath those actions. For more information, refer to Span Reference. - Metrics record the check in
guardrails.requests,guardrails.requests.active,guardrails.request.duration, andguardrails.requests.errors. A block also updatesguardrails.requests.blockedwith therail.typelabel. A tool-result block counts as anInputblock and a tool-call block as anOutputblock, as in generation. A check rejected by a full admission queue incrementsguardrails.nonstream.rejections. For more information, refer to Metric Reference. - Content capture records the checked messages in
guardrails.request.inputand the returned content inguardrails.request.outputon the check’s request span. When an input or output rail rewrites the text it checked, for example to mask personal data, the span records the rewritten messages rather than the ones the caller sent, even when a later rail blocks the check. Until every configured masking rail has decided on the text it guards, the span leaves that text out rather than record it unmasked: for example when a masking rail fails, another rail blocks before the output rails run, orrail_typesleaves out a masking rail’s direction. For more information, refer to Capturing Prompt and Response Content.
The synchronous check() builds a short-lived engine with tracing and metrics disabled, so it emits no spans and no metrics. Use check_async() on instrumented paths.
Guardrails Server
The Guardrails API server (nemoguardrails server) exposes checks through the /v1/checks endpoint, which calls check_async() on the engine serving the requested configuration.
The server resolves that engine through the top-level LLMRails import.
Setting NEMO_GUARDRAILS_IORAILS_ENGINE=1 runs compatible configurations on IORails and the rest on LLMRails.
Requesting a rail type with no configured flows returns HTTP 422.
guardrails.rail_types accepts tool_call and tool_result on a configuration that IORails serves.
On a configuration that LLMRails serves, they return HTTP 422.
The request’s top-level tools field sets the tools a tool_call check validates against.
On a configuration that IORails serves, a request that carries tools without tool_call in guardrails.rail_types returns HTTP 422.
On a configuration that LLMRails serves, a request that carries tools also returns HTTP 422.
A tools entry that is not a Chat Completions function tool returns HTTP 422 as well.
To check a coding agent’s tool calls from its own hooks, use the Guardrails hooks server (nemoguardrails hooks-server) instead.
It is a separate server, which applies a tool policy of its own to each call before it runs the called tool’s per_tool rails.
The response carries status, content, and, on a block, rail.
A block on IORails also carries reason, and a tool rail block also carries tool_violations.
When the request sets guardrails.context, the server prepends a context message, and each violation’s index still counts positions in the request’s own messages.
The response omits a field whose value is None, so a passed check and an LLMRails block carry no reason and no tool_violations.
For a request and response example, refer to Tool Calling: Check Tool Calls and Results Without Generation.
Running the server on the IORails engine is an early-release path. Validate it against your own configurations before depending on it in production.
Related Resources
- Core Classes -
LLMRailsandRailsConfigclass reference - Generation Options - Fine-grained control over generation with the
optionsparameter - Engine Feature Support - What the
LLMRailsandIORailsengines each support