AWS Builder Center

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)

  1. 2
    Bedrock Guardrails for Tool-Using Agents in Python This article
Lead Data Scientist

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  converse  call. 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, text
Now 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_final
Note 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} ) over  BLOCKED  — 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)

  1. 2
    Bedrock Guardrails for Tool-Using Agents in Python This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article