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.

Integration overview

At runtime, the integration follows this flow:

User question ──► LLM generates response ──► ApplyGuardrail validates 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:

This page focuses on the ApplyGuardrail API because it provides the most flexibility for implementing the rewriting and clarification patterns described below. For information about using guardrails with the other APIs, see Use a guardrail.

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.

Call ApplyGuardrail with Automated Reasoning checks

Use the ApplyGuardrail API to validate content against your guardrail. The API accepts one or more content blocks and returns an assessment that includes Automated Reasoning findings.

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.

Interpret AR 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: TRANSLATION_AMBIGUOUS, INVALID, IMPOSSIBLE, SATISFIABLE, NO_TRANSLATIONS, VALID, TOO_COMPLEX.

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

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

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
}