Bedrock Guardrails for Tool-Using Agents in Python
Your Bedrock agent can call tools — but should it? Use Bedrock Guardrails and the ApplyGuardrail API to block prompt attacks and mask PII inside the tool loop.
Series: Bedrock Builder's Log (6 articles)
- 2Bedrock Guardrails for Tool-Using Agents in Python This article
Guardrails for Tool-Using Bedrock Agents: Where to Put the Rails
📦 Companion repo: github.com/AashimaYuthika/bedrock-guardrails-tool-loop — clone it and run the exact code from this article.
In the first entry of this log , I built a Bedrock agent that calls a Python function through the Converse API and reasoned that the safety story of tool use is one line: the model plans, your code executes. That boundary is real, but it's only half the picture. The model still decides what to ask your code to do, and the text flowing in and out of that loop is where the actual risk lives — prompt injection on the way in, leaked PII on the way out, a tool result that quietly poisons the next turn.
So this entry is the sequel the first one demanded: where do you put the rails? The answer on AWS is Amazon Bedrock Guardrails, and specifically the ApplyGuardrail API — a standalone call that scores text against your policies without invoking a model. That decoupling is the whole trick. It means you can inspect every string that crosses the loop boundary, not just the final answer.
The mental model: three checkpoints, not one
Most teams bolt a guardrail onto the model's final output and call it done. In a tool-using agent that's the weakest of the three places it belongs:
- INPUT rail — score the user's message before the first
conversecall. Catch prompt-attack patterns and denied topics here, and you never spend tokens (or run a tool) on a request you were always going to refuse.
- TOOL-RESULT rail — score what your function returns before you hand it back to the model. This is the checkpoint everyone forgets. If
get_customer_record()returns a row with an email and a phone number, that PII is about to become model input. Mask it here or it ends up in the model's context, its logs, and possibly its answer.
- OUTPUT rail — score the final text before it reaches the user, as a backstop.
The design rule I use: guard every boundary where text changes hands. In the Converse tool loop that's three hands-off points, not one.
The code
ApplyGuardrail is a single boto3 call. Wrap it once and drop it at each checkpoint:python
import boto3
brt = boto3.client("bedrock-runtime", region_name="us-east-1")GUARDRAIL_ID = "your-guardrail-id"GUARDRAIL_VERSION = "DRAFT" # pin to a numbered version in prod
def guard(text: str, source: str) -> tuple[bool, str]: """Returns (blocked, safe_text). safe_text may be PII-masked.""" r = brt.apply_guardrail( guardrailIdentifier=GUARDRAIL_ID, guardrailVersion=GUARDRAIL_VERSION, source=source, # "INPUT" or "OUTPUT" content=[{"text": {"text": text}}], ) if r["action"] == "GUARDRAIL_INTERVENED": # If blocked, outputs holds a canned message; if masked, the redacted text. return True, r["outputs"][0]["text"] return False, textNow thread it through the loop from article 1:
python
def run(user_text: str): blocked, safe = guard(user_text, "INPUT") if blocked: return safe # refuse before any model/tool call
messages = [{"role": "user", "content": [{"text": safe}]}] resp = brt.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config) messages.append(resp["output"]["message"])
if resp["stopReason"] == "tool_use": results = [] for block in resp["output"]["message"]["content"]: if "toolUse" not in block: continue tu = block["toolUse"] raw = str(run_tool(tu["name"], tu["input"])) # your validated dispatch _, clean = guard(raw, "INPUT") # mask PII in tool output results.append({"toolResult": { "toolUseId": tu["toolUseId"], "content": [{"text": clean}]}}) messages.append({"role": "user", "content": results}) resp = brt.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
final = next(b["text"] for b in resp["output"]["message"]["content"] if "text" in b) _, safe_final = guard(final, "OUTPUT") return safe_finalNote the tool-result check uses
source="INPUT" — from the guardrail's point of view, your function's output is about to become model input, so that's the policy set you want (PII masking, prompt-attack detection on anything a tool scraped off the web).The tradeoffs nobody puts on the slide
- Latency. Each
guard()call is a network round trip. Three checkpoints add three of them. In practice they're fast and parallelizable, but budget for it — don't guard the same string twice.
- Cost. Guardrails bills per "text unit" (~1,000 characters) per policy. Re-sending a growing conversation through a rail every hop is the same silent multiplier the tool loop itself has. Guard the new text at each boundary, not the whole transcript.
- Masking vs. blocking. For PII, prefer
ANONYMIZED(mask to{NAME},{EMAIL}) overBLOCKED— the agent stays useful without ever seeing the raw value. Reserve hard blocks for denied topics and prompt attacks.
What I'd do
Start with one guardrail, INPUT + tool-result rails, PII set to mask. Pin
guardrailVersion to a number before production so a console tweak can't silently change behavior mid-incident. Turn on tracing and log every GUARDRAIL_INTERVENED — that log is your audit trail and your tuning dataset in one. Add the OUTPUT rail last; if your first two rails are good, it should rarely fire.The first article gave the model hands. This one gives it a supervisor at every door it walks through.
Which rail would you add first — the input filter that saves tokens, or the tool-result filter that keeps PII out of the model's context? And has a guardrail ever blocked something in production you didn't expect?
#AWS #Bedrock #Guardrails #GenAI #AIAgents #Python #ResponsibleAI #MachineLearning
Series: Bedrock Builder's Log (6 articles)
- 2Bedrock Guardrails for Tool-Using Agents in Python This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article