Define a guardrail

A guardrail is a named check run at one boundary of an agent: its input (the user text), its output (the model's reply), or a tool call (a tool's name and arguments before it runs, or its result after). The check returns TRUE to pass, or a short reason string to fail. On failure the guardrail either blocks (raises a typed condition and records the event), warns, or merely flags; in every case the decision is recorded as an event, so a blocked input is analyzable rather than invisible.

Usage

guardrail(
  name,
  check,
  on_fail = c("block", "warn", "flag"),
  stage = c("input", "output", "tool")
)

Arguments

name

A short label for the guardrail (appears in events).

check

A function (payload, context) -> TRUE | reason. payload is the text (input/output) or a list(name=, arguments=, result=) (tool). context is a small list with stage, agent, and phase ("pre" or "post" for tools). Return TRUE to pass, or a non-empty character reason to fail.

on_fail

What to do on failure: "block" (raise llmragent_guardrail_block and stop), "warn" (warn and continue), or "flag" (record only). Default "block".

stage

Which boundary: "input", "output", or "tool".

Value

An object of class agent_guardrail.

See also

guardrails(), agent()

Examples

no_pii <- guardrail(
  "no_ssn",
  function(payload, context) {
    if (grepl("\\b\\d{3}-\\d{2}-\\d{4}\\b", payload)) "contains an SSN" else TRUE
  },
  stage = "input"
)