Skip to content

docs: describe which message guardrail redaction overwrites - #6137

Open
di-brasil wants to merge 2 commits into
strands-agents:mainfrom
di-brasil:docs/guardrail-redaction-latest-message
Open

di-brasil wants to merge 2 commits into
strands-agents:mainfrom
di-brasil:docs/guardrail-redaction-latest-message

Conversation

@di-brasil

Copy link
Copy Markdown

Human Overview

The Bedrock Guardrails page says Strands "overwrites the offending user input". In practice, the current code replaces the latest message in history on either an input or an output block, so after a tool call the tool result is what gets rewritten. I updated the paragraph to match the current behavior and documented guardrail_latest_message=True, which already exists in BedrockModel but isn't mentioned on the page. No code change.

Description

This updates the Bedrock Guardrails documentation to match the current redaction behavior, and documents the existing guardrail_latest_message option.

Three changes, no code is modified:

  1. The paragraph says Strands "overwrites the offending user input". That's narrower than what the code does. On an input or an output block, agent.py replaces the latest message in self.messages, and after a tool-use turn that message is a toolResult. _redact_user_content keeps the toolResult block and swaps only its content. The new wording says that.

  2. The paragraph is silent on scope. By default the whole conversation is sent to the guardrail as input, so content that reached history without being blocked (for example, a tool result that reached history because output wasn't checked) can block every later turn in the session. The new paragraph names that case and points to guardrail_latest_message=True as the opt-in that evaluates only the latest user text message. The code already does this (see models/bedrock.py _find_last_user_text_message_index and the guardContent wrapping); it just isn't documented here.

  3. The BedrockModel(...) example gains one more field so readers see the option at the point they'd use it:

guardrail_latest_message=True,  # Send only the latest user text message to the guardrail

Related Issues

Documentation PR

This PR is the documentation change. The only file touched is site/src/content/docs/user-guide/sdk/safety-security/guardrails.mdx.

Type of Change

Documentation update

Testing

I reproduced the behavior described in the new wording end-to-end and ran the site's CI steps locally.

Observed behavior (strands-agents 1.64.0, Bedrock, eu-west-1, Claude Sonnet 4.6). With a guardrail whose denied topic blocks input and does not check output, and BedrockModel(guardrail_id=..., guardrail_trace="enabled"):

  • Turn 1: a tool returned content that would hit the denied topic ("Buy BTC now…"). The model summarized it. Output isn't checked, so the turn ended with end_turn and the content stayed in history.
  • Turn 2: a harmless follow-up ("Thanks. Is there anything else I should know?") was blocked (guardrail_intervened). ApplyGuardrail on each message alone showed the trigger: the tool result and the model's summary trip input, the follow-up on its own doesn't.
  • Redaction then replaced messages[-1], which was the harmless follow-up. The messages that caused the block stayed. Every later turn in the session was blocked the same way.

With guardrail_latest_message=True on the same BedrockModel, the follow-up passed on the first attempt.

Site CI. From site/, as docs-ci.yml runs:

  • npm ci

  • npm run format:check (CI step: "Check formatting")

  • npm run cms:build with NODE_OPTIONS=--max-old-space-size=4096 (CI step: "Build")

  • npm run typecheck (CI step: "Typecheck")

  • npm test (CI step: "Test")

  • I ran hatch run prepare — N/A, Python SDK unchanged.

The Bedrock Guardrails page says Strands "overwrites the offending user input".
In the current code, agent.py replaces self.messages[-1] on any input or output
block, and after a tool-use turn that message is a toolResult (not the user
message that produced it). Document the actual behavior, and surface the
existing BedrockModel option guardrail_latest_message=True that evaluates only
the latest user text message, which avoids follow-up turns being blocked by
earlier content in history.

Docs only. See issues strands-agents#3613, strands-agents#1639 and PR strands-agents#1978 / strands-agents#2992 for the related code
discussions.
@di-brasil
di-brasil requested a review from a team as a code owner November 13, 2026 17:24
@di-brasil
di-brasil requested a review from Unshure November 13, 2026 17:24
@github-actions github-actions Bot added documentation Documentation changes, improvements, additions, content updates, site improvements, examples, guides area-interventions Related to interventions labels Nov 13, 2026
### Amazon Bedrock

Amazon Bedrock provides a [built-in guardrails framework](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) that integrates directly with Strands. When a guardrail triggers, Strands overwrites the offending user input in the conversation history so a follow-up turn is not blocked by the same content. Control this with the `guardrail_redact_input` boolean, and set the replacement text with `guardrail_redact_input_message`. The same redaction is available for model output, disabled by default: enable it with `guardrail_redact_output` and set its message with `guardrail_redact_output_message`. Below is an example of how to use Bedrock guardrails in your code:
Amazon Bedrock provides a [built-in guardrails framework](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) that integrates directly with Strands. When a guardrail blocks content, on either the input or the output, Strands overwrites the latest message in the conversation history so a follow-up turn is not blocked by the same content. After a turn that called tools, the latest message is the tool result, so only the tool result's content is replaced. Control this with the `guardrail_redact_input` boolean, and set the replacement text with `guardrail_redact_input_message`. The same redaction is available for model output, disabled by default: enable it with `guardrail_redact_output` and set its message with `guardrail_redact_output_message`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@di-brasil #6261 changes which message is redacted when input is blocked: the last user-role message rather than the latest message, in both SDKs. yonib05 asked me to bring this paragraph in line with that. The wording below is only accurate once #6261 merges, so please apply it then.

Suggested change
Amazon Bedrock provides a [built-in guardrails framework](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) that integrates directly with Strands. When a guardrail blocks content, on either the input or the output, Strands overwrites the latest message in the conversation history so a follow-up turn is not blocked by the same content. After a turn that called tools, the latest message is the tool result, so only the tool result's content is replaced. Control this with the `guardrail_redact_input` boolean, and set the replacement text with `guardrail_redact_input_message`. The same redaction is available for model output, disabled by default: enable it with `guardrail_redact_output` and set its message with `guardrail_redact_output_message`.
Amazon Bedrock provides a [built-in guardrails framework](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) that integrates directly with Strands. When a guardrail blocks the input, Strands overwrites the most recent user message in the conversation history so a follow-up turn is not blocked by the same content. Messages added after it, such as context appended by a session manager or a hook, are left unchanged. After a turn that called tools, the most recent user message is the tool result, so only the tool result's content is replaced. Control this with the `guardrail_redact_input` boolean, and set the replacement text with `guardrail_redact_input_message`. The same redaction is available for model output, disabled by default: enable it with `guardrail_redact_output` and set its message with `guardrail_redact_output_message`.

This branch is waiting to be deployed

1 waiting deployment
manual-approval — d1bab06e Waiting Nov 17, 2026 by di-brasil via Build and Deploy Preview #3923
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-interventions Related to interventions documentation Documentation changes, improvements, additions, content updates, site improvements, examples, guides

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants