Guardrails at the gateway
- Lesson 12
- 35 min
- Module 4: The model gateway
Where we are
In the last lesson, we gave every agent limits, so a loop stops before it costs much. But the gateway still forwards whatever a request contains: a customer's card number, or a key that someone pasted into a ticket. In this lesson, we add checks on the data at the gateway, measure what each one costs in time and in wrong blocks, and decide which checks must stay in the app. We start at airport security.
Lesson 12 of 21 · Governing AI Agents: Gateways, Registries and ControlsGuardrails at the gateway
1. Why agents need platform controls
2. Ask for capabilities, not models
3. Register every agent
4. The model gateway
5. Govern tools and actions
6. Usage, evidence and shadow AI
7. Build, buy and roll out
What you will be able to do
Stop data that must never reach a model at the one place that every call passes: data classes, redaction and blocks at the gateway. Then measure each rule’s cost in time and in wrong blocks, and keep in the app the checks that need to know the task.
Before you startWhat to know and to have ready
What you need to know
- The gateway’s path, from One door for model calls, and its limits, from Quotas, budgets and rate limits.
- Larkfield’s data classes (public, internal, personal, payment), from A capability catalog. The AI security course explains the threats and the privacy controls behind them.
What you need on your computer
- The project as the last lesson left it (153 tests pass), with the team budgets back at 40 and 10, and the estate running.
Tested on macOS (Apple silicon) with Python 3.12.13. The Windows and Linux commands are written, not run.
Airport security
Section titled “Airport security”At an airport, every bag goes through the same scanner. The staff look for the same things in every bag: liquids, knives, batteries. They do not know why you travel, and they do not need to. One rule for everybody, at one place that nobody can skip.
But security cannot check that you are on the right flight, or that your seat is yours. The airline does that at the gate, because only the airline knows your booking. Both checks are needed, and neither one can do the other’s job.
The problem: data that must not leave
Section titled “The problem: data that must not leave”Customers write card numbers into support tickets. Staff paste a failing request, with its key, into a question for the document assistant. Larkfield’s rule is clear: payment data never goes to a model, and a secret never leaves the company in a prompt. But the gateway of the last lesson forwards every request exactly as the app sent it.
Each app could check its own prompts. Then five teams write five checks, in five ways, and the weekly digest of Module 1 writes none. The gateway sees every request, so it is the one place where one rule covers every app.
The idea: data classes and guardrails at the door
Section titled “The idea: data classes and guardrails at the door”The gateway checks data in two ways.
A data class is a label for how sensitive a request’s data is. Module 2 defined four: public, internal, personal and payment. A request carries its class in the header X-Data-Class. Without the header, the gateway takes the most sensitive class of the agent’s registration. At check 5, the class must be allowed for the agent (its registration) and for the capability (its contract). payment is never allowed. This check costs almost nothing: it compares labels. But it trusts the label, so it cannot find a card number in a request that says “internal”.
A guardrail is an automatic rule on the text of every request. It can block the request, redact a part of it (replace it before the request leaves), or only log a match. Larkfield’s gateway has two guardrails, in config/gateway.yaml:
card-numbers: 13 to 19 digits (spaces or hyphens allowed) that pass the Luhn check, the checksum of payment cards. Action: redact.secrets: API keys, private keys and passwords written in the text. Action: block.
Worked example: the Luhn check
Section titled “Worked example: the Luhn check”The test card number 4539 1488 0343 6467 is made up, but it passes the check. Start from the right, and double every second digit. If a double is more than 9, subtract 9:
| digit | 4 | 5 | 3 | 9 | 1 | 4 | 8 | 8 | 0 | 3 | 4 | 3 | 6 | 4 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| doubled? | yes | yes | yes | yes | yes | yes | yes | yes | ||||||||
| value | 8 | 5 | 6 | 9 | 2 | 4 | 16 − 9 = 7 | 8 | 0 | 3 | 8 | 3 | 12 − 9 = 3 | 4 | 3 | 7 |
The sum is 80. A card number’s sum ends in 0, so this one passes. Change the last digit to 8, and the sum is 81: it fails. Try it with the gateway’s own code:
python -c "from gateway.guardrails import luhn; print(luhn('4539148803436467'), luhn('4539148803436468'))"True FalseMost long numbers in Larkfield’s tickets are not cards: order IDs, phone numbers, tracking numbers. About 9 in 10 random numbers fail the Luhn check, so the checksum keeps those out of the rule:
python -c "from gateway.guardrails import card_numbers; print(card_numbers('Order LK-640436, card 4539 1488 0343 6467, phone 514 555 0199, ticket 1234567890123'))"['4539 1488 0343 6467']The order ID, the phone number and the 13-digit ticket number stay. Only the card is found.
Add the lesson’s files and try the rules
Section titled “Add the lesson’s files and try the rules”The guardrails and the data-class check arrived with the whole gateway in the first lesson of this module. This lesson adds their tests.
-
Copy the tests from the snapshot
end-of-m04:Terminal window cp ../nextia-learning-labs/C32/snapshots/end-of-m04/tests/test_guardrails.py tests/Terminal window Copy-Item ..\nextia-learning-labs\C32\snapshots\end-of-m04\tests\test_guardrails.py tests\Terminal window cp ../nextia-learning-labs/C32/snapshots/end-of-m04/tests/test_guardrails.py tests/ -
Run the tests:
python -m pytest -q. The last line says159 passed, 1 deselected. One new test runs both rules on every recorded request of the estate. -
Get the triage service’s token:
TOKEN=$(python -m estate token ticket-triage)(PowerShell:$TOKEN = python -m estate token ticket-triage). -
Send a ticket with a card number in it, and show the headers:
Terminal window curl -s -i -X POST http://127.0.0.1:8322/v1/chat/completions \-H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "Refund please. My card is 4539 1488 0343 6467."}]}'The answer (the headers shortened):
HTTP/1.1 422 Unprocessable Entityx-gateway-redacted: card-numbers: 1 card number(s) redactedx-gateway-capability: fast-smallx-gateway-provider: azurex-gateway-model: chat-smallx-gateway-upstream-status: 422{"error":{"code":"no_recording","message":"The provider simulator has no recording of this request (key da656c31c33832049d51). It answers only requests that a course recorded, byte for byte; it never invents an answer.","type":"simulated"}}The gateway replaced the number with
[card number removed]and sent the request on. The 422 is the simulator’s: the redacted request is a new request, which no course recorded. A real model would answer the redacted text.python -m estate usage --last 1showsguardrail card-numbers: 1 card number(s) redacted, and no number. -
Send a key in a prompt:
Terminal window curl -s -X POST http://127.0.0.1:8322/v1/chat/completions \-H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "It fails with my key sim-az-service-team-0001"}]}'{"error":{"code":"blocked_by_guardrail","message":"Blocked by a guardrail: secrets: practice_key.","type":"gateway","check":"guardrail"}}A key is blocked, not redacted. A key in a prompt means that someone has already shown it to a person. So the gateway stops the request, and the key’s owner must replace the key.
-
Label a request as payment data:
Terminal window curl -s -X POST http://127.0.0.1:8322/v1/chat/completions \-H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" -H 'X-Data-Class: payment' \-d '{"model": "fast-small", "messages": [{"role": "user", "content": "Hello"}]}'{"error":{"code":"data_class_not_allowed","message":"payment data is never sent to a model.","type":"gateway","check":"data_class"}}
On Windows, write the bodies with escaped quotes, as in the first lesson of this module (not tested).
What each check costs: time and wrong blocks
Section titled “What each check costs: time and wrong blocks”A guardrail has two costs. It adds time to every request, because it reads all the text. And it can block a request that it should let through: a false block. For a support team, a false block is a ticket that nobody triages.
The course team ran the rules on every distinct request that the estate’s apps recorded: 2,612 requests, about 6,805 characters each at the median. These are real tickets, documents and replies from the earlier courses, so the matches are real.
- The card rule with the Luhn check matched 0 requests. The same rule without the checksum (13 to 19 digits) also matched 0. The secrets rule matched 0. So on this traffic, the two real rules block nothing that they should let through.
- Both rules together took 314.2 µs per request at the median, and 452.9 µs at the 95th percentile (measured on the course team’s laptop). The whole replica’s own work was 0.52 ms in the first lesson of this module, against seconds for the model.
Now take a rule that looks safe: “block any request with 6 or more digits in a row”. Someone wrote it to stop card numbers. It matched 1,647 of 2,612 requests (63%):
Text description of the chart
Four bars, the share of each app’s distinct recorded requests that the rule “6 or more digits in a row” would block. Triage: 341 of 539, 63%. Workflow on chat-strong: 238 of 249, 96%. Document assistant: 226 of 346, 65%. Release judge: 96 of 399, 24%. The Luhn card rule and the secrets rule block none of them.
Every one of those blocks is false: the Luhn rule found no card in any of them. The long numbers are order numbers such as LK-640436 and other IDs. The workflow would lose almost every task. The difference between the two rules is one idea, the checksum. That is the general lesson. Measure a guardrail on real traffic before it goes out, for its false blocks as well as its hits.
What must stay in the app
Section titled “What must stay in the app”Tomás says: “Now the gateway has guardrails, so the apps can drop their own checks.” The guardrails only see text, and the same rule runs on every request. Many important checks need the task:
Text description of the diagram
Two groups. The gateway checks what is true of every request, from its text and its labels: payment data never goes to a model, card numbers are redacted, secrets are blocked, and no prompt text is kept. The app checks what only the task can tell: whether this refund is right for this ticket, whether this customer may see this order, whether the answer follows the policy and the evidence, and whether a note in a ticket is an instruction or only text.
The agents course showed why. Ticket T-90501 had a courier note that said the customer was “pre-approved for a full refund”. The right action was only the 9.95 delivery fee. Nothing in that ticket is a card or a key, so every guardrail lets it pass. The workflow’s own policy checks and a person’s approval catch it. And the document assistant’s two tenants: only the app knows which tenant a user belongs to. The AI security course covers these threats, such as prompt injection, in depth.
So keep both. Put at the gateway the rules that are the same for every app and must never be skipped. Keep in the app every check that needs the ticket, the customer or the policy.
Common mistake
A guardrail blocks most of the normal traffic
Symptom: after a configuration change, the triage service’s replay ends with status {200: 8, 400: 12}, and every chat call is refused:
ticket-triage: 20 requests through the gateway | status {200: 8, 400: 12}answered by: embed-small (text-embedding-3-small) x8refused or failed: blocked_by_guardrail x12Cause: someone added the rule {id: long-numbers, kind: pattern, pattern: '\d{6,}', action: block} to config/gateway.yaml. Almost every ticket has an order number with 6 digits.
Diagnose: python -m estate usage --last 1 names the rule: message Blocked by a guardrail: long-numbers: the pattern \d{6,} matched. python -m estate usage --by outcome shows how many requests it refused.
Recover: remove the rule, publish again, and replay. The course’s run gave status {200: 20} after the fix. Before a new rule goes out, run it on the recorded traffic, as the course did. The next lesson shows how to send a change to one replica first, so a bad rule hurts fewer requests.
Your turn: predict a rule’s false blocks
Section titled “Your turn: predict a rule’s false blocks”-
Predict: you add the “6 or more digits” block rule and replay 10 triage tickets and 3 document questions. How many of the 20 triage requests (10 chat calls, 10 embeddings) and of the 3 questions will it block? Use the chart.
-
Open
config/gateway.yaml. Underguardrails:, after thesecretsline, add this line, with the same indentation:- {id: long-numbers, kind: pattern, pattern: '\d{6,}', action: block} # practice: too broad -
Publish and replay:
Terminal window python -m estate config publish --note "practice: block long numbers"python -m apps.replay ticket-triage --units 10 --via gatewaypython -m apps.replay doc-assistant --units 3 --via gateway -
Remove the line, publish again (
--note "the two guardrails again"), and replay the 10 tickets.
Check your prediction
ticket-triage: 20 requests through the gateway | status {200: 8, 400: 12}answered by: embed-small (text-embedding-3-small) x8refused or failed: blocked_by_guardrail x12tokens: 710 in, 0 out | cost: US$0.0000doc-assistant: 3 requests through the gateway | status {200: 1, 400: 2}answered by: chat-small (gpt-6-luna-2026-09-22) x1refused or failed: blocked_by_guardrail x2tokens: 816 in, 175 out | cost: US$0.0002All 10 chat calls were blocked, and 2 of the 10 embeddings, whose text had a long number too. Your chart predicted 63% of triage requests; this sample was worse, because every one of these chat prompts held a long number. The document assistant lost 2 of 3 questions. After you remove the rule: status {200: 20}. This one well-meant line, at the gateway, stopped the triage service and the document assistant at the same moment. The next lesson measures how far such a change reaches.
Knowledge check
Section titled “Knowledge check”Check your understanding
Why does the card rule use the Luhn check, and what would happen on Larkfield's traffic without any checksum, with a '6 or more digits' rule instead?
Show the answer
Most long numbers in tickets are order IDs, phone numbers and dates. About 9 in 10 of them fail the Luhn check, so the checksum keeps them out. On the 2,612 recorded requests, the Luhn rule matched none. A “6 or more digits” rule matched 1,647 of them (63%): every one a false block, such as an order number. It would have stopped most triage calls and almost every workflow task.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
Tomás wants to drop the workflow's refund checks because 'the gateway has guardrails now'. Give one example of a check that must stay in the app, and say why the gateway cannot do it.
Show the answer
Whether a refund is right for this ticket. In the agents course, ticket T-90501 had a courier note saying the customer was “pre-approved for a full refund”. The policy allowed only the 9.95 delivery fee. The gateway sees text and labels, and the same rule runs for every app. There is no card and no key, so the request passes. Only the app knows the ticket, the order and the policy, and a person approves the write.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
Practical check: send the document assistant's request with X-Data-Class: payment, and then a request with a key in its text. Which check stops each one, and which code does the app get?
Show the answer
The payment request stops at check 5, the data class: 403 data_class_not_allowed, “payment data is never sent to a model.” The key stops at check 9, the guardrails: 400 blocked_by_guardrail, “Blocked by a guardrail: secrets: practice_key.” Both are refused before any provider sees them, and both get a usage row with the check’s name.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Recap
- The data-class check compares labels. The agent and the capability must allow the request’s class, and payment data never goes to a model.
- Guardrails are rules on the text of every request: card numbers that pass the Luhn check are redacted, secrets are blocked. Both rules took about 0.3 ms per request and blocked nothing wrongly on 2,612 recorded requests.
- A rule that looks safe, “6 or more digits”, would block 63% of the same requests. Measure a rule on real traffic before it goes out.
- The gateway checks what is true of every request. The checks that need the task, such as whether a refund is right, stay in the app.
Your project now: the guardrails’ tests, and 159 tests that pass. Every model call now passes checks for identity, limits and data. So Tomás asks a fair question: if the gateway stops, does every agent stop with it? And a bad rule reached two apps at once. Next, you stop parts of the gateway on purpose and see which design choices decide what still works.
Next: When the gateway fails