As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Integre verificações automatizadas de raciocínio em seu aplicativo

Depois de implantar sua política de raciocínio automatizado em uma grade de proteção (consulteImplantar uma política de raciocínio automatizado em uma aplicação), você pode usá-la em tempo de execução para validar as respostas do LLM e agir de acordo com o feedback. Esta página explica como chamar a API de validação, interpretar as descobertas de forma programática e implementar padrões de integração comuns, como reescrever respostas inválidas e fazer perguntas esclarecedoras.

As verificações automatizadas de raciocínio operam apenas no modo de detecção — elas retornam descobertas e feedback em vez de bloquear o conteúdo. Seu aplicativo é responsável por decidir o que fazer com as descobertas: fornecer a resposta, reescrevê-la, pedir esclarecimentos ou retornar a um comportamento padrão.

Como as verificações automatizadas de raciocínio avaliam o conteúdo

As verificações automatizadas de raciocínio traduzem o conteúdo que você envia em uma implicação lógica — uma relação if/then "” — e, em seguida, comparam essa implicação com base nas regras de sua política. A tradução produz dois tipos de declarações lógicas:

As verificações automatizadas de raciocínio decidem quais declarações são premissas e quais são afirmações quando traduzem o conteúdo — a divisão não é obtida diretamente dos campos de entrada. O que você controla por meio da API é se cada parte do conteúdo é inserida como entrada do usuário (uma pergunta ou condição declarada) ou entrada do agente (uma resposta para validar). O query qualificador marca o conteúdo como do lado do usuário; guardContent (ou texto não marcado) o marca como do agente; groundingSource é ignorado pelas verificações de raciocínio automatizado. A tradução então deriva as premissas e reivindicações da entrada combinada.

Se você precisa marcar o conteúdo e como, depende da API que você usa.

Principais diferenças entre as APIs

Visão geral da integração

Em tempo de execução, a integração segue esse fluxo:

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
    

As descobertas do Automated Reasoning são retornadas por meio de qualquer API que ofereça suporte a uma configuração do Amazon Bedrock Guardrails:

Ligue ApplyGuardrail com verificações automatizadas de raciocínio

ApplyGuardrailavalia todo o conteúdo que você passa. A marcação é opcional: por padrão, cada bloco de conteúdo é tratado como conteúdo do lado do agente (reivindicação) e validado de acordo com suas regras de política, que é o caminho de integração mais simples. Para dar contexto adicional às verificações de raciocínio automatizado, você pode definir qualifiers um bloco de conteúdo para marcá-lo como entrada do lado do usuário (query). Ao contrário de Converse eInvokeModel, ApplyGuardrail não acrescenta um modelo de resposta para você, então o conteúdo enviado deve incluir pelo menos um bloco de reivindicação; caso contrário, a solicitação retornará a. ValidationException

Estrutura de solicitações

Exemplo: Validar uma resposta LLM usando o 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."
      }
    }
  ]'

Exemplo: Validar uma resposta LLM usando Python (boto3)

import boto3
import json

bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-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))

Estrutura de respostas

A ApplyGuardrail resposta inclui uma assessments matriz. Cada avaliação contém um automatedReasoningPolicy objeto com uma findings matriz. Cada descoberta é um tipo de união — exatamente uma das seguintes chaves está presente:

Para obter uma descrição detalhada de cada tipo de descoberta e seus campos, consulteDescobertas e resultados de validação.

Ligue para a Converse com verificações automatizadas de raciocínio

As verificações automatizadas de raciocínio são executadas em uma Converse solicitação somente quando a solicitação inclui pelo menos um guardContent bloco. Uma solicitação que envia apenas mensagens simples text não executa verificações de raciocínio automatizado.

Somente texto simples (verificações de raciocínio automatizado ignoradas)

Se sua Converse solicitação usa apenas text blocos simples (sem guardContent blocos), o texto não é marcado para avaliação de proteção, portanto, as verificações de raciocínio automatizado não têm nada para avaliar e são ignoradas:

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

Essa solicitação é retornadaautomatedReasoningPolicyUnits: 0. Outras políticas de proteção (conteúdo, tópico, palavras e informações confidenciais) ainda avaliam o conteúdo; somente as verificações automatizadas de raciocínio são ignoradas. Para executar verificações de raciocínio automatizado, use um guardContent bloco conforme mostrado na próxima seção.

Usando blocos GuardContent

Para executar verificações de raciocínio automatizadoConverse, agrupe o conteúdo que você deseja avaliar em um guardContent bloco e defina seus qualificadores. É assim que você marca qual conteúdo é do lado do usuário e qual é do lado do agente.

A tabela a seguir mostra como cada qualificador marca o conteúdo para verificações de raciocínio automatizado.

O qualificador define apenas se o conteúdo é do lado do usuário ou do agente; as verificações automatizadas de raciocínio derivam as premissas e afirmações reais quando traduzem a entrada combinada. Um bloco sem qualificadores especificados é padronizado para guard_content (lado do agente). Você pode especificar vários qualificadores em um bloco. A ordem de precedência éguard_content > query > grounding_source.

Exemplo: Ligue para a Converse com qualificadores de raciocínio automatizado usando o 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"]
            }
          }
        }
      ]
    }
  ]'

Quando as verificações de raciocínio automatizado são executadas

A tabela a seguir resume se as verificações de raciocínio automatizado são executadas para cada formato de Converse solicitação. Em todos os casos em que são executados, a resposta do modelo é anexada como um bloco do lado do agente (reivindicação).

Ligue InvokeModel com verificações automatizadas de raciocínio

Como funciona

InvokeModelrequer duas coisas para verificações automatizadas de raciocínio:

O formato da tag XML é o seguinte:

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

Em que:

Funções de tag para verificações automatizadas de raciocínio

O qualificador define somente se o texto marcado é uma entrada do lado do usuário ou do agente; as verificações de raciocínio automatizado derivam as premissas e as afirmações quando traduzem a entrada combinada. Marque o prompt do usuário com query para dar contexto às verificações. A saída do modelo é anexada automaticamente como um bloco do lado do agente (declaração), portanto, marcar o prompt query sozinho é suficiente para que as verificações sejam executadas.

Multi-tag regras de precedência e aninhamento

Um único segmento de texto pode ser encapsulado em vários tipos de tag aninhados. Quando várias tags se aplicam ao mesmo conteúdo, a precedência determina a função do raciocínio automatizado:. guardContent > query > groundingSource Se o conteúdo estiver marcado com ambos guardContentquery, ele será tratado como uma reivindicação.

As seguintes regras de aninhamento se aplicam:

Exemplo: Ligue InvokeModel com tags de raciocínio automatizado usando o 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

Essa solicitação retornaautomatedReasoningPolicyUnits: 1, com as descobertas do raciocínio automatizado no rastreamento.

Comportamento padrão (sem tags)

A mesma solicitação sem as tags XML usa texto simples:

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

Essa solicitação retorna automatedReasoningPolicyUnits: 0 — As verificações automatizadas de raciocínio não foram executadas e nenhum erro foi gerado. O guardrail ainda avalia outras políticas (conteúdo, tópico, palavra e informações confidenciais), mas as verificações automatizadas de raciocínio são totalmente ignoradas.

Interprete as descobertas do raciocínio automatizado em tempo de execução

Para agir programaticamente com base nas descobertas do Raciocínio Automatizado, seu aplicativo precisa extrair o tipo de descoberta, os detalhes da tradução e as regras de apoio ou contraditórias. As seções a seguir explicam como analisar cada parte de uma descoberta.

Determine o tipo de descoberta

Cada descoberta é uma união — exatamente uma chave está presente. Verifique qual chave existe para determinar o tipo de descoberta:

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

Leia a tradução

A maioria dos tipos de descoberta inclui um translation objeto que mostra como as verificações de raciocínio automatizado traduziram a entrada da linguagem natural em lógica formal. A tradução contém:

Verifique untranslatedPremises e untranslatedClaims entenda o escopo da validação. Um VALID resultado abrange apenas as declarações traduzidas — o conteúdo não traduzido não é verificado.

Leia as regras de apoio ou contraditórias

Dependendo do tipo de descoberta, a descoberta inclui regras que explicam o resultado:

Essas regras e cenários são as principais entradas para o padrão de reescrita descrito em. Reescreva respostas inválidas usando feedback de AR

Determine o resultado agregado

Uma única solicitação de validação pode retornar várias descobertas. Para determinar o resultado geral, classifique as descobertas por gravidade e selecione a pior. A ordem de severidade do pior para o melhor é: translationAmbiguousimpossible,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

Gerencie os resultados da validação em seu aplicativo

Use o resultado agregado para decidir o que seu aplicativo fará a seguir. A tabela a seguir resume a ação recomendada para cada tipo de resultado.

Reescreva respostas inválidas usando feedback de AR

O padrão de integração mais poderoso para verificações de raciocínio automatizado é o ciclo de reescrita: quando uma resposta é invalid ousatisfiable, seu aplicativo cria um prompt que inclui a resposta original, as descobertas específicas e as regras da política e, em seguida, solicita que o LLM reescreva a resposta para que seja consistente com a política. A resposta reescrita é validada novamente e o loop continua até que a resposta seja atingida valid ou o número máximo de iterações seja atingido.

Reescrevendo o fluxo do loop

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
      

Construa o prompt de reescrita

A solicitação de reescrita deve incluir três informações das descobertas do AR:

Exemplo de modelo de solicitação de reescrita:

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.

Reescrevendo as melhores práticas

Faça perguntas esclarecedoras

Quando as verificações de raciocínio automatizado retornam translationAmbiguous ou impossible resultam, o LLM pode não ter informações suficientes para reescrever a resposta com precisão. satisfiable Nesses casos, seu aplicativo pode pedir esclarecimentos ao usuário e, em seguida, incorporar as respostas na próxima tentativa de validação.

Quando pedir esclarecimentos

Padrão de esclarecimento

O fluxo de esclarecimento funciona da seguinte forma:

Exemplo: gerar perguntas esclarecedoras a partir de uma descoberta satisfiable

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 reescrevendo amostra de chatbot

Para uma implementação completa e em estilo de produção dos padrões descritos nesta página, consulte as verificações de raciocínio automatizado que reescrevem o chatbot em. GitHub Esse exemplo de aplicativo demonstra:

A amostra usa um Python/Flask back-end com um front-end React e se comunica com o Amazon Bedrock para inferência do LLM e com o Amazon Bedrock Guardrails para validação por meio da API. ApplyGuardrail

Crie uma trilha de auditoria

As descobertas do raciocínio automatizado fornecem prova de validade matematicamente verificável. Para setores regulamentados e cenários de conformidade, essa prova é um diferencial importante: você pode demonstrar que uma resposta de IA foi verificada em relação a regras de política específicas com atribuições de variáveis específicas, não apenas com correspondência de padrões ou avaliada probabilisticamente.

Para criar uma trilha de auditoria eficaz, registre as seguintes informações para cada solicitação de validação:

Exemplo: estrutura de entrada do registro de auditoria

{
  "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
}