Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Guardrails in policies

This section explains how to put guardrails in policies, so that a policy’s decision depends on whether request or response content holds unsafe material. The content check itself is performed by a guardrail, which Policy in AgentCore calls during evaluation. Today guardrails are backed by Amazon Bedrock Guardrails.

A guardrail condition names three things: the guardrail type, the categories that type should assess, and the content to assess. The guardrail returns a confidence score, and your policy decides what to do with it.

If you are new to guardrails in policies, start with Getting started with guardrails, which will walk you through creating one end to end. For example policies covering MCP, runtime, and each inference API, see Guardrail policy examples.

Building blocks of a guardrail condition

Policy in AgentCore supports three guardrail types. Each takes a set of categories to assess and returns its result differently.

For the categories each type accepts, see Supported guardrails. For the content to assess, see Passing context to your guardrail.

A confidence score is a decimal between 0 and 1 expressing how strongly the content exhibits the assessed property. You decide what to do with that score, and the policy expresses your decision as a condition on the guardrail result — most often a threshold comparison, such as .confidenceScore.greaterThan(decimal("0.4")). For thresholds and the comparison operators, see Thresholds for guardrails.

Scores can also be reduced across categories instead of compared one at a time. An aggregation does this: maxConfidenceScore() and minConfidenceScore() return a score, while count() returns how many detections there were and categories() returns the set of categories detected, so those two need no threshold. For the full list, see Aggregations.

Guardrails regional availability

The following table shows which Amazon Regions support guardrails in policies.

Before you begin

Before you start, you need to properly configure your IAM role.

Permissions

The gateway’s execution role needs bedrock:InvokeGuardrailChecks in addition to the AgentCore permissions it already carries. For the latter, see AgentCore Gateway and Policy in AgentCore IAM Permissions.

Policy in AgentCore uses forward access session (FAS) credentials derived from the gateway’s execution role to call the Bedrock Guardrails API on your behalf, which is why the permission belongs on that role.

{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "arn:aws:bedrock:us-west-2:123456789012:guardrail/abc123"
    }
  ]
}

Supported guardrails

Writing guardrails in policies

To put a guardrail in a policy, you can either author the policy as code or describe it in natural language. As with other policies, specify an effect, such as permit, with a condition (when guardrails). In the condition, provide the guardrail to enable, the categories to assess, the content to evaluate, and the score comparison you want.

Example guardrail definition

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___<METHOD>:<uri>", resource == AgentCore::Gateway::"<gateway-arn>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};

Note the three underscores that separate the target name from the method and URI. For examples against a complete reference gateway, see Guardrail policy examples.

Creating a policy with guardrails

To create the policy, put the statement in the policy field of the definition property. For more information, see Create a policy. Otherwise it is created like any other policy.

Whichever surface you use, prefer expressing the rule as a permit with the inverse comparison. Policy evaluation is deny-by-default, so a single permit that holds only while the score stays low both grants the action and gates it:

permit (principal, action == AgentCore::Action::"RefundTool___process_refund", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5")
when guardrails {
  BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"]
    .confidenceScore.lessThanOrEqual(decimal("0.4"))
};

Use forbid when you want to constrain a permission that already exists — an action that some other policy permits, say on its input values. A forbid overrides any permit, so it subtracts from that existing grant. On its own it grants nothing: the action stays denied by default and the guardrail is never consulted, so a lone forbid needs a companion permit for the same action.

For an end-to-end walkthrough using the AgentCore CLI instead, see Getting started with guardrails. For statements on every target type, see Guardrail policy examples.

Specifying a guardrail type

To choose a specific guardrail type, use the BedrockGuardrails namespace:

Selecting a guardrail category

Select a category for the chosen guardrail type (see Supported guardrails).

For example: BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Effects for guardrails

To gate an authorization request on a guardrail, use the permit and forbid effects. These continue to govern request authorization.

forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails {
  BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6"))
};

To suppress outputs from tools, agents, or models, use the suppressOutput effect. suppressOutput operates on the data an action returns. After an authorized action is completed, it evaluates the outputs against the guardrail and suppresses the output when the guardrail is violated.

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])
    .count() > 0
};

Passing context to your guardrail

In a guardrail condition, specify data paths, such as context.input.message, that identify the values to extract from the action’s payload. The guardrail evaluates the extracted values. You can specify one or more paths based on your request or response schema.

For example: [context.input.message, context.input.systemPrompt]

You can provide a data path in one of two ways:

You can give each call several data paths. Each path is extracted independently and sent to the guardrail as its own content block, so to have a list evaluated as distinct items, name the items with separate paths rather than one wildcard path.

For examples on each inference API path, see Reaching text inside arrays with a JSONPath.

Thresholds for guardrails

With content filters and prompt attack detection, the guardrail returns a confidence score, which is a numeric value in the range [0, 1], where 0 is low confidence and 1 is high confidence. The score represents how confidently the guardrail detected a violation. Current possible scores are the discrete values {0.0, 0.2, 0.4, 0.6, 0.8, 1.0}.

To set a threshold, provide the decimal value to the comparison operator, such as greaterThan(decimal("0.4")).

Score comparison operators

You can apply the following comparison operators to confidenceScore, maxConfidenceScore(), or minConfidenceScore():

You can use an aggregation in your policy to extract and compare scores returned by guardrails:

Aggregations

How to choose a threshold

If you do not specify a threshold when prompting the authoring service, AgentCore sets a default value. If you write your policies without the help of the authoring service, you must provide the threshold value.

The following defaults are calibrated to provide broad coverage with acceptable precision for most workloads:

Choosing a custom threshold

If the default thresholds do not meet your requirements, you can determine the optimal threshold for your workload using one of the following approaches.

Option 1: Evaluate against a golden test set

Use this approach when you have a curated set of test inputs with clear expected outcomes.

Option 2: Evaluate against production traffic

Use this approach when you do not have a pre-built test set and want to calibrate using real traffic patterns.

Testing guardrails in a policy

AgentCore provides multiple mechanisms for testing guardrails before enforcing them on production traffic. You can control enforcement at the policy engine level, at the individual policy level, or both, allowing you to validate guardrail behavior incrementally. For more information, see Test a policy in LOG_ONLY mode.

How guardrails work in a policy

You can put a guardrail in a policy on any gateway target. Guardrails run on:

When a call arrives at your gateway, the Policy Evaluator performs the following:

Note: Guardrails are non-deterministic, so the same input can result in different outputs. Policies are deterministic; the same evaluation context will always result in the same policy decision.

Limitations