Skip to navigation

Checking Messages Against Rails

View as MarkdownOpen in Claude

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.

async def check_async(
messages: List[dict],
rail_types: Optional[List[RailType]] = None,
*,
tools: Optional[List[dict]] = None, # IORails and the Guardrails facade only
) -> RailsResult

check()

Synchronous wrapper around check_async().

def check(
messages: List[dict],
rail_types: Optional[List[RailType]] = None,
*,
tools: Optional[List[dict]] = None, # IORails and the Guardrails facade only
) -> RailsResult

Parameters:

ParameterTypeDescription
messagesList[dict]List of message dictionaries with role and content fields
rail_typesOptional[List[RailType]]Optional list of rail types to run. When provided, overrides automatic detection based on message roles.
toolsOptional[List[dict]]IORails only; LLMRails raises RailTypeNotSupportedError. The tools a tool_call check validates calls against, as Chat Completions function tools. Only a tool_call check reads them, so passing tools without RailType.TOOL_CALL in rail_types raises InvalidCheckRequestError. Refer to Tool Rails (IORails Only).

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:

Messages ContainRails Executed
Only user messagesInput rails
Only assistant messagesOutput rails
Both user and assistantBoth input and output rails
No user or assistant messagesReturns PASSED status

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:

from nemoguardrails.rails.llm.options import RailType
result = await rails.check_async(
[{"role": "user", "content": "Hello!"}],
rail_types=[RailType.INPUT]
)
ValueDescription
RailType.INPUTRun input rails
RailType.OUTPUTRun output rails
RailType.TOOL_CALLRun tool-call rails on the last assistant message’s tool calls (IORails only)
RailType.TOOL_RESULTRun tool-result rails on the tool messages (IORails only)

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.

Rail typeWhat the check validates
RailType.TOOL_CALLThe tool calls on the last assistant message. With tool call validation configured, each call must name a declared tool, and its arguments must match that tool’s JSON Schema.
RailType.TOOL_RESULTEvery tool message. Each result must link to exactly one earlier tool call by tool_call_id, must not name a different tool than that call, and must carry well-formed content.

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:

from nemoguardrails import Guardrails, RailsConfig
from nemoguardrails.rails.llm.options import RailStatus, RailType
config = RailsConfig.from_path("path/to/config")
rails = Guardrails(config, use_iorails=True, require_iorails=True)
weather_tool = {
"type": "function",
"function": {
"name": "get_weather",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
},
}
messages = [
{"role": "user", "content": "What's the weather in Paris?"},
{
"role": "assistant",
"content": None,
"tool_calls": [
{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}}
],
},
]
result = await rails.check_async(messages, rail_types=[RailType.TOOL_CALL], tools=[weather_tool])
if result.status == RailStatus.BLOCKED:
for violation in result.tool_violations:
print(f"{violation.violation_type.value}: call {violation.tool_call_id} at index {violation.index}")

Keep the following behavior in mind:

  • Tool rails run only when you name them. When rail_types is 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.
  • tools replaces the tools declared in the main model’s parameters.tools, schemas included; it does not add to them. When you omit tools, the configured tools are the allowlist. tools=[] declares no tools, so tool call validation blocks every call.
  • A tools entry that is not a Chat Completions function tool, with a function object and a non-empty name, raises InvalidCheckRequestError rather than being dropped.
  • Only a tool_call check reads tools. Passing tools to any other check, including one that leaves rail_types to automatic detection, raises InvalidCheckRequestError rather than ignoring them.
  • A tool_call check validates only the last assistant message. Earlier calls were validated when they were produced, and a tool_result check validates how results link to them.
  • A tool check needs no main model. It reads the messages and tools in the Chat Completions format, whatever the main model’s engine.
  • A tool rail type counts as configured when its configuration section lists flows or per_tool rails: rails.tool_call for tool_call, and rails.tool_result for tool_result. Otherwise the check raises RailTypeNotConfiguredError.
  • When you name several rail types, they run in the order generation runs them: tool_result, input, tool_call, then output. 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_call on the last assistant message. The other calls on that message are still validated, so tool_violations lists 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.
  • LLMRails does not run tool rails in a check. Requesting a tool rail type, or passing tools, raises RailTypeNotSupportedError rather 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.

FieldTypeDescription
statusRailStatusPASSED, MODIFIED, or BLOCKED
contentstrThe final content after rails processing
railOptional[str]Name of the rail that blocked the content (only when BLOCKED)
reasonOptional[str]Why the rail blocked the content (IORails only; None on LLMRails and when not BLOCKED)
tool_violationsOptional[List[ToolViolation]]The tool calls or tool results a tool rail blocked (IORails only; None unless a tool rail blocked). Refer to Tool Violations

RailStatus Enum

The RailStatus enum represents the three possible outcomes of a rails check.

StatusDescription
PASSEDContent passed all rails without modification
MODIFIEDContent was modified by rails but not blocked
BLOCKEDContent was blocked by a rail

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.

FieldTypeDescription
kindstrtool_call or tool_result
violation_typeToolViolationTypeWhat the call or result violated. Refer to the following table
reasonstrWhy it was blocked. Never contains argument values or tool-result content. A tool name or call id it quotes is cut to 64 characters, followed by ...
tool_call_idOptional[str]The call’s id, or the id a result links to. Always whole, so you can match the violation to its call
tool_nameOptional[str]The tool called. For a result, taken from the call it links to, never from the result’s own name. A name longer than 64 characters is cut to 64, followed by ...
indexOptional[int]For a call, its position in the last assistant message’s tool_calls. For a result, the position of its message in messages
argument_pathOptional[str]For arguments_invalid, a JSON Pointer to the failing argument, such as /city. A key the schema does not declare appears as *. An empty string points at the arguments object itself
schema_keywordOptional[str]For arguments_invalid, the JSON Schema keyword that failed, such as required
railOptional[str]For per_tool_rail and rail_failed, the rail that blocked or failed. Also set when a per_tool rail’s own allowlist or schema check blocked a call, naming that rail
violation_typeKindMeaning
tool_not_allowedCallThe call names a tool that is not declared
arguments_invalidCallThe arguments do not match the tool’s JSON Schema
unexpected_argumentsCallThe tool declares no parameters, but the call passes arguments
invalid_tool_schemaCallThe tool’s declared schema is not valid JSON Schema
malformed_argumentsCallThe arguments are not a JSON object
malformed_tool_callCallThe tool-call entry is not an object, has no function object, or has an id, type, or function name that is not a string. An empty function name counts as malformed
legacy_function_callCallThe last assistant message carries a legacy function_call, which tool rails do not validate
invalid_toolsetCallThe declared tools cannot be used, for example because a tool is declared twice
missing_call_idResultThe result has no tool_call_id
unknown_call_idResultNo earlier call in the same turn has the result’s tool_call_id
duplicate_resultResultAn earlier result already answers the same call
duplicate_prior_call_idResultSeveral calls in a turn share an id, so that turn’s results cannot be linked and are not checked further
name_mismatchResultThe result names a different tool than the call it answers
malformed_contentResultThe content is neither a string nor a list of content blocks
unlinkable_resultResultA per_tool rail applies, but the result cannot be linked to exactly one call
extraction_failedEitherThe messages could not be read in the Chat Completions format
rail_failedEitherA tool rail raised an error instead of deciding. The check returns the internal-error message
per_tool_railEitherA per_tool rail blocked the call or result. When a per_tool rail blocks a call for an undeclared tool or schema-invalid arguments, the violation carries that underlying type instead, such as tool_not_allowed or arguments_invalid, so a call is categorized the same way whichever rails are configured

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.

from nemoguardrails import LLMRails, RailsConfig
from nemoguardrails.rails.llm.options import RailStatus
config = RailsConfig.from_path("path/to/config")
rails = LLMRails(config)
result = await rails.check_async([
{"role": "user", "content": "Hello! How can I hack into a system?"}
])
if result.status == RailStatus.BLOCKED:
print(f"Input blocked by rail: {result.rail}")
elif result.status == RailStatus.MODIFIED:
print(f"Input was modified to: {result.content}")
else:
print("Input passed validation")

Validating a Full Conversation

Pass both user and assistant messages to run input and output rails together.

result = await rails.check_async([
{"role": "user", "content": "What's the weather like?"},
{"role": "assistant", "content": "It's sunny and 72F today!"}
])
if result.status == RailStatus.BLOCKED:
print(f"Conversation blocked by rail: {result.rail}")

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.

result = await rails.check_async([
{
"role": "context",
"content": {"user_id": "12345", "session_type": "support"}
},
{"role": "user", "content": "I need help with my account"}
])

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.

from nemoguardrails import Guardrails, RailsConfig
from nemoguardrails.rails.llm.options import RailStatus
config = RailsConfig.from_path("path/to/config")
rails = Guardrails(config, use_iorails=True, require_iorails=True)
result = await rails.check_async([
{"role": "user", "content": "Hello! How can I hack into a system?"}
])
if result.status == RailStatus.BLOCKED:
print(f"Input blocked by rail: {result.rail} ({result.reason})")

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:

BehaviorLLMRailsIORails
How the check runsThrough the Colang runtime, as a generation with dialog rails and the unrequested rail types disabledDirectly through the engine’s rails manager, with no Colang runtime
Rails that can runEvery configured input and output flow, including community, third-party, and custom-action railsThe input and output rails IORails supports. A configuration outside that set routes to LLMRails
Main LLM callNot madeNot made
Tool railsNot run. Requesting a tool rail type, or passing tools, raises RailTypeNotSupportedErrorRun when named in rail_types. Refer to Tool Rails (IORails Only)
BLOCKED contentThe refusal message defined by the configuration’s Colang flowA fixed refusal message that the configuration does not change
BLOCKED reasonNot reported. reason is NoneThe blocking rail’s own explanation, or the rail’s name when it gives none
Rail that fails to executeHandled by the Colang runtime’s internal-error pathBLOCKED with an internal-error message that is distinct from the refusal message
Requested direction with no content to checkAn output-only check with no user message runs with an empty user message supplied as contextThe direction is skipped and the result is PASSED
Admission controlNoneShares the non-streaming admission queue with generate_async(), and raises NonStreamingWorkQueueFullError (a subclass of asyncio.QueueFull) when the queue is full
Tracing and metricsSpans through a tracing adapter with no OpenTelemetry metricsThe same request span and request metrics as generate_async(). Refer to Observability for IORails Checks
Synchronous check()Runs check_async() on the calling thread’s event loopRuns check_async() on a short-lived engine with tracing and metrics disabled

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.request SERVER span per check, with one guardrails.rail INTERNAL span per rail that runs and a guardrails.action span per action. The check makes no main-model call, so the tree has no top-level chat {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, and guardrails.requests.errors. A block also updates guardrails.requests.blocked with the rail.type label. A tool-result block counts as an Input block and a tool-call block as an Output block, as in generation. A check rejected by a full admission queue increments guardrails.nonstream.rejections. For more information, refer to Metric Reference.
  • Content capture records the checked messages in guardrails.request.input and the returned content in guardrails.request.output on 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, or rail_types leaves 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.