---
schema_version: "1"
id: 5723399867c67a96bdcd67b0d96f74c683ceb0b3276a177c267660957e624cfd
title: A2A v1 Bedrock Guardrails Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-a2a-v1-bedrock-guardrails.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-bedrock-guardrails
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 1b449c79ba12de6601ef0ffc815090db3d66968535d7c09e443e103c5f36f4b0
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: api gateway, flex gateway, gateway, policy, a2a, agent, bedrock, guardrails, content safety, pii
---

# A2A v1 Bedrock Guardrails Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Bedrock Guardrails Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-bedrock-guardrails-release-notes">A2A v1 Bedrock Guardrails Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates guardrail policies</p></td></tr><tr><td><p>503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The A2A v1 Bedrock Guardrails policy provides comprehensive content moderation for A2A v1.0
(Agent-to-Agent) traffic by evaluating the entire request and response payloads against Amazon
Bedrock guardrails. This policy works with both JSON-RPC and HTTP+JSON transports.

The policy integrates with AWS Bedrock’s [Guardrails](https://aws.amazon.com/bedrock/guardrails/)
feature to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across six categories (hate, insults,
  sexual, violence, misconduct, prompt attacks) with configurable filter strengths (NONE, LOW,
  MEDIUM, HIGH).

- **Denied topics**: Blocks content related to specific topics you define, for example, financial
  advice, medical diagnosis

- **Word filters**: Blocks profanity and custom words or phrases you specify

- **PII detection**: Detects and optionally redacts personally identifiable information, for
  example, names, addresses, SSNs, credit cards

- **Contextual grounding**: Evaluates whether agent responses are grounded in provided reference
  text and relevant to the user query (hallucination detection)

The policy enforces the rules you configure for the specific guardrail in AWS.

The policy operates in two independent phases:

- **Request phase** — Moderates user messages before they reach the upstream agent, preventing
  harmful or inappropriate prompts from being processed.

- **Response phase** — Moderates agent responses before they reach the client, ensuring outputs
  comply with safety policies. Streaming responses (`text/event-stream`) aren’t moderated in v1.

When content violates guardrail policies, the request is rejected with a `403` error code and never
reaches the upstream agent (request phase) or the client receives a `403` instead of the agent
response (response phase).

## Before You Begin

Before configuring this policy, you need:

1.  **AWS Account** with access to Amazon Bedrock

2.  **Bedrock Guardrail** created and configured in AWS Console

3.  **IAM Credentials** with permissions to call `bedrock:ApplyGuardrail`

4.  **Guardrail ID** from the AWS Console

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Bedrock Guardrails policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Bedrock Runtime Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Amazon Bedrock Runtime endpoint URL. Accepts either:</p></div><div><ul><li><p>Base host: <code>https://bedrock-runtime.us-east-1.amazonaws.com</code></p></li><li><p>Full ApplyGuardrail URL: <code>https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/&lt;id&gt;/version/&lt;version&gt;/apply</code></p></li></ul></div><div><p>When the full URL is provided, the policy derives the region, guardrail identifier, and guardrail version, unless if you explicitly configure those values.</p></div></div></td></tr><tr><td><div><div><p>AWS Credentials</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS credentials and region for signing requests to the Bedrock API. See <a href="#aws-credentials">AWS Credentials</a>.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Identifier</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>The unique ID of the Bedrock guardrail to apply (for example, <code>paccgfhgnj1dc</code>).</p></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Guardrail Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Version of the guardrail to apply.</p></div><div><ul><li><p><code>DRAFT</code> (default): Use the working draft version for development and testing.</p></li><li><p>Numeric version (for example, <code>"1"</code>, <code>"2"</code>): Use a published version for production deployments.</p></li></ul></div><div><p>Required unless provided in the Bedrock Runtime Endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire request body against the guardrail before forwarding to the upstream agent. Rejected requests never reach the agent.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled (default: <code>true</code>), the policy evaluates the entire unary response body against the guardrail before returning to the client. Rejected responses return a <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr></tbody></table>

### AWS Credentials

The policy uses AWS Signature V4 to authenticate with the Bedrock API and supports both long-lived
IAM credentials and temporary STS credentials.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Access Key ID</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS access key ID, either:</p></div><div><ul><li><p>Long-lived IAM user credentials (starting with <code>AKIA</code>)</p></li><li><p>Temporary credentials from STS or SSO (starting with <code>ASIA</code>)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Secret Access Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>AWS secret access key corresponding to the Access Key ID.</p></div></div></td></tr><tr><td><div><div><p>Session Token</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>Required when using temporary credentials (Access Key ID starting with <code>ASIA</code>). Leave empty for long-lived IAM user credentials.</p></div></div></td></tr><tr><td><div><div><p>Region</p></div></div></td><td><div><div><p>Conditional</p></div></div></td><td><div><div><p>AWS region of the Bedrock Runtime endpoint (for example, <code>us-east-1</code>).</p></div><div><p>Set explicitly for custom domains or VPC endpoints. Optional when the region is provided in the Bedrock Runtime Endpoint host.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the reference text for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Query Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.metadata.context]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.metadata.context]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Grounding Query Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the user query for contextual grounding from the request body.</p></div><div><p>Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with <strong>Grounding Source Selector</strong>.</p></div><div><p>Example for JSON-RPC: <code>#[payload.params.message.parts[0].text]</code></p></div><div><p>Example for HTTP+JSON: <code>#[payload.message.parts[0].text]</code></p></div><div><p>See <a href="#contextual-grounding">Contextual Grounding</a> for more information.</p></div></div></td></tr><tr><td><div><div><p>Max Payload Bytes</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum request or response body size (in bytes) sent to Bedrock.</p></div><div><ul><li><p>Default: <code>25000</code></p></li><li><p>Range: <code>1024</code> - <code>25000</code></p></li></ul></div><div><p>The <code>ApplyGuardrail</code> API caps synchronous calls at approximately 25,000 characters. Larger payloads are rejected (when fail-open is disabled) or passed through without moderation (when fail-open is enabled).</p></div></div></td></tr><tr><td><div><div><p>Sampling Rate Percent</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Percentage of sessions to sample for moderation (0-100).</p></div><div><ul><li><p>Default: <code>100</code> (moderate every request)</p></li><li><p><code>50</code>: Moderate half of sessions</p></li><li><p><code>0</code>: Disable moderation</p></li></ul></div><div><p>Sampling is deterministic per session. The same session is always or never sampled.</p></div></div></td></tr><tr><td><div><div><p>Session Key Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression that extracts the session identifier used for sampling.</p></div><div><p>By default, the key selector resolves to A2A v1.0 <code>contextId</code> (conversation-scoped identifier). For single messages that aren’t part of an ongoing A2A conversation (one-shot sends), the key selector resolves to <code>messageId</code>.</p></div><div><p>Only used when Sampling Rate Percent is less than 100.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Timeout in milliseconds for calls to the Bedrock <code>ApplyGuardrail</code> API.</p></div><div><ul><li><p>Default: <code>5000</code></p></li><li><p>Range: <code>1000</code> - <code>30000</code></p></li></ul></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Bedrock API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div><div><p>When enabled, failures are logged and the <code>service_unavailable</code> reason is emitted in response headers for observability.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The A2A v1 Bedrock Guardrails policy integrates with AWS Bedrock’s content moderation service to
evaluate complete A2A request and response payloads against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for requests and responses. The two phases mirror AWS
Bedrock’s INPUT and OUTPUT scopes:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the entire request body.

    2.  The policy sends the complete JSON payload to Bedrock’s `ApplyGuardrail` API.

    3.  If the content violates any guardrail policies, the policy blocks the request and returns a
        `403` error code to the client.

    4.  If the content passes, the policy forwards the original request to the upstream agent.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the agent response.

    2.  The policy sends the complete response to Bedrock’s `ApplyGuardrail` API.

    3.  If the response violates any guardrail policies, the policy returns a `403` error code to
        the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation. Only non-streaming (`application/json`) responses are moderated.

### Supported Transports

The policy supports these A2A v1.0 transports:

- **JSON-RPC**

- **HTTP+JSON**

The policy doesn’t support gRPC traffic (`application/grpc` or `application/grpc+proto`) and it
passes through without moderation. When gRPC traffic is detected, the policy emits these
observability headers:

- `x-flex-bedrock-guardrails-action: skip`

- `x-flex-bedrock-guardrails-reason: unsupported_transport_v1`

### Method Scope

The policy only evaluates `SendMessage` and `SendStreamingMessage` methods. Other methods (for
example, `GetTask`, `ListTasks`, `SubscribeToTask`, agent card requests) pass through without
moderation.

### Contextual Grounding

Contextual grounding helps detect hallucinations by scoring agent responses on two dimensions:

- **Grounding**: Is the response derived from the provided reference text?

- **Relevance**: Does the response actually answer the user’s question?

To enable contextual grounding:

1.  Enable the contextual grounding feature for your AWS Bedrock guardrail.

2.  Configure both **Grounding Source Selector** and **Grounding Query Selector** in the policy.

The selectors are DataWeave expressions that extract:

- **Grounding source**: The reference text the answer should be based on (often from message
  metadata or context)

- **Query**: The user’s actual question (often from message parts)

Both parameters must be configured together. Configuring only one causes the Bedrock API to return a
`400` error code.

DataWeave selectors bind to the raw request body differently for different transports:

- JSON-RPC

  For JSON-RPC, A2A parameters are under `payload.params.*`. For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.params.message.metadata.context]"
    groundingQuerySelector: "#[payload.params.message.parts[0].text]"
  ```

- HTTP+JSON

  For HTTP+JSON, A2A parameters are at the top level (`payload.*`). For example:

  ```yaml
  advancedConfiguration:
    groundingSourceSelector: "#[payload.message.metadata.context]"
    groundingQuerySelector: "#[payload.message.parts[0].text]"
  ```

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-flex-bedrock-guardrails-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code>, <code>skip</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies. <code>skip</code> indicates the request wasn’t moderated (sampling, gRPC, or streaming).</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the request or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-flex-bedrock-guardrails-reason</code></p></div></div></td><td><div><div><p><code>content_filter</code>, <code>denied_topic</code>, <code>word_filter</code>, <code>pii</code>, <code>grounding</code>, <code>payload_too_large</code>, <code>service_unavailable</code>, <code>sampled_out</code>, <code>unsupported_transport_v1</code></p></div></div></td><td><div><div><p>Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: "${GUARDRAIL_IDENTIFIER}"
    guardrailVersion: "1"
```

### Using Full URL (Region, ID, and Version Derived)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/2dxe6otc16kv/version/DRAFT/apply
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
```

### Request-Only Moderation (Block Harmful Prompts)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: false
```

### With Contextual Grounding (Hallucination Detection)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      sessionToken: "${AWS_SESSION_TOKEN}" # for temporary credentials
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: DRAFT
    moderateRequest: false
    moderateResponse: true
    advancedConfiguration:
      groundingSourceSelector: "#[payload.params.message.metadata.context]"
      groundingQuerySelector: "#[payload.params.message.parts[0].text]"
      apiTimeoutMs: 8000
      failOpen: false
```

### Fail-Open Configuration with Sampling (High Availability, Cost Control)

```yaml
- policyRef:
    name: a2a-v1-bedrock-guardrails-policy-v1-0-impl
  config:
    bedrockEndpoint: https://bedrock-runtime.us-east-1.amazonaws.com
    awsCredentials:
      accessKeyId: "${AWS_ACCESS_KEY_ID}"
      secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"
      region: us-east-1
    guardrailIdentifier: paccgfhgnj1dc
    guardrailVersion: "1"
    moderateRequest: true
    moderateResponse: true
    advancedConfiguration:
      failOpen: true # Allow traffic if Bedrock is unavailable
      apiTimeoutMs: 3000
      samplingRatePercent: 50 # Moderate 50% of sessions
```

## Error Responses

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Condition</th><th>Status Code</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Content violates guardrail (request phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Request blocked before reaching the agent. Response body contains A2A error envelope with reason details.</p></div></div></td></tr><tr><td><div><div><p>Content violates guardrail (response phase)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Response blocked and replaced with A2A error envelope. Original response is not returned.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open disabled)</p></div></div></td><td><div><div><p>503 Service Unavailable</p></div></div></td><td><div><div><p>Bedrock service error or timeout with fail-open disabled. Traffic is blocked.</p></div></div></td></tr><tr><td><div><div><p>Bedrock API failure (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Traffic proceeds unmoderated. Observability headers indicate <code>service_unavailable</code>.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open disabled)</p></div></div></td><td><div><div><p>403 Forbidden</p></div></div></td><td><div><div><p>Payload larger than <code>maxPayloadBytes</code>. Request blocked.</p></div></div></td></tr><tr><td><div><div><p>Payload exceeds size limit (fail-open enabled)</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Oversized payload passes through unmoderated. Observability headers indicate <code>payload_too_large</code>.</p></div></div></td></tr><tr><td><div><div><p>Sampled-out session</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>Session not selected for moderation. Traffic passes through with <code>sampled_out</code> reason header.</p></div></div></td></tr><tr><td><div><div><p>gRPC traffic</p></div></div></td><td><div><div><p>Varies</p></div></div></td><td><div><div><p>gRPC traffic passes through unmoderated with <code>unsupported_transport_v1</code> reason header.</p></div></div></td></tr></tbody></table>

## Limitations

- **Streaming responses**: Streaming responses (`text/event-stream`) aren’t moderated and pass
  through unchanged.

- **gRPC traffic**: gRPC traffic isn’t moderated and passes through with observability headers.

- **Payload size**: Payloads exceeding `maxPayloadBytes` (default 25,000 bytes) can’t be evaluated
  synchronously by Bedrock.

- **JSON envelope**: Bedrock evaluates the complete JSON payload, including A2A protocol fields, not
  just the natural language content. This may affect classifier confidence scores compared to
  evaluating bare text.

## Best Practices

1.  **Use versioned guardrails in production**: Pin to a numeric guardrail version instead of
    `DRAFT` for consistent, repeatable behavior.

2.  **Monitor observability headers**: Track `x-flex-bedrock-guardrails-reason` headers to
    understand why content is blocked or skipped.

3.  **Start with sampling in production**: Use `samplingRatePercent: 50` or lower initially to
    control costs while establishing baseline behavior.

4.  **Enable fail-open for availability**: Consider `failOpen: true` in production to prevent
    Bedrock outages from blocking all agent traffic.

5.  **Test grounding with representative payloads**: If using contextual grounding, validate with
    full A2A JSON payloads, not just extracted text fields.

6.  **Use temporary credentials**: Rotate temporary STS credentials instead of long-lived IAM keys
    for improved security.

## See Also

- [Amazon Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) - AWS documentation

- [ApplyGuardrail API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ApplyGuardrail.html) -
  AWS API documentation

- [Amazon Bedrock Guardrails Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-bedrock-guardrails) - LLM Gateway version

- [A2A v1 PII Detector Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-a2a-v1-pii-detector) - Alternative PII detection
  for A2A v1.0