4.8

Guardrails, PII, and the decision middleware (beta)

PIIMiddleware rewrites or blocks one kind of personal data by a fixed rule, and two beta middlewares ask a decision model to pick a model or block a call.

A user pastes an email address and a card number into your support agent. The model provider now has both. A day later the model asks to delete the main branch, and the tool runs. Both needed a check between the user, the model, and the tools.

When you finish this section, you can choose a PII strategy, say where PIIMiddleware acts, and read what it changed. You can also set up ModelRouterMiddleware and AutoModeMiddleware, and say what their decision models receive.

Two kinds of guardrail

Guardrail: a check that runs inside the agent and changes, blocks, or stops a request, a reply, or a tool call.

The guardrails page names two kinds. A deterministic guardrail uses rules, such as a regular expression. It is fast and repeatable, and it misses what the rule does not describe. A model-based guardrail asks a model or a classifier, and costs a call.

PIIMiddleware is the deterministic guardrail in langchain. HumanInTheLoopMiddleware asks a person, and section 6.5 covers it. The two decision middlewares below are model-based.

PIIMiddleware

PIIMiddleware: a middleware that finds one type of personal data in messages and applies one strategy to each match.

Each instance handles one type: email, credit_card, ip, mac_address, url, or a name of your own with a detector. Use one instance for each type. Each instance is named PIIMiddleware[<type>], so two instances of one type conflict. Its defaults set where it acts:

OptionDefaultWhere it acts
apply_to_inputTruethe newest human message, in before_model
apply_to_outputFalsethe newest AI message, in after_model
apply_to_tool_resultsFalsethe tool messages after the newest AI message, in before_model
strategyredactwhat it does with a match

The middleware changes the message in the state, so the checkpoint and the trace hold the changed text too. The kit sends one input with four kinds of data, through one middleware at a time. Figure 4.13 sets the results side by side.

Fig. 4.13four PII strategies on one inputcomparison
Four PII strategies on one input One human message holds an email address, a card number, an IP address, and a URL, each underlined in the hue of the row that matched it. Five rows each ran one PIIMiddleware. email with redact replaced "ada@example.com" with "[REDACTED_EMAIL]". credit_card with mask replaced "4111 1111 1111" with "**** **** ****". ip with hash replaced "192.168.1.20" with "<ip_hash:55235459>". url with redact replaced "https://example.com/x" with "[REDACTED_URL]". email with block raised PIIDetectionError, "Detected 1 instance(s) of email in text content", and the model got 0 calls. Each other run made 1 model call, and only the matched span of the newest human message changed. THE HUMAN MESSAGE 1 2 Mail ada@example.com, card 4111 1111 1111 1111, 3 4 from 192.168.1.20, see https://example.com/x PIIMIDDLEWARE THE MATCHED SPAN BECOMES MODEL CALLS 1 'email' strategy='redact' ada@example.com [REDACTED_EMAIL] 1 2 'credit_card' strategy='mask' 4111 1111 1111 **** **** **** 1 3 'ip' strategy='hash' 192.168.1.20 <ip_hash:55235459> 1 4 'url' strategy='redact' https://example.com/x [REDACTED_URL] 1 5 'email' strategy='block' PIIDetectionError Detected 1 instance(s) of email in text content 0 Each row is one run. Grey: what the input held. Bold: what was saved and sent instead. Only the newest human message changed, because apply_to_input is the default.
Redact and hash replace the match, mask keeps the last four digits of a card, and block raises before the model gets any call. Each row is one run of the kit with one PIIMiddleware. The left column is the setting, and the right column is the text the model received, or the error.
jsonthe human message after PIIMiddleware('credit_card', strategy='mask')Full log
    "content": "Mail ada@example.com, card **** **** **** 1111, from 192.168.1.20, see https://example.com/x",

hash writes the type and a short hash, here <ip_hash:55235459>. The same address gives the same hash, so the model can tell two values apart without seeing them. block raises before the model call:

outputPIIMiddleware('email', strategy='block')Full log
raised langchain.agents.middleware._redaction.PIIDetectionError: Detected 1 instance(s) of email in text content

model calls, as the model received them:
[]
The model log after the error is empty.

A custom detector is a regular expression or a function. The kit redacts keys that match sk-[a-z0-9]{8}:

pythona custom detectorFull log
        middleware=[PIIMiddleware("api_key", detector=r"sk-[a-z0-9]{8}", strategy="redact")], inp=ask("my key is sk-abcd1234"), first=0)

The model received my key is [REDACTED_API_KEY], and it answered that the key was redacted. With apply_to_output=True, the kit asked the model to reply Write to grace@example.org.. That reply became Write to [REDACTED_EMAIL]. in the state.

The four runs on input each got the same answer from Qwen3 4B: I'm sorry, but I can't assist with that request.. The input still held a card number, an address, or a URL, and the model refused. Redaction changes what the model reads, and it does not make the request look safe to the model.

The guardrails page describes a stream transformer for apply_to_output=True. It holds back the last 128 characters of each text block, so a match split across chunks is not sent. The kit did not stream through PIIMiddleware. That test is coming in the next edition, and section 8.8 lists it.

Decision models

Decision model: a BaseDecisionModel from langchain_core.decisions, new in langchain-core 1.8.0. It answers typed questions, such as a choice among named options or the probability that a statement is true.

Both decision middlewares are new in langchain 1.5.0, by the release notes, and both are in beta. The prebuilt middleware page marks both as beta. In the code, ModelRouterMiddleware has the beta decorator and warns when you build it. AutoModeMiddleware says beta in its docstring only, so it gives no warning. LangChain has decision models for OpenAI and Google only.

So the kit answers with OllamaDecisionModel, about 34 lines of its own. It sends each question and the state to Qwen3 4B in JSON mode, and turns the JSON reply into the typed answer. The questions below are what the middleware sent, and the answers are what the model said.

ModelRouterMiddleware

ModelRouterMiddleware asks one choice question in before_agent and uses the chosen model for every model call of the run. The kit gives it two choices, fast and deep. This is the question it sent:

jsonthe question ModelRouterMiddleware sentFull log
    "questions": {
      "model_route": {
        "type": "choice",
        "criteria": {
          "fast": "arithmetic and short answers",
          "deep": "long reasoning"
        },
        "instructions": "Pick the cheapest model that can answer."
      }
    }

The decision model answered fast, with probability 0.999 against 0.001 for deep. The deep route was qwen3:8b, and it got no call. The fast model got the only model call, the model passed to create_agent got none, and the answer went into state["model_route"]. The run warned LangChainBetaWarning: The middleware ModelRouterMiddleware is in beta..

AutoModeMiddleware

AutoModeMiddleware: a middleware that asks a decision model, before each call to a listed tool, for the probability that the call is risky. At 0.5 or more it blocks the call.

The middleware sends the tool call, the tool description, and up to 30 recent messages. A blocked call gets an error ToolMessage, and the tool does not run. A tool you do not list runs with no question. When the decision model raises, the error goes up and the tool does not run. The middleware blocks. It never asks a person.

The kit lists delete_branch and add, and asks the model to call both in one reply. The decision model answered 0.999 for delete_branch and 0.0 for add:

jsonone blocked call and one allowed callFull log
    "type": "ToolMessage",
    "content": "The tool call `delete_branch` was blocked because it was classified as risky (probability: 1.00). The tool was not executed.",
    "name": "delete_branch",
…
    "tool_call_id": "<uuid-3>",
    "status": "error"
  },
  {
    "type": "ToolMessage",
    "content": "5",
    "name": "add",
The two ToolMessages. The ids are cut.

The user asked for the deletion in plain words, and the call was still blocked. The instructions of the middleware count destructive actions as risky. In an earlier recording of the same scenario, the decision model also gave add 0.999 and blocked it. A small decision model can block a safe call, so measure it on your own calls before you rely on it.

Figure 4.14 draws the two paths. The question that the decision model received has criteria set to null:

jsonthe question AutoModeMiddleware sentFull log
    "is_risky": {
      "type": "noul",
…
      "criteria": null
    }
The instructions are cut after their first sentence.
Fig. 4.14what AutoModeMiddleware does with one tool calldecision
What AutoModeMiddleware does with one tool call The model asks for two tool calls, delete_branch with name main and add with 2 and 3. For each listed tool, AutoModeMiddleware asks the decision model the noul question is_risky, with the instructions, the tool call, the tool description, up to 30 messages, and criteria null. delete_branch scored 0.999, at or above 0.5, so it got an error ToolMessage and did not run. add scored 0.0, so it ran and returned 5. A tool that is not listed runs with no question. AIMessage tool_calls delete_branch(main), add(2, 3) question is_risky, type noul instructions, tool_call, tool_description, up to 30 messages, criteria: null each listed tool delete_branch: 0.999 at or above 0.5: error ToolMessage, the tool does not run add: 0.0 below 0.5: the tool runs, ToolMessage 5 risky allowed a tool missing from tools= runs with no question to the decision model The probabilities are the answers of Qwen3 4B through the OllamaDecisionModel of the kit.
A listed tool call at or above 0.5 gets an error ToolMessage and never runs, and the question carries criteria null unless you pass criteria. Read from the tool call at the top. The amber box is the question to the decision model, with the fields it sent. The rose box is the blocked delete_branch call, and the green box is add, which ran.

The config class of the middleware has default criteria: risky means harm, more than the user allowed, exposed data, or an outside effect. The constructor takes criteria=None as its default and passes it on, and that None replaces the default. So with no criteria argument, the decision model gets the instructions and no criteria. Pass a NoulCriteria with true and false texts when your decision model needs them.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11