Contact Us 1-800-596-4880
  1. Homepage
  2. Omni Gateway (1.13)
  3. Securing Omni Gateway Instances with Policies
  4. Inbound Policies Directory

  5. A2A v1 Bedrock Guardrails

A2A v1 Bedrock Guardrails Policy

Policy Name

A2A v1 Bedrock Guardrails Policy

Summary

Evaluates A2A v1.0 agent requests and responses against Amazon Bedrock guardrails for content safety, PII detection, and contextual grounding

Category

A2A

First Omni Gateway version available

v1.13.0

Release Notes

A2A v1 Bedrock Guardrails Policy

Returned Status Codes

403 - Forbidden: Content violates guardrail policies

503 - Service Unavailable: Bedrock API call failed (only when fail-open is disabled)

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 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

Element Required Description

Bedrock Runtime Endpoint

Yes

Amazon Bedrock Runtime endpoint URL. Accepts either:

  • Base host: https://bedrock-runtime.us-east-1.amazonaws.com

  • Full ApplyGuardrail URL: https://bedrock-runtime.us-east-2.amazonaws.com/guardrail/<id>/version/<version>/apply

When the full URL is provided, the policy derives the region, guardrail identifier, and guardrail version, unless if you explicitly configure those values.

AWS Credentials

Yes

AWS credentials and region for signing requests to the Bedrock API. See AWS Credentials.

Guardrail Identifier

Conditional

The unique ID of the Bedrock guardrail to apply (for example, paccgfhgnj1dc).

Required unless provided in the Bedrock Runtime Endpoint URL.

Guardrail Version

No

Version of the guardrail to apply.

  • DRAFT (default): Use the working draft version for development and testing.

  • Numeric version (for example, "1", "2"): Use a published version for production deployments.

Required unless provided in the Bedrock Runtime Endpoint URL.

Moderate Request

No

When enabled (default: true), the policy evaluates the entire request body against the guardrail before forwarding to the upstream agent. Rejected requests never reach the agent.

Moderate Response

No

When enabled (default: true), the policy evaluates the entire unary response body against the guardrail before returning to the client. Rejected responses return a 403 error code. Streaming responses (text/event-stream) aren’t moderated and pass through unchanged.

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.

Element Required Description

Access Key ID

Yes

AWS access key ID, either:

  • Long-lived IAM user credentials (starting with AKIA)

  • Temporary credentials from STS or SSO (starting with ASIA)

Secret Access Key

Yes

AWS secret access key corresponding to the Access Key ID.

Session Token

Conditional

Required when using temporary credentials (Access Key ID starting with ASIA). Leave empty for long-lived IAM user credentials.

Region

Conditional

AWS region of the Bedrock Runtime endpoint (for example, us-east-1).

Set explicitly for custom domains or VPC endpoints. Optional when the region is provided in the Bedrock Runtime Endpoint host.

Advanced Configuration

Element Required Description

Grounding Source Selector

No

DataWeave expression that extracts the reference text for contextual grounding from the request body.

Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with Grounding Query Selector.

Example for JSON-RPC: #[payload.params.message.metadata.context]

Example for HTTP+JSON: #[payload.message.metadata.context]

See Contextual Grounding for more information.

Grounding Query Selector

No

DataWeave expression that extracts the user query for contextual grounding from the request body.

Required only when the AWS guardrail has contextual grounding enabled. Must be configured together with Grounding Source Selector.

Example for JSON-RPC: #[payload.params.message.parts[0].text]

Example for HTTP+JSON: #[payload.message.parts[0].text]

See Contextual Grounding for more information.

Max Payload Bytes

No

Maximum request or response body size (in bytes) sent to Bedrock.

  • Default: 25000

  • Range: 1024 - 25000

The ApplyGuardrail 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).

Sampling Rate Percent

No

Percentage of sessions to sample for moderation (0-100).

  • Default: 100 (moderate every request)

  • 50: Moderate half of sessions

  • 0: Disable moderation

Sampling is deterministic per session. The same session is always or never sampled.

Session Key Selector

No

DataWeave expression that extracts the session identifier used for sampling.

By default, the key selector resolves to A2A v1.0 contextId (conversation-scoped identifier). For single messages that aren’t part of an ongoing A2A conversation (one-shot sends), the key selector resolves to messageId.

Only used when Sampling Rate Percent is less than 100.

API Timeout (ms)

No

Timeout in milliseconds for calls to the Bedrock ApplyGuardrail API.

  • Default: 5000

  • Range: 1000 - 30000

Fail Open

No

Determines behavior when the Bedrock API call fails or times out:

  • Disabled (default): Rejects the request with HTTP 503

  • Enabled: Allows traffic to proceed without moderation (fail-open mode)

When enabled, failures are logged and the service_unavailable reason is emitted in response headers for observability.

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.

      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:

    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:

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

Response Headers

Every moderated response includes observability headers:

Header Values Description

x-flex-bedrock-guardrails-action

allow, reject, skip

Final moderation decision. reject indicates content violated one or more policies. skip indicates the request wasn’t moderated (sampling, gRPC, or streaming).

x-flex-bedrock-guardrails-phase

request, response

Which phase performed the moderation. Useful for understanding whether the request or response was blocked.

x-flex-bedrock-guardrails-reason

content_filter, denied_topic, word_filter, pii, grounding, payload_too_large, service_unavailable, sampled_out, unsupported_transport_v1

Why the content was rejected or skipped. Multiple reasons are comma-separated if the content violated multiple policies.

Example Configurations

Minimal Configuration — Request and Response Moderation

- 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)

- 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)

- 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)

- 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)

- 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

Condition Status Code Description

Content violates guardrail (request phase)

403 Forbidden

Request blocked before reaching the agent. Response body contains A2A error envelope with reason details.

Content violates guardrail (response phase)

403 Forbidden

Response blocked and replaced with A2A error envelope. Original response is not returned.

Bedrock API failure (fail-open disabled)

503 Service Unavailable

Bedrock service error or timeout with fail-open disabled. Traffic is blocked.

Bedrock API failure (fail-open enabled)

Varies

Traffic proceeds unmoderated. Observability headers indicate service_unavailable.

Payload exceeds size limit (fail-open disabled)

403 Forbidden

Payload larger than maxPayloadBytes. Request blocked.

Payload exceeds size limit (fail-open enabled)

Varies

Oversized payload passes through unmoderated. Observability headers indicate payload_too_large.

Sampled-out session

Varies

Session not selected for moderation. Traffic passes through with sampled_out reason header.

gRPC traffic

Varies

gRPC traffic passes through unmoderated with unsupported_transport_v1 reason header.

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