Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Integrate Automated Reasoning checks in your application

After you deploy your Automated Reasoning policy in a guardrail (see Deploy your Automated Reasoning policy in your application), you can use it at runtime to validate LLM responses and act on the feedback. This page explains how to call the validation API, interpret the findings programmatically, and implement common integration patterns such as rewriting invalid responses and asking clarifying questions.

Automated Reasoning checks operate in detect mode only – they return findings and feedback rather than blocking content. Your application is responsible for deciding what to do with the findings: serve the response, rewrite it, ask for clarification, or fall back to a default behavior.

How Automated Reasoning checks evaluate content

Automated Reasoning checks translate the content that you submit into a logical implication – an "if/then" relationship – and then check that implication against your policy rules. The translation produces two kinds of logical statements:

Automated Reasoning checks decide which statements are premises and which are claims when they translate the content – the split is not taken directly from the input fields. What you control through the API is whether each piece of content enters as user-side input (a question or stated condition) or agent-side input (a response to validate). The query qualifier marks content as user-side; guardContent (or untagged text) marks it as agent-side; groundingSource is ignored by Automated Reasoning checks. The translation then derives the premises and claims from the combined input.

Whether you have to tag content, and how, depends on the API that you use.

Key differences between APIs

Integration overview

At runtime, the integration follows this flow:

User question ──► LLM generates response ──► Validate response
                                                      │
                                            ┌─────────┴─────────┐
                                            │                   │
                                          VALID              Not VALID
                                            │                   │
                                            ▼                   ▼
                                      Serve response     Inspect findings
                                      to user                  │
                                                      ┌────────┴────────┐
                                                      │                 │
                                                 OTHER FINDING     TRANSLATION_
                                                    TYPES       AMBIGUOUS / SATISFIABLE
                                                      │                 │
                                                      ▼                 ▼
                                                 Rewrite using    Ask user for
                                                 AR feedback      clarification
                                                      │                 │
                                                      ▼                 ▼
                                                 Validate again   Validate with
                                                                  clarified input
    

Automated Reasoning findings are returned through any API that supports a Amazon Bedrock Guardrails configuration:

Call ApplyGuardrail with Automated Reasoning checks

ApplyGuardrail evaluates all the content that you pass. Tagging is optional: by default each content block is treated as agent-side (claim) content and validated against your policy rules, which is the simplest integration path. To give Automated Reasoning checks additional context, you can set qualifiers on a content block to mark it as user-side (query) input. Unlike Converse and InvokeModel, ApplyGuardrail does not append a model response for you, so the content you submit must include at least one claim block; otherwise the request returns a ValidationException.

Request structure

Example: Validate an LLM response using the AWS CLI

aws bedrock-runtime apply-guardrail \
  --guardrail-identifier "your-guardrail-id" \
  --guardrail-version "1" \
  --source OUTPUT \
  --content '[
    {
      "text": {
        "text": "User: Am I eligible for parental leave if I have been working here for 2 years full-time?\nAssistant: Yes, you are eligible for parental leave."
      }
    }
  ]'

Example: Validate an LLM response using Python (boto3)

import boto3
import json

bedrock_runtime = boto3.client("bedrock-runtime", region_name="eusc-de-east-1")

response = bedrock_runtime.apply_guardrail(
    guardrailIdentifier="your-guardrail-id",
    guardrailVersion="1",
    source="OUTPUT",
    content=[
        {
            "text": {
                "text": (
                    "User: Am I eligible for parental leave if I have been "
                    "working here for 2 years full-time?\n"
                    "Assistant: Yes, you are eligible for parental leave."
                )
            }
        }
    ],
)

# The AR findings are in the assessments
for assessment in response.get("assessments", []):
    ar_assessment = assessment.get("automatedReasoningPolicy", {})
    findings = ar_assessment.get("findings", [])
    for finding in findings:
        # Each finding is a union — exactly one key is present
        # Possible keys: valid, invalid, satisfiable, impossible,
        #                translationAmbiguous, tooComplex, noTranslations
        print(json.dumps(finding, indent=2, default=str))

Response structure

The ApplyGuardrail response includes an assessments array. Each assessment contains an automatedReasoningPolicy object with a findings array. Each finding is a union type – exactly one of the following keys is present:

For a detailed description of each finding type and its fields, see Findings and validation results.

Call Converse with Automated Reasoning checks

Automated Reasoning checks run on a Converse request only when the request includes at least one guardContent block. A request that sends only plain text does not run Automated Reasoning checks.

Plain text only (Automated Reasoning checks skipped)

If your Converse request uses only plain text blocks (no guardContent blocks), the text is not tagged for guardrail evaluation, so Automated Reasoning checks have nothing to evaluate and are skipped:

{
  "messages": [{"role": "user", "content": [{"text": "Apply a 20% discount to my order"}]}]
}

This request returns automatedReasoningPolicyUnits: 0. Other guardrail policies (content, topic, word, and sensitive information) still evaluate the content; only Automated Reasoning checks are skipped. To run Automated Reasoning checks, use a guardContent block as shown in the next section.

Using guardContent blocks

To run Automated Reasoning checks on Converse, wrap the content you want evaluated in a guardContent block and set its qualifiers. This is how you mark which content is user-side and which is agent-side.

The following table shows how each qualifier marks content for Automated Reasoning checks.

The qualifier sets only whether content is user-side or agent-side; Automated Reasoning checks derive the actual premises and claims when they translate the combined input. A block with no qualifiers specified defaults to guard_content (agent-side). You can specify multiple qualifiers on one block. The precedence order is guard_content > query > grounding_source.

Example: Call Converse with Automated Reasoning qualifiers using the AWS CLI

aws bedrock-runtime converse \
  --model-id "model-id" \
  --guardrail-config '{
    "guardrailIdentifier": "your-guardrail-id",
    "guardrailVersion": "1",
    "trace": "enabled"
  }' \
  --messages '[
    {
      "role": "user",
      "content": [
        {
          "guardContent": {
            "text": {
              "text": "Apply a 20% discount to my order and confirm it is done.",
              "qualifiers": ["query"]
            }
          }
        }
      ]
    }
  ]'

When Automated Reasoning checks run

The following table summarizes whether Automated Reasoning checks run for each Converse request shape. In every case where they run, the model's response is appended as an agent-side (claim) block.

Call InvokeModel with Automated Reasoning checks

How it works

InvokeModel requires two things for Automated Reasoning checks:

The XML tag format is as follows:

<amazon-bedrock-guardrails-QUALIFIER_SUFFIX>text</amazon-bedrock-guardrails-QUALIFIER_SUFFIX>

Where:

Tag roles for Automated Reasoning checks

The qualifier sets only whether the tagged text is user-side or agent-side input; Automated Reasoning checks derive the premises and claims when they translate the combined input. Tag the user prompt with query to give the checks context. The model's output is automatically appended as an agent-side (claim) block, so tagging the prompt with query alone is enough for the checks to run.

Multi-tag precedence and nesting rules

A single text segment can be wrapped in multiple nested tag types. When multiple tags apply to the same content, precedence determines the Automated Reasoning role: guardContent > query > groundingSource. If content is tagged with both guardContent and query, it is treated as a claim.

The following nesting rules apply:

Example: Call InvokeModel with Automated Reasoning tags using the AWS CLI

aws bedrock-runtime invoke-model \
  --model-id "model-id" \
  --guardrail-identifier "your-guardrail-id" \
  --guardrail-version "1" \
  --trace "ENABLED" \
  --cli-binary-format raw-in-base64-out \
  --body '{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 256,
    "amazon-bedrock-guardrailConfig": {
      "tagSuffix": "arp"
    },
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "<amazon-bedrock-guardrails-query_arp>Apply a 20% discount to my order and confirm it is done.</amazon-bedrock-guardrails-query_arp>"
          }
        ]
      }
    ]
  }' \
  output.json

This request returns automatedReasoningPolicyUnits: 1, with Automated Reasoning findings in the trace.

Default behavior (without tags)

The same request without the XML tags uses plain text:

"text": "Apply a 20% discount to my order and confirm it is done."

This request returns automatedReasoningPolicyUnits: 0 – Automated Reasoning checks did not run, and no error is raised. The guardrail still evaluates other policies (content, topic, word, and sensitive information), but Automated Reasoning checks are skipped entirely.

Interpret Automated Reasoning findings at runtime

To act on Automated Reasoning findings programmatically, your application needs to extract the finding type, the translation details, and the supporting or contradicting rules. The following sections explain how to parse each part of a finding.

Determine the finding type

Each finding is a union – exactly one key is present. Check which key exists to determine the finding type:

def get_finding_type(finding):
    """Return the finding type and its data from an AR finding union."""
    for finding_type in [
        "valid", "invalid", "satisfiable", "impossible",
        "translationAmbiguous", "tooComplex", "noTranslations"
    ]:
        if finding_type in finding:
            return finding_type, finding[finding_type]
    return None, None

Read the translation

Most finding types include a translation object that shows how Automated Reasoning checks translated the natural language input into formal logic. The translation contains:

Check untranslatedPremises and untranslatedClaims to understand the scope of the validation. A VALID result only covers the translated claims – untranslated content is not verified.

Read the supporting or contradicting rules

Depending on the finding type, the finding includes rules that explain the result:

These rules and scenarios are the key inputs for the rewriting pattern described in Rewrite invalid responses using AR feedback.

Determine the aggregate result

A single validation request can return multiple findings. To determine the overall result, sort findings by severity and select the worst. The severity order from worst to best is: translationAmbiguous, impossible, invalid, satisfiable, valid.

SEVERITY_ORDER = {
    "tooComplex": 0,
    "translationAmbiguous": 0,
    "impossible": 1,
    "invalid": 2,
    "satisfiable": 3,
    "valid": 4,
    "noTranslations": 5, 
}

def get_aggregate_result(findings):
    """Return the worst finding type from a list of findings."""
    worst = None
    worst_severity = float("inf")
    for finding in findings:
        finding_type, _ = get_finding_type(finding)
        severity = SEVERITY_ORDER.get(finding_type, 0)
        if severity < worst_severity:
            worst_severity = severity
            worst = finding_type
    return worst

Handle validation outcomes in your application

Use the aggregate result to decide what your application does next. The following table summarizes the recommended action for each result type.

Rewrite invalid responses using AR feedback

The most powerful integration pattern for Automated Reasoning checks is the rewriting loop: when a response is invalid or satisfiable, your application constructs a prompt that includes the original response, the specific findings, and the policy rules, then asks the LLM to rewrite the response to be consistent with the policy. The rewritten response is validated again, and the loop continues until the response is valid or a maximum number of iterations is reached.

Rewriting loop flow

LLM generates initial response
         │
         ▼
Validate with ApplyGuardrail ◄──────────────────┐
         │                                       │
         ▼                                       │
   ┌─────┴─────┐                                 │
   │           │                                 │
 VALID     Not VALID                             │
   │           │                                 │
   ▼           ▼                                 │
 Done    Construct rewriting prompt              │
         with findings + rules                   │
              │                                  │
              ▼                                  │
         LLM rewrites response                   │
              │                                  │
              ▼                                  │
         Max iterations? ──── No ────────────────┘
              │
             Yes
              │
              ▼
         Return best response
         with warning
      

Construct the rewriting prompt

The rewriting prompt should include three pieces of information from the AR findings:

Example rewriting prompt template:

The following response was checked against our policy and found to be
{finding_type}.

Original response:
{original_response}

The validation found the following issue:
- Premises (what was understood from the input): {premises}
- Claims (what was asserted): {claims}
- Contradicting rules: {contradicting_rules}

Please rewrite the response so that it is consistent with the policy document. 
Keep the same helpful tone and answer the user's question
accurately based on the rules. If you cannot provide an accurate answer
without more information, explain what additional information is needed.

Rewriting best practices

Ask clarifying questions

When Automated Reasoning checks return translationAmbiguous, satisfiable, or impossible results, the LLM may not have enough information to rewrite the response accurately. In these cases, your application can ask the user for clarification, then incorporate the answers into the next validation attempt.

When to ask for clarification

Clarification pattern

The clarification flow works as follows:

Example: Generate clarifying questions from a satisfiable finding

def generate_clarifying_questions(finding_data, user_question):
    """Ask the LLM to generate clarifying questions from a SATISFIABLE finding."""
    claims_true = json.dumps(
        finding_data.get("claimsTrueScenario", {}), indent=2, default=str
    )
    claims_false = json.dumps(
        finding_data.get("claimsFalseScenario", {}), indent=2, default=str
    )

    prompt = (
        f"A user asked: {user_question}\n\n"
        f"The answer is correct when these conditions hold:\n{claims_true}\n\n"
        f"But incorrect when these conditions hold:\n{claims_false}\n\n"
        f"Generate 1-3 short, specific questions to ask the user to determine "
        f"which conditions apply to their situation. Format each question on "
        f"its own line."
    )

    return generate_response(prompt, "You are a helpful assistant.")

Open-source rewriting chatbot sample

For a complete, production-style implementation of the patterns described on this page, see the Automated Reasoning checks rewriting chatbot on GitHub. This sample application demonstrates:

The sample uses a Python/Flask backend with a React frontend and communicates with Amazon Bedrock for LLM inference and Amazon Bedrock Guardrails for validation through the ApplyGuardrail API.

Build an audit trail

Automated Reasoning findings provide mathematically verifiable proof of validity. For regulated industries and compliance scenarios, this proof is a key differentiator – you can demonstrate that an AI response was verified against specific policy rules with specific variable assignments, not just pattern-matched or probabilistically assessed.

To build an effective audit trail, log the following information for each validation request:

Example: Audit log entry structure

{
  "timestamp": "2025-07-21T14:30:00Z",
  "request_id": "req-abc123",
  "guardrail_id": "your-guardrail-id",
  "guardrail_version": "1",
  "user_question": "Am I eligible for parental leave?",
  "llm_response": "Yes, you are eligible for parental leave.",
  "validation_result": "valid",
  "findings": [
    {
      "type": "valid",
      "premises": "isFullTime = true, tenureMonths = 24",
      "claims": "eligibleForParentalLeave = true",
      "supporting_rules": ["A1B2C3D4E5F6"]
    }
  ],
  "action_taken": "served_response",
  "rewrite_iterations": 0
}