Bedrock Guardrails

Safety as a configurable layer essential

Here is the failure this section exists to prevent. A team ships a support chatbot on Bedrock. It works beautifully in the demo. Two weeks later a user pastes their full credit-card number into the chat, the model happily quotes it back in its reply, and now that number is sitting in your CloudWatch logs and your conversation history — a compliance incident that started as a helpful answer. Another team's bot cheerfully dispenses legal advice it was never authorized to give. A third confidently answers a question its knowledge base never covered, inventing a policy that does not exist. None of these are model bugs. The model did exactly what a helpful model does. The missing piece was a layer that says "no" before the harmful text ever reaches the user or the logs — and that layer is a guardrail.

Think of a guardrail the way you think of a metal detector at an airport. The detector is not part of any individual traveller, it does not care which airline you fly, and you can upgrade it or retune its sensitivity without changing a single passenger. It simply stands in the doorway and inspects everything that passes in and everything that passes out. A Bedrock Guardrail is that detector for text: a policy object that lives outside the model and screens the conversation in both directions, so the same rules protect every model call you attach it to.

Why make it a separate, configurable layer instead of just writing "please be safe" in the system prompt? Because a prompt is advice the model may or may not follow, while a guardrail is enforcement that runs regardless of what the model decides. Prompts can be jailbroken, ignored under pressure, or forgotten as the conversation grows long; a guardrail is deterministic policy applied by the platform, not by the model's goodwill. It also means your safety rules live in one auditable place — the security team can own them, you can diff them in code review, and you can reuse the identical policy across ten different bots instead of copy-pasting prompt text into each. The single most common mistake here is treating "the model is well-behaved" as your safety strategy; the professional stance is that the model is one layer and the guardrail is an independent second one that does not trust the first.

A Guardrail is a policy object you attach to model calls. It filters harmful content, blocks topics you deny, redacts PII, and can check that a RAG answer is grounded in the retrieved context. It runs on both the input and the output, independent of the model.

Create a guardrail essential

The mistake to avoid is scattering safety checks through your code. The tempting first instinct is to sprinkle if "credit card" in text and a pile of regexes directly into every handler that touches the model. That path leads to safety logic duplicated across ten endpoints, drifting out of sync, impossible to audit, and untestable in one place. Bedrock's answer is to make the policy a single object you create once — the way you'd define one firewall ruleset for a whole network rather than re-deriving the rules at every port.

Reading the lab below, notice that a guardrail is built on the control plane — the management API (the bedrock client) whose whole job is to create and configure resources, as opposed to the runtime that actually runs models. That distinction matters and trips people up constantly: you create a guardrail with the bedrock client, but later you apply it with the bedrock-runtime client. Creating returns a durable identifier and a version number; applying happens on every call using that identifier. Two clients, two jobs.

The policy itself is assembled from independent, opt-in sections — you turn on only the ones you need, and each is just data (dictionaries and lists), which is exactly why adding a new protection later is a one-line edit rather than a code change:

• Content filters score text against harm categories (such as hate or violence) at a strength you choose. Crucially, each category has a separate strength for input (what the user sends) and output (what the model replies) — a higher strength blocks more aggressively but risks catching borderline-benign text, so it is a dial, not a switch.
• PII handling lets you name personal-data entity types and pick an action per type. This is where the two-actions idea lives: some data can pass through masked (anonymized), while some data should stop the request entirely (blocked) — different risk, different action, same policy.
• Denied topics let you refuse a whole subject, not just a word. You give the topic a plain-English definition plus a few example utterances, and Bedrock detects the topic semantically — so a paraphrase you never listed still gets caught, which a keyword blocklist would miss.

The two fallback-message fields are easy to overlook but they are the user's entire experience of a block: when the guardrail refuses, the caller receives that polite text instead of the real content, so it is worth writing something honest and on-brand rather than leaving a terse default. Keep an eye on the returned id and version in the final line — those two values are the handle you must save, because without them no model call can be told which policy to enforce.

create_guardrail.pyimport boto3
bedrock = boto3.client("bedrock", region_name="us-east-1")

g = bedrock.create_guardrail(
    name="support-guardrail",
    blockedInputMessaging="I can't help with that request.",
    blockedOutputsMessaging="I can't provide that response.",
    contentPolicyConfig={"filtersConfig": [
        {"type": "HATE", "inputStrength": "HIGH", "outputStrength": "HIGH"},
        {"type": "VIOLENCE", "inputStrength": "HIGH", "outputStrength": "HIGH"},
    ]},
    sensitiveInformationPolicyConfig={"piiEntitiesConfig": [
        {"type": "EMAIL", "action": "ANONYMIZE"},
        {"type": "CREDIT_DEBIT_CARD_NUMBER", "action": "BLOCK"},
    ]},
    topicPolicyConfig={"topicsConfig": [
        {"name": "legal-advice", "definition": "Providing legal advice.",
         "type": "DENY", "examples": ["Should I sue my employer?"]},
    ]},
)
print("guardrail id:", g["guardrailId"], "version:", g["version"])

Apply it to a call intermediate

A guardrail you created but never attached protects nothing. This is a genuinely common oversight: an engineer builds a polished policy, sees "guardrail created" in the console, ships — and the bot is exactly as exposed as before, because creating a guardrail and using it are two separate acts. The policy sits on the shelf until you hand its identifier to a specific model call. Think of the guardrail as a security badge you had printed: printing it does nothing; it only works when you actually tap it at the door on the way in.

Attaching it is deliberately small: you pass one extra argument — guardrailConfig, carrying the identifier and version from the previous step — to the same converse call you already make. Nothing else about your request changes. That minimalism is the design goal: safety should be a bolt-on you can add (or, in testing, remove) without rewriting your calling code.

The part worth internalizing is how you learn a block happened, because your code must react to it rather than blindly print a reply. Bedrock does not throw an exception when a guardrail fires; it returns a normal, successful response whose stopReason field has changed. A clean completion carries a stop reason like end_turn; when the guardrail intervenes, that field becomes guardrail_intervened. So stopReason is your control signal: branch on it. When it says the guardrail acted, the text already sitting in the response is your fallback message, not the model's real words — the platform has substituted it for you, and the offending content never came back to your application at all. The mistake to avoid is ignoring stopReason and treating every response as trustworthy model output; a blocked call looks structurally identical to a successful one until you read that one field.

Pass guardrailConfig to converse. If the guardrail intervenes, stopReason is guardrail_intervened and you get the safe fallback message instead of raw model output.

apply_guardrail.pyimport boto3
brt = boto3.client("bedrock-runtime", region_name="us-east-1")

resp = brt.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role": "user", "content": [{"text": "My card is 4111 1111 1111 1111, is it valid?"}]}],
    guardrailConfig={"guardrailIdentifier": "GR123", "guardrailVersion": "1"},
)
print("stop reason:", resp["stopReason"])
print(resp["output"]["message"]["content"][0]["text"])

stop reason: guardrail_intervened
I can't provide that response.

Contextual grounding for RAG advanced

You have felt this failure even if you have never built a bot. You ask an assistant a question its documents cannot actually answer, and instead of admitting it, the model produces a fluent, confident, completely invented answer — the classic hallucination. In a RAG system this is the cardinal sin: the retrieval step handed the model some context, the user's question was slightly outside what that context covers, and the model filled the gap with plausible fiction. Content filters and denied topics do nothing here — the answer is not hateful or off-topic, it is simply unsupported. That is the exact hole a contextual-grounding check is built to plug.

The mental model is a diligent fact-checker sitting between the model and the user. The fact-checker holds two things: the source context that retrieval pulled, and the answer the model wrote. Its job is to ask, "Is this answer actually backed by that context, and is it even relevant to what was asked?" It does not judge whether the answer is true in some absolute sense — it judges whether the answer is grounded in the material you gave the model. An answer can be perfectly true in reality and still fail grounding because your documents never mentioned it, and that failure is the point: you want the bot to answer from your corpus, not from the model's training-time memory.

Because "grounded or not" is a matter of degree, the check produces a score rather than a yes/no, and you set a threshold below which the answer is refused. This turns a fuzzy safety concern into a dial you can tune: raise the threshold and the bot becomes stricter (it refuses more, hallucinates less, but sometimes declines answerable questions); lower it and it answers more freely at the cost of letting weaker-supported replies through. Choosing that number is a product decision about how much unsupported confidence you can tolerate. The common mistake is assuming grounding is binary or that a high score guarantees truth — it guarantees support by the provided context, which is what you can actually enforce, and it is a far stronger defense than hoping the model stays honest on its own.

The grounding check scores whether an answer is supported by the source context and relevant to the query. Below a threshold, the guardrail blocks the answer — a managed defense against the hallucination problem you evaluated in Ch 5.

import boto3

bedrock = boto3.client("bedrock", region_name="us-east-1")
resp = bedrock.create_guardrail(
    name="support-guardrail",
    blockedInputMessaging="I can't help with that request.",
    blockedOutputsMessaging="Response withheld by policy.",
    contentPolicyConfig={"filtersConfig": [
        {"type": "HATE",     "inputStrength": "HIGH", "outputStrength": "HIGH"},
        {"type": "VIOLENCE", "inputStrength": "HIGH", "outputStrength": "HIGH"},
    ]},
)
print(resp["guardrailId"], resp["version"])

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
r = brt.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role":"user","content":[{"text":"...user text..."}]}],
    guardrailConfig={"guardrailIdentifier": "GR123", "guardrailVersion": "1"},
)
if r["stopReason"] == "guardrail_intervened":
    print("blocked; safe fallback returned")
else:
    print(r["output"]["message"]["content"][0]["text"])

import boto3

bedrock = boto3.client("bedrock", region_name="us-east-1")
bedrock.create_guardrail(
    name="pii-guardrail",
    blockedInputMessaging="blocked", blockedOutputsMessaging="blocked",
    sensitiveInformationPolicyConfig={"piiEntitiesConfig": [
        {"type": "EMAIL",                  "action": "ANONYMIZE"},
        {"type": "CREDIT_DEBIT_CARD_NUMBER", "action": "BLOCK"},
    ]},
)
print("pii guardrail created")

import boto3

bedrock = boto3.client("bedrock", region_name="us-east-1")
bedrock.create_guardrail(
    name="topic-guardrail",
    blockedInputMessaging="I can't advise on that.",
    blockedOutputsMessaging="Withheld.",
    topicPolicyConfig={"topicsConfig": [{
        "name": "FinancialAdvice",
        "definition": "Recommendations to buy/sell specific securities.",
        "type": "DENY",
        "examples": ["Should I buy TSLA?", "What stock will go up?"],
    }]},
)
print("topic guardrail created")

def build_guardrail_config(pii, denied_topics):
    cfg = {"name": "house-guardrail",
           "blockedInputMessaging": "blocked",
           "blockedOutputsMessaging": "blocked"}
    if pii:
        cfg["sensitiveInformationPolicyConfig"] = {"piiEntitiesConfig":
            [{"type": t, "action": a} for t, a in pii]}
    if denied_topics:
        cfg["topicPolicyConfig"] = {"topicsConfig":
            [{"name": n, "definition": d, "type": "DENY", "examples": ex}
             for n, d, ex in denied_topics]}
    return cfg

c = build_guardrail_config(
    pii=[("EMAIL","ANONYMIZE"),("SSN","BLOCK")],
    denied_topics=[("Legal","Legal advice",["Can I sue?"])])
print(list(c.keys()))

def gate(grounding_score, stop_reason, threshold=0.75):
    if stop_reason == "guardrail_intervened":
        return {"action": "blocked_by_guardrail"}
    if grounding_score < threshold:
        return {"action": "refuse", "reason": "insufficient grounding",
                "score": grounding_score}
    return {"action": "answer", "score": grounding_score}

print(gate(0.91, "end_turn"))   # answer
print(gate(0.40, "end_turn"))   # refuse
print(gate(0.99, "guardrail_intervened"))   # blocked_by_guardrail

Knowledge check check yourself