> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # AI Guardrails > How Agent Handler's AI Guardrails work: writing the instruction, the block and log actions, pre-run and post-run screening, tool pack and Group scoping, and picking an evaluation model. AI Guardrails are Security Gateway rules you describe in a sentence instead of a pattern. [Standard Entity Rules](/merge-agent-handler/secure/standard-entity-rules) and [Custom Regex Rules](/merge-agent-handler/secure/custom-regex-rules) match on shape, so they catch things that look a certain way. A guardrail states what you want caught, "any information about Project Alpha, including code names, timelines, or team members", and an evaluator decides whether a given tool call violates it. Reach for a guardrail when the thing you want stopped is a topic or a judgment call rather than a string. Guardrails are available to every organization, and nothing is screened until you write one. Adding your first guardrail is what turns the layer on. ## How evaluation works Before a tool call runs, Agent Handler sends the request to an evaluator together with every guardrail that applies to that call. The evaluator reads the content, compares it against each instruction independently, and answers yes or no per guardrail. On yes, that guardrail's action fires. When the evaluator is unsure, it answers no and the call continues. Guardrails screen in both directions, which makes them the one rule type that can inspect a result rather than an argument: | Pass | When it runs | What it reads | | ------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Pre-run** | After the agent issues `tools/call`, before the request leaves Agent Handler | The method, URL, query parameters, and payload of the outgoing request | | **Post-run** | After the third party replies, before the result reaches tool code | The tool result | Request headers are excluded from what the evaluator sees. They carry auth material, and the entity and regex rules already cover them separately. Two properties are worth knowing before you write your first one. Content reaches the evaluator as data inside per-request boundary markers, so an instruction planted in a tool argument is judged rather than obeyed. And when evaluation itself fails, because the evaluator is unreachable or returns no verdict for a guardrail, the call continues and that guardrail is marked as an evaluation failure rather than a pass, so the gap does not read as a clean run. That second property is a deliberate trade-off, and it runs the opposite way from a fail-closed design: an evaluator outage degrades your coverage rather than stopping your agent. Watch for evaluation-failure rows in [Alerts](https://ah.merge.dev/security/alerts), since a guardrail that keeps failing evaluation is enforcing nothing. If a category of data must never move even during an outage, express it as a Standard Entity Rule or a Custom Regex Rule set to Block. Those match deterministically and do not depend on an evaluator being reachable. ## Configurable per guardrail | Setting | What it does | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | What the guardrail shows up as in the guardrails table, the tester, and the Audit Trail. Unique per organization, case-insensitively, up to 100 characters. | | **What it should catch** | The instruction the evaluator judges against, in plain English | | **Action** | Block or Log, applied when the evaluator says yes | | **What it screens** | Requests (pre-run), responses (post-run), or both. New guardrails screen requests only, so turn on responses when the data you care about arrives rather than departs. At least one is required. | | **Limit to tool packs** | Off by default, in which case the guardrail applies to every Tool Pack in your organization | | **Limit to user groups** | Off by default, in which case the guardrail applies to every Registered User. Available once your identity provider is connected, since the Groups come from [SCIM](/merge-agent-handler/administer/scim-provisioning). | | **Enabled** | Master switch for this guardrail | Configuration lives at [Security → AI Guardrails](https://ah.merge.dev/security/guardrails). Each guardrail can start from a template, which prefills the fields and leaves every one of them editable. One scoping consequence to plan for: a call that runs without a Tool Pack, which is how the employee MCP endpoint in [Agent Handler for Employees](/merge-agent-handler/setup/agent-handler-for-employees) resolves tools, matches only the guardrails that are not limited to Tool Packs. If a guardrail has to cover your employees, leave its Tool Pack limit off. ## The two actions | Action | What happens | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Block** | The call is canceled. On a pre-run verdict the third party is never contacted; on a post-run verdict the result never reaches the agent. The agent gets an error whose message starts with `Blocked by guardrail rule:` and names the guardrail, and the call lands in the [Tool Call Logs](/merge-agent-handler/observe/tool-call-logs) as a failure. | | **Log** | The call proceeds unchanged and the verdict is recorded. Use it to watch what a guardrail would catch before you let it block. | There is no redact action. Redaction needs a matched span to replace, and a guardrail verdict is a judgment about the call as a whole, so Block and Log are the only two choices. ## Writing an instruction the evaluator can act on One subject per guardrail. The evaluator judges each instruction independently, and a guardrail that covers three unrelated topics gives you one verdict where you wanted three, in the table and in every violation you investigate. Name the thing and the forms it takes. "Project Alpha" alone leaves the evaluator guessing about code names and internal shorthand; naming those forms in the instruction is what makes the verdict predictable. Pick the direction deliberately. A topic you don't want leaving your organization is a pre-run guardrail. A category you don't want an agent pulling back in, credentials in a tool result for instance, is a post-run guardrail. Screening both costs two evaluations per call. ## Three worked examples ### A confidential project An unannounced project that must not reach any third-party system, in either direction. ```text Name: Block Project Alpha Instruction: Any information about Project Alpha, including code names, timelines, or team members Action: Block Screens: Requests and responses Applies to: All tool packs ``` Screening both directions matters here: the agent should neither write the project into a ticket nor read it back out of one and carry it into the next call. ### Competitor mentions on outbound calls You want the agent to stay off the subject of competitors in anything it sends to a customer-facing system, without stopping it from reading what is already there. ```text Name: No competitor mentions Instruction: Mentions of competitors or their products in outgoing messages Action: Block Screens: Requests Applies to: The Tool Packs backing customer-facing surfaces ``` Requests only, so the agent can still summarize an inbound email that mentions a competitor. Scoping to specific Tool Packs keeps an internal research agent unaffected. ### Credentials coming back from a tool A repository or a ticketing system can hand an agent a secret that somebody pasted into a comment years ago. You want to know when it happens before you decide to block it. ```text Name: Leaked credentials Instruction: API keys, passwords, tokens, or other secrets appearing in tool responses Action: Log Screens: Responses Applies to: All tool packs ``` Log first. Run it for a week, read what it caught, then switch the action to Block once you trust the instruction. ## Picking an evaluation model Pre-run and post-run each get their own model class, set on the AI Guardrails tab: | Class | Trade-off | | ------------ | -------------------------------------------------------------------- | | **Fast** | Quickest checks at the lowest cost, and enough for most instructions | | **Balanced** | More accurate on nuanced instructions, a little slower | | **Thorough** | Best judgment on subtle or ambiguous content, slowest | Pre-run evaluation sits in front of every call the guardrail applies to, so its class is the one that shows up as latency your users feel. Post-run runs after the third party has already answered, so a slower class there costs less. A common split is Fast on pre-run and Balanced on post-run. Adding guardrails does not multiply that cost. Every guardrail that applies to a call is evaluated in a single request per pass, so a second guardrail on the same pass does not double the latency. Screening both passes is what costs two evaluations. ## Testing before going live The [Rule Tester](/merge-agent-handler/secure/rule-tester) runs a sample input through the whole Gateway and streams the result back in order: entity detections first, then each pre-run verdict, then whether the call was blocked, then the post-run verdicts. Use it to confirm an instruction catches what you meant and leaves benign content alone, which is where most instructions need a second draft. It lives at [Security → Guardrail tester](https://ah.merge.dev/security/guardrail-tester) in the dashboard, and it ships with a library of sample inputs covering payment, health, personal, secret, financial, and legal content, along with a benign control for checking that a new instruction doesn't fire on ordinary traffic. Test the negative case as carefully as the positive one. An instruction written to catch discussion of an acquisition will also catch a customer asking about your funding history if it is loose, and the tester is where you find that out rather than in the alerts table a week later. ## Violations Guardrail verdicts land in [Alerts](https://ah.merge.dev/security/alerts) alongside entity and regex detections, tagged so you can separate the two. Every row carries the guardrail that fired, the action taken, the content the evaluator flagged, the Registered User, and a link to the [tool call](/merge-agent-handler/observe/tool-call-logs). For the full tour of the dashboard, see [Violations and alerts](/merge-agent-handler/secure/violations-and-alerts). ## Where guardrails fit A guardrail evaluates content, so it does not decide who may call which tool. That is what Tool Packs and [tool access](/merge-agent-handler/administer/managing-tool-access) are for. Guardrails also run alongside the pattern rule types rather than replacing them: an entity rule is the cheaper and more precise way to stop a credit card number, a guardrail is the only way to stop a topic, and an entity or regex rule is the one to reach for when the rule has to hold whether or not an evaluator answers. ## Next Investigate what your rules and guardrails are catching in [Violations and alerts](/merge-agent-handler/secure/violations-and-alerts).