Usa la CLI di Kiro con una politica di ragionamento automatizzato - Amazon Bedrock
PrerequisitiNozioni di baseRisolvere i problemi relativi alle politicheInteragire con una politicaModifica o revisione della tua politicaRisolvi i test non riuscitiFasi successiveRichiesta contestuale dell'API della politica di ragionamento automatico

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Usa la CLI di Kiro con una politica di ragionamento automatizzato

Puoi utilizzare la CLI di Kiro per porre domande sulle tue politiche di ragionamento automatico, comprendere il comportamento delle varie regole e richiedere modifiche che risolvano i test non riusciti o le ambiguità nella politica stessa. La CLI di Kiro è particolarmente utile per il flusso di lavoro di perfezionamento iterativo descritto Risolvi i problemi e perfeziona la tua politica di ragionamento automatico in perché può caricare la definizione della politica, analizzare i risultati dei test e applicare annotazioni tramite conversazioni in linguaggio naturale.

Prerequisiti

Per utilizzare la CLI di Kiro con le tue politiche di ragionamento automatico, devi prima completare i seguenti passaggi:

  • Installa l'ultima versione di Kiro CLI.

  • Installazione della versione più recente della AWS CLI.

  • Crea una politica di ragionamento automatizzato utilizzando un documento tramite la console o. APIs Per iniziare rapidamente, utilizza la policy Homework di esempio integrata nella console. Per ulteriori informazioni, consulta Creare una policy di ragionamento automatico.

  • Acquisisci familiarità con i concetti dei controlli di ragionamento automatico, in particolare le politiche, le regole, le variabili e i risultati. Per ulteriori informazioni, consulta Il ragionamento automatizzato controlla i concetti.

  • Copia il contenuto del prompt contestuale fornito Richiesta contestuale dell'API della politica di ragionamento automatico e salvalo in un file Markdown nella cartella del progetto. Questo prompt aiuta la CLI di Kiro a utilizzare il piano di controllo della policy di Automated Reasoning e a testare correttamente l'API.

Nota

Per gli esempi rapidi riportati di seguito, utilizziamo l'esempio di politica Homework. Le istruzioni dovrebbero funzionare altrettanto bene con altre politiche, basta cambiare l'argomento evidenziato.

Nota

Le policy di ragionamento automatizzato possono essere complesse e richiedono la CLI di Kiro per ragionare attraverso costrutti logici complessi. Per prestazioni ottimali, consigliamo di utilizzare versioni più grandi LLMs come Anthropic Sonnet 4.5. Per cambiare modello nella CLI di Kiro, usa /model il comando.

Nozioni di base

È necessario l'ARN della policy di ragionamento automatico che hai creato per avviare il flusso di lavoro con Kiro CLI.

  1. Utilizzando la console, apri la tua politica di ragionamento automatico e dalla pagina Panoramica della politica, apri la scheda dei dettagli della politica.

  2. Nella scheda Dettagli della politica, trova l'ARN della politica e copialo negli appunti.

  3. Utilizzando il terminale, avvia una sessione CLI di Kiro con il seguente comando:

    kiro-cli

  4. Al primo prompt, chiedi a Kiro di cercare il file Markdown delle istruzioni che hai copiato da questa pagina come parte dei prerequisiti. Esempio:

    We will be using Automated Reasoning checks control plane APIs. I have saved an instructions file called your_file_name.md in this folder. Read this file as it will give you the context you need to work with the APIs.

  5. Dopo che la CLI di Kiro ha caricato e compreso i APIs controlli di ragionamento automatico, chiedigli di caricare l'ultima versione della tua policy e iniziare a esplorarla. Usa una variante del seguente prompt con l'ARN che hai copiato:

    Load the policy assets for the latest build of the policy with ARN YOUR_POLICY_ARN. Make sure you understand the policy with all its rules and variables. Give a high-level description of the policy and the type of content it is capable of validating.

A questo punto, la CLI di Kiro dovrebbe fornirti una breve descrizione delle regole e delle variabili della policy. La CLI di Kiro dovrebbe anche caricare il rapporto sulla qualità delle politiche e riepilogare problemi come tipi e variabili non utilizzati.

Risolvere i problemi relativi alle politiche

Puoi usare la CLI di Kiro per risolvere i problemi relativi alle policy segnalati nel report sulla policy. Innanzitutto, chiedi a Kiro di fornirti un riepilogo del rapporto sulla qualità:

Can you give me a summary of the quality report for this policy?

Il rapporto sulla qualità include un elenco delle variabili non utilizzate, delle regole in conflitto e delle regole disgiunte e di altri potenziali problemi relativi alla politica. Per ulteriori informazioni sull'interpretazione del rapporto sulla qualità, vedere. Utilizza il rapporto sulla qualità

Le regole in conflitto faranno sì che la politica risponda a tutte le richieste IMPOSSIBLE di convalida. Per ulteriori informazioni sulle regole in conflitto e su come risolverle, consulta. Conflitti nella politica Puoi chiedere alla CLI di Kiro di spiegare il conflitto e proporre una soluzione:

Can you look at the conflicting rules, explain how they are used in the policy, why they conflict, and suggest a change such as deleting one of the rules or merging the logic from the two into a single rule?

Le variabili non utilizzate possono far sì che i risultati della convalida restituiscano risultati. TRANSLATION_AMBIGUOUS Per ulteriori informazioni sul motivo per cui le variabili non utilizzate causano problemi, vedere. Variabili non utilizzate Puoi chiedere a Kiro CLI di aiutarti con questo problema:

I see the quality report lists some unused variables, can you get rid of them?

Allo stesso modo, variabili ambigue che sono semanticamente simili possono far sì che i risultati della convalida restituiscano risultati. TRANSLATION_AMBIGUOUS Per ulteriori informazioni sulle variabili sovrapposte e su come correggerle, consulta e. Variabili sovrapposte Definizioni di variabili sovrapposte Puoi chiedere a Kiro CLI di aiutarti con questo problema:

Automated Reasoning checks translate input natural language into logical statements that use the schema of variables from the policy. Variables that are semantically similar - ambiguous - can cause issues with inconsistent translations. Can you take a look at the schema of variables and help me identify variables that have potentially overlapping meanings? If you find any, suggest changes like removing one of them or merging them. Variable changes are also likely to require corresponding rule changes.
Nota

Dopo aver elaborato alcune modifiche, la CLI di Kiro chiederà la conferma per applicarle. A questo punto, puoi utilizzare l'interfaccia utente di Bedrock Console per esaminare le modifiche proposte in una schermata differenziale. Se usi la console per rivedere e approvare le modifiche, non dimenticare di dire a Kiro CLI di ricaricare l'ultima build della definizione della policy.

Interagire con una politica

Puoi usare la CLI di Kiro per esplorare la tua politica. Ad esempio, potresti chiedere alla CLI di Kiro di riepilogare le regole politiche relative a un'area specifica. Utilizzando la politica dei compiti di esempio come esempio, potresti chiedere alla CLI di Kiro di parlarti delle regole che limitano specificamente i compiti di matematica:

Can you tell me about the rules that constrain math homework? Explain the rules themselves and how they fit in the broader policy.

Puoi anche usare la CLI di Kiro per aggiungere funzionalità alla policy. Le politiche di ragionamento automatico spesso aggirano alcune variabili di output chiave che catturano l'intento dell'utente. Ad esempio, la politica di invio dei compiti di esempio utilizza una isSubmissionAcceptable variabile come output delle sue regole. Puoi usare la CLI di Kiro per modificare la policy e acquisire altre possibili domande degli utenti. Quando aggiungi nuove regole, segui le migliori pratiche descritte inLe migliori pratiche relative alla politica di ragionamento automatico, in particolare. Utilizza le implicazioni (=>) per strutturare le regole

Modifica o revisione della tua politica

Puoi chiedere alla CLI di Kiro se la policy è in grado di convalidare domande specifiche dei tuoi utenti. Ad esempio, la politica dei compiti si concentra sulla determinazione se l'invio di un compito è accettabile. Puoi aspettarti una risposta positiva dalla CLI di Kiro con questa domanda:

Can this policy validate answers about whether homework submissions are acceptable?

Se chiedi di ritardare l'invio dei compiti nella policy Homework di esempio, la CLI di Kiro spiegherà che la politica non è in grado di rispondere a queste domande:

Can this policy validate answers about permissible delays in homework submissions?

La CLI di Kiro spiegherà cosa può e non può fare la policy:

> Yes, but with limitations. The policy can validate whether a late submission is acceptable, but it cannot answer general questions about permissible delays.

What it CAN validate:
- Whether a specific late submission is acceptable given the circumstances
- Example: "Student submitted 2 days late with a doctor's note because they were sick before the deadline" → The policy will determine if this is acceptable (it would be)

What it CANNOT validate:
- General questions like "How many days late can a student submit homework?"
- Questions about delay policies without specific submission details
- Hypothetical scenarios without concrete variable values

The late submission logic:
The policy allows late submissions (submissionDate > 0) ONLY if:
1. The student has a valid doctor's note (hasDoctorNote = true), AND
2. The student was sick before the original deadline (wasSickPriorToDeadline = true)

Without both conditions met, any submission after the due date (submissionDate > 0) is automatically rejected.

So it's designed to validate specific submission instances against the rules, not to answer policy interpretation questions.

Quando scopri qualcosa che la policy non può fare, puoi chiedere a Kiro CLI di aggiornare la policy per acquisire queste informazioni usando il seguente prompt:

I would like the policy to also validate answers about by how many days homework submissions can be delayed. Homework submissions accompanied by a doctor note can be up to 7 days late. Suggest the necessary variables and rules to capture these new questions.

In risposta a questa richiesta, la CLI di Kiro suggerirà una serie di variabili e regole che possono essere aggiunte alla policy per convalidare il nuovo tipo di domande. Esamina i suggerimenti e se sono in linea con le tue intenzioni, puoi indicare alla CLI di Kiro di utilizzare l' APIs annotazione dei controlli di ragionamento automatico per apportare queste modifiche alla politica:

Looks good. Can you use the annotation APIs to submit these changes to the policy.

Una volta che la CLI di Kiro conferma che le annotazioni sono pronte, puoi aprire la policy nella console per rivedere le annotazioni. Se le annotazioni sono corrette, scegli Applica annotazioni.

Dopo aver applicato le annotazioni, chiedi a Kiro CLI di ricaricare l'ultima build della policy per assicurarti che Kiro CLI funzioni con una copia corrente:

I applied the annotations. Reload the latest build of the policy.

Risolvi i test non riusciti

Un buon modo per verificare che la politica di ragionamento automatico sia in grado di convalidare il linguaggio naturale generato dall'applicazione consiste nell'utilizzare i test. Dopo aver creato le domande e risposte dei test con i risultati attesi, puoi utilizzare la CLI di Kiro per capire perché un test non ha restituito il risultato previsto e modificare la policy. Per ulteriori informazioni sulla creazione e l'esecuzione dei test, consulta. Testare una policy di ragionamento automatico Per un approccio sistematico alla diagnosi degli errori dei test senza la CLI di Kiro, vedere. Risolvi i problemi e perfeziona la tua politica di ragionamento automatico

  1. Come primo passo, chiedi alla CLI di Kiro di caricare il test fallito e spiega perché non restituisce il risultato previsto in base alla definizione della policy. Usa la console o copia APIs l'ID del test per il test non riuscito. Nella console, l'ID del test è disponibile sia nella tabella che elenca i test sia nella pagina dei dettagli di ogni test.

    The test with ID YOUR_TEST_ID is not returning the expected result. Can you load the test definition and findings, look at the policy definition, and explain why this test is failing.

  2. La spiegazione fornita dalla CLI di Kiro ti indicherà se la policy sta facendo la cosa giusta (e dovresti modificare il risultato previsto per il test) o se la policy è sbagliata. Puoi chiedere alla CLI di Kiro di suggerire modifiche alla politica per garantire che il test restituisca il risultato previsto:

    Can you suggest changes to the policy to ensure this test returns the expected result? Explain why you are suggesting these changes. Only create rules in if/then format.
    Nota

    Quando suggerisce modifiche alle regole, la CLI di Kiro può cercare di adattarsi eccessivamente all'esempio specifico e creare regole che non sono utili in altri casi d'uso. Controlla l'output del test e fornisci indicazioni sulla CLI di Kiro per focalizzarlo sul problema giusto. Per indicazioni su come scrivere regole efficaci, consulta. Le migliori pratiche relative alla politica di ragionamento automatico

    Ad esempio, chiedendo a Kiro di modificare la policy Homework di esempio in modo che il SATISFIABLE test venga restituitoVALID, potrebbe indurre Kiro a suggerire di aggiungere assiomi alla policy per far sì che il test venga sempre superato, ad esempio creando una regola che dica (false isHomeworkSubmissionAcceptable) Ciò garantirebbe che il valore sia sempre falso. Sebbene ciò risolva tecnicamente il test problematico, è dannoso per la funzionalità complessiva della politica. Analizzando gli scenari restituiti dal risultato del SATISFIABLE test, puoi vedere che forniscono a Kiro CLI una guida migliore per creare una nuova regola che copra solo i vincoli specificati nel test o aggiornare le regole esistenti per controllare solo i vincoli del test:

  3. Quando sei soddisfatto delle modifiche suggerite, chiedi alla CLI di Kiro di inviare le annotazioni e rivederle utilizzando l'interfaccia utente della console:

    Looks good. Can you start a build workflow to apply these changes to the policy.

  4. Dopo aver applicato le modifiche e passato al successivo test non riuscito, chiedi alla CLI di Kiro di ricaricare l'ultima build della policy:

    I applied the changes. Reload the latest build of the policy.

Fasi successive

Quando sei soddisfatto della policy di Automated Reasoning, puoi distribuirla per utilizzarla in Amazon Bedrock Guardrails. Per ulteriori informazioni, consulta Implementare la policy di ragionamento automatico nell’applicazione.

Dopo aver implementato la policy, consulta le indicazioni sull'utilizzo dei controlli di ragionamento automatico in fase di esecuzione Integra i controlli di ragionamento automatizzato nella tua applicazione per convalidare le risposte LLM e agire in base al feedback.

Richiesta contestuale dell'API della politica di ragionamento automatico

Copia il seguente contenuto e salvalo in un file Markdown nella cartella del progetto per Kiro CLI. Questo prompt fornisce alla CLI di Kiro il contesto necessario per funzionare correttamente con la politica di ragionamento automatico. APIs 

# Automated Reasoning Policy APIs and Workflows

## Table of Contents

### Core APIs
- Policy Management
- Policy Versions
- Build Workflows
- Test Management
- Annotations & Scenarios

### Build Workflow Types
- INGEST_CONTENT Workflow
- REFINE_POLICY Workflow
- IMPORT_POLICY Workflow
- GENERATE_FIDELITY_REPORT Workflow

### Annotation Type Reference
- Type Management Annotations
- Variable Management Annotations
- Rule Management Annotations
- Natural Language Rule Creation
- Feedback-Based Updates

### Common Workflows
1. Getting Started (New Policy)
2. Building Policy from Document
3. Policy Development Cycle
4. REFINE_POLICY Workflow (Annotation-Based)

### Testing Workflow
1. Primary Approach: Scenarios API (Recommended)
2. Secondary Approach: Test Cases (User Experience)
3. Test Result Analysis and Troubleshooting

### Build Workflow Monitoring
- Check Build Status
- List Build History
- Best Practice: Clean Build Management
- Troubleshooting Build Failures

### Build Workflow Assets
- Asset Types
- Understanding Conflicting Rules
- Understanding Disjoint Rule Sets
- Advanced Quality Report Analysis

### Additional Topics
- Policy Version Export
- Key Concepts
- Important Format Requirements
- Policy Modeling Best Practices
- ARN Formats

## Core APIs

### Policy Management
- `create-automated-reasoning-policy` - Create initial policy (returns policy ARN). Supports optional `--description`, `--kms-key-id` (for encryption with a customer managed AWS KMS key), `--tags` (up to 200 tags), and `--client-request-token` (idempotency token).
- `get-automated-reasoning-policy` - Retrieve policy (DRAFT version by default with unversioned ARN). Returns `policyId`, `definitionHash`, and `kmsKeyArn` (if a KMS key was provided at creation).
- `update-automated-reasoning-policy` - Update DRAFT policy with new definition. Accepts optional `--name` and `--description` updates alongside `--policy-definition` (required).
- `delete-automated-reasoning-policy` - Delete policy. Supports optional `--force` flag: when true, deletes the policy and all its artifacts (versions, test cases, test results) without validation; when false (default), validates that all artifacts have been deleted first.
- `list-automated-reasoning-policies` - List all policies. Supports optional `--policy-arn` filter to list only versions of a specific policy.

### Policy Versions
- `create-automated-reasoning-policy-version` - Snapshot DRAFT into numbered version. Requires `--last-updated-definition-hash` (concurrency token from get/create/update response). Supports optional `--tags` (up to 200 tags) and `--client-request-token`.
- `export-automated-reasoning-policy-version` - Export specific policy version definition including rules, variables, and types.

### Build Workflows
- `start-automated-reasoning-policy-build-workflow` - Start build process. Valid `--build-workflow-type` values: `INGEST_CONTENT`, `REFINE_POLICY`, `IMPORT_POLICY`, `GENERATE_FIDELITY_REPORT`. Supports optional `--client-request-token` (idempotency token, passed as header).
- `get-automated-reasoning-policy-build-workflow` - Get build workflow status. Status values: `SCHEDULED`, `CANCEL_REQUESTED`, `PREPROCESSING`, `BUILDING`, `TESTING`, `COMPLETED`, `FAILED`, `CANCELLED`.
- `cancel-automated-reasoning-policy-build-workflow` - Cancel running build
- `delete-automated-reasoning-policy-build-workflow` - Delete build workflow. Requires `--last-updated-at` (concurrency token timestamp).
- `list-automated-reasoning-policy-build-workflows` - List build workflows
- `get-automated-reasoning-policy-build-workflow-result-assets` - Get compiled policy assets. Requires `--asset-type`. Valid asset types: `BUILD_LOG`, `QUALITY_REPORT`, `POLICY_DEFINITION`, `GENERATED_TEST_CASES`, `POLICY_SCENARIOS`, `FIDELITY_REPORT`, `ASSET_MANIFEST`, `SOURCE_DOCUMENT`. Supports optional `--asset-id` (required when retrieving `SOURCE_DOCUMENT` assets if multiple source documents were used; obtain from the `ASSET_MANIFEST`).

### Test Management
- `create-automated-reasoning-policy-test-case` - Create test case. Requires `--guard-content` and `--expected-aggregated-findings-result`. Supports optional `--query-content`, `--confidence-threshold` (Double, 0 to 1, minimum confidence level for logic validation), and `--client-request-token`.
- `get-automated-reasoning-policy-test-case` - Get test case details (includes `confidenceThreshold` if set)
- `update-automated-reasoning-policy-test-case` - Update test case. Requires `--guard-content`, `--expected-aggregated-findings-result`, and `--last-updated-at` (concurrency token). Supports optional `--query-content`, `--confidence-threshold`, and `--client-request-token`.
- `delete-automated-reasoning-policy-test-case` - Delete test case. Requires `--last-updated-at` (concurrency token).
- `list-automated-reasoning-policy-test-cases` - List test cases
- `start-automated-reasoning-policy-test-workflow` - Run tests against a completed build. Requires `--build-workflow-id` (the build workflow must show COMPLETED status). Supports optional `--test-case-ids` (array of test case IDs to run; if not provided, all tests for the policy are run) and `--client-request-token`.
- `get-automated-reasoning-policy-test-result` - Get test result for a specific test case. Requires `--build-workflow-id` and `--test-case-id`.
- `list-automated-reasoning-policy-test-results` - List test results. Requires `--build-workflow-id`.

### Annotations & Scenarios
- `get-automated-reasoning-policy-annotations` - Get policy annotations for a build workflow. Requires `--build-workflow-id`. Returns `annotations`, `annotationSetHash` (concurrency token), `buildWorkflowId`, `name`, `policyArn`, and `updatedAt`.
- `update-automated-reasoning-policy-annotations` - Update annotations for a build workflow. Requires `--build-workflow-id`, `--annotations` (array of annotation objects, max 10), and `--last-updated-annotation-set-hash` (concurrency token from get-annotations response). Returns updated `annotationSetHash`.
- `get-automated-reasoning-policy-next-scenario` - Get next test scenario

**Important**: Do NOT use `get-automated-reasoning-policy-annotations` or 
`update-automated-reasoning-policy-annotations` for the `REFINE_POLICY` workflow. Annotations are passed directly in the `start-automated-reasoning-policy-build-workflow` call.

## Build Workflow Types

1. **INGEST_CONTENT** - Process documents to create/extract policy rules
2. **REFINE_POLICY** - Refine and improve existing policies using annotations
3. **IMPORT_POLICY** - Import policies from external sources
4. **GENERATE_FIDELITY_REPORT** - Generate a fidelity report for the policy

### INGEST_CONTENT Workflow
- **Purpose**: Extract policy rules from documents (PDF/TXT)
- **Input**: Documents + optional existing policy definition
- **Use Cases**: Document-to-policy conversion, incremental policy building
- **Content Structure**: `workflowContent.documents[]`

**CRITICAL: Complete Policy Definition for Incremental Building**

When adding documents to an existing policy, you must include the complete current policy definition:

```json
// CORRECT - Incremental policy building
{
  "policyDefinition": {
    "version": "1.0",
    "types": [/* ALL existing types */],
    "rules": [/* ALL existing rules */],
    "variables": [/* ALL existing variables */]
  },
  "workflowContent": {
    "documents": [/* New documents to process */]
  }
}
```

### REFINE_POLICY Workflow
- **Purpose**: Iteratively improve policies with targeted modifications
- **Input**: Policy definition + annotations for specific changes
- **Use Cases**: Kiro CLI suggestions, test-driven improvements, feedback-based refinement
- **Content Structure**: `workflowContent.policyRepairAssets.annotations[]`

**CRITICAL: Complete Policy Definition Required**

ALL build workflows require the COMPLETE existing policy definition in the `policyDefinition` section, not just the changes you want to make.

**REFINE_POLICY Annotation Types:**

**Top-Level Annotations:**
- **Type Management**: `addType`, `updateType`, `deleteType`
- **Variable Management**: `addVariable`, `updateVariable`, `deleteVariable`
- **Rule Management**: `addRule`, `updateRule`, `deleteRule`
- **Natural Language Rules**: `addRuleFromNaturalLanguage`
- **Feedback-Based Updates**: `updateFromRulesFeedback`, `updateFromScenarioFeedback`

**Sub-Operations (only within `updateType`):**
- `addTypeValue`, `updateTypeValue`, `deleteTypeValue` - Used to modify values within an existing custom type

**important**: Only create rules in if/then format.

## Annotation Type Reference

### Type Management Annotations

#### `addType` - Create New Custom Type
```json
{
  "addType": {
    "name": "ApprovalStatus",
    "description": "Status values for approval requests",
    "values": [
      {
        "value": "PENDING",
        "description": "Request is awaiting approval"
      },
      {
        "value": "APPROVED",
        "description": "Request has been approved"
      },
      {
        "value": "REJECTED",
        "description": "Request has been rejected"
      }
    ]
  }
}
```

#### `updateType` - Modify Existing Custom Type
```json
{
  "updateType": {
    "name": "ApprovalStatus",
    "newName": "RequestStatus",
    "description": "Updated status values for all request types",
    "values": [
      {
        "addTypeValue": {
          "value": "ESCALATED",
          "description": "Request escalated to higher authority"
        }
      },
      {
        "updateTypeValue": {
          "value": "PENDING",
          "newValue": "WAITING",
          "description": "Request is waiting for review"
        }
      },
      {
        "deleteTypeValue": {
          "value": "REJECTED"
        }
      }
    ]
  }
}
```

#### `deleteType` - Remove Custom Type
```json
{
  "deleteType": {
    "name": "ObsoleteType"
  }
}
```

### Variable Management Annotations

#### `addVariable` - Create New Variable
```json
{
  "addVariable": {
    "name": "requestAmount",
    "type": "real",
    "description": "The monetary amount of the approval request in USD"
  }
}
```

#### `updateVariable` - Modify Existing Variable
```json
{
  "updateVariable": {
    "name": "requestAmount",
    "newName": "approvalAmount",
    "description": "The monetary amount requiring approval in USD (updated description)"
  }
}
```

#### `deleteVariable` - Remove Variable
```json
{
  "deleteVariable": {
    "name": "obsoleteVariable"
  }
}
```

### Rule Management Annotations

#### `addRule` - Create New Rule (SMT-LIB)
```json
{
  "addRule": {
    "expression": "(=> (and (= userRole MANAGER) (< requestAmount 10000)) (not approvalRequired))"
  }
}
```

#### `updateRule` - Modify Existing Rule
```json
{
  "updateRule": {
    "ruleId": "A1B2C3D4E5F6",
    "expression": "(=> (and (= userRole MANAGER) (< requestAmount 5000)) (not approvalRequired))"
  }
}
```

#### `deleteRule` - Remove Rule
```json
{
  "deleteRule": {
    "ruleId": "G7H8I9J0K1L2"
  }
}
```

### Natural Language Rule Creation

#### `addRuleFromNaturalLanguage` - Convert Natural Language to Rule
```json
{
  "addRuleFromNaturalLanguage": {
    "naturalLanguage": "Managers can approve expense requests up to $5,000 without additional authorization. Senior managers can approve up to $25,000."
  }
}
```

### Feedback-Based Updates

#### `updateFromRulesFeedback` - Improve Rules Based on Performance
```json
{
  "updateFromRulesFeedback": {
    "ruleIds": ["A1B2C3D4E5F6", "G7H8I9J0K1L2"],
    "feedback": "These rules are too restrictive for emergency scenarios. Add exception handling for urgent requests with proper escalation paths."
  }
}
```

#### `updateFromScenarioFeedback` - Improve Based on Test Scenarios
```json
{
  "updateFromScenarioFeedback": {
    "ruleIds": ["A1B2C3D4E5F6"],
    "scenarioExpression": "(and (= requestType EMERGENCY) (= userRole MANAGER) (> requestAmount 10000))",
    "feedback": "Emergency requests should have different approval thresholds. Current rule blocks legitimate emergency expenses."
  }
}
```

**Important**: Do NOT use `get-automated-reasoning-policy-annotations` or `update-automated-reasoning-policy-annotations` for the `REFINE_POLICY` workflow. Annotations are passed directly in the `start-automated-reasoning-policy-build-workflow` call.

## Common Workflows

### 1. Getting Started (New Policy)

**CRITICAL: Always Create Policy First**

You must create a policy before starting any build workflows.

```bash
# Step 1: Create initial policy (REQUIRED FIRST STEP)
aws bedrock create-automated-reasoning-policy \
  --region us-west-2 \
  --name "YourPolicyName"

# Step 2: Extract the policyArn from the response above, then start build workflow
aws bedrock start-automated-reasoning-policy-build-workflow \
  --region us-west-2 \
  --policy-arn "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/abcd1234efgh" \
  --build-workflow-type INGEST_CONTENT \
  --source-content <policy-definition>

# Step 3: Get build results
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --region us-west-2 \
  --policy-arn "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/abcd1234efgh" \
  --build-workflow-id <workflow-id>
```

### 2. Building Policy from Document

**RECOMMENDED: Using CLI Input JSON File**

```bash
# Step 1: Encode PDF to base64 and create JSON file with base64 content
PDF_BASE64=$(base64 -i your-policy.pdf | tr -d '\n')

cat > ingest-policy.json << EOF
{
  "policyArn": "arn:aws:bedrock:us-west-2:123456789012:automated-reasoning-policy/your-actual-policy-id",
  "buildWorkflowType": "INGEST_CONTENT",
  "sourceContent": {
    "policyDefinition": {
      "version": "1.0",
      "types": [],
      "rules": [],
      "variables": []
    },
    "workflowContent": {
      "documents": [
        {
          "document": "$PDF_BASE64",
          "documentContentType": "pdf",
          "documentName": "Company Policy Document",
          "documentDescription": "Main policy document containing business rules and organizational guidelines."
        }
      ]
    }
  }
}
EOF

# Step 2: Use the JSON file
aws bedrock start-automated-reasoning-policy-build-workflow \
  --region us-west-2 \
  --cli-input-json file://ingest-policy.json
```

### 3. Policy Development Cycle

```bash
# 1. Import/process policy definition
aws bedrock start-automated-reasoning-policy-build-workflow \
  --build-workflow-type IMPORT_POLICY

# 2. Update DRAFT with processed definition
aws bedrock update-automated-reasoning-policy \
  --policy-arn <unversioned-arn> \
  --policy-definition <build-output>

# 3. Create versioned snapshot of DRAFT (definitionHash from step 2 response)
aws bedrock create-automated-reasoning-policy-version \
  --policy-arn <unversioned-arn> \
  --last-updated-definition-hash <definition-hash>
```

## Testing Workflow

### Primary Approach: Scenarios API (Recommended)

Use `get-automated-reasoning-policy-next-scenario` for comprehensive policy validation.

The Scenarios API is superior for testing because it:
- Tests formal logic directly - Validates policy rules work correctly
- AI-generated scenarios - Comprehensive coverage of edge cases and rule interactions
- Targets specific rules - Tests individual rules and combinations
- Always works - No natural language translation issues
- Intelligent test generation - AI understands policy logic deeply

```bash
# Generate intelligent test scenarios automatically
aws bedrock get-automated-reasoning-policy-next-scenario \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123"
```

### Secondary Approach: Test Cases (User Experience)

Use manual test cases to validate natural language translation.

```bash
# Create test cases for natural language validation
aws bedrock create-automated-reasoning-policy-test-case \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --guard-content "It is 2:30 PM on a clear day" \
  --query-content "What color should the sky be?" \
  --expected-aggregated-findings-result "VALID" \
  --confidence-threshold 0.8
```

### Test Result Analysis and Troubleshooting

**Understanding Test Results:**

**Scenarios API Results:**
- `expectedResult: SATISFIABLE` - Policy logic works correctly
- API errors or logic conflicts - Policy needs fixing with REFINE_POLICY

**Common Test Case Failure Modes:**

1. **TRANSLATION_AMBIGUOUS**
   - Problem: AI can't map natural language to policy variables
   - Solution: Improve variable descriptions with more natural language synonyms

2. **SATISFIABLE when expecting VALID**
   - Problem: Your expected result label is likely WRONG, not the policy
   - SATISFIABLE = "This scenario is logically consistent with the policy rules"
   - VALID = "This is the correct/expected answer according to the policy"
   - Solution: Change `expectedAggregatedFindingsResult` from `VALID` to `SATISFIABLE`

3. **Empty testFindings arrays**
   - Problem: Translation issues, not rule violations
   - Solution: Focus on improving natural language descriptions, not policy logic

**Valid values for `expectedAggregatedFindingsResult`:**
- `VALID` - The claims are true, implied by the premises and the policy
- `INVALID` - The claims are false, not implied by the premises and policy
- `SATISFIABLE` - The claims can be true or false depending on assumptions
- `IMPOSSIBLE` - Automated Reasoning can't make a statement (e.g., conflicting policy rules)
- `TRANSLATION_AMBIGUOUS` - Ambiguity in translation prevented validity checking
- `TOO_COMPLEX` - Input too complex for Automated Reasoning to process within latency limits
- `NO_TRANSLATION` - Some or all of the input wasn't translated into logic

### Running Tests Against a Build

After creating test cases, run them against a completed build workflow:

```bash
# Run all tests against a completed build
aws bedrock start-automated-reasoning-policy-test-workflow \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123"

# Run specific tests only
aws bedrock start-automated-reasoning-policy-test-workflow \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --test-case-ids '["A1B2C3D4E5F6"]'

# Get result for a specific test case
aws bedrock get-automated-reasoning-policy-test-result \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --test-case-id "A1B2C3D4E5F6"

# List all test results for a build
aws bedrock list-automated-reasoning-policy-test-results \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123"
```

## Build Workflow Monitoring

**Critical Build Limits**: The API supports maximum 2 total build workflows per policy, with only 1 allowed to be IN_PROGRESS at any time. When a build workflow completes, you can instruct the user to review the output using the console. 

### Check Build Status

```bash
aws bedrock get-automated-reasoning-policy-build-workflow \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123"
```

### List Build History

```bash
aws bedrock list-automated-reasoning-policy-build-workflows \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --max-results 50
```

### Best Practice: Clean Build Management

```bash
# 1. Check existing builds before starting new ones
aws bedrock list-automated-reasoning-policy-build-workflows \
  --policy-arn <policy-arn> \
  --max-results 10

# 2. Delete old/completed builds if you have 2 already
aws bedrock delete-automated-reasoning-policy-build-workflow \
  --policy-arn <policy-arn> \
  --build-workflow-id "old-workflow-id" \
  --last-updated-at "2025-11-15T00:41:18.608000+00:00"

# 3. Now start your new build
aws bedrock start-automated-reasoning-policy-build-workflow \
  --policy-arn <policy-arn> \
  --build-workflow-type INGEST_CONTENT \
  --source-content <content>
```

## Build Workflow Assets

After a build workflow completes successfully, you can retrieve various assets. After you complete a build workflow, you can ask the user to check the build diff using the Automated Reasoning checks console.

### Asset Types

#### 1. ASSET_MANIFEST - Index of All Assets

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "ASSET_MANIFEST"
```

**What it contains:**
- A manifest listing all available assets and their IDs for the build workflow
- Use this to discover asset IDs needed for retrieving assets

#### 2. POLICY_DEFINITION - The Main Output

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "POLICY_DEFINITION"
```

**What it contains:**
- Compiled policy with extracted/refined rules, variables, and types
- SMT-LIB expressions for all rules
- Complete policy structure ready for deployment

#### 3. BUILD_LOG - Build Process Details

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "BUILD_LOG"
```

**What it shows:**
- Document processing steps - What content was analyzed
- Extraction results - What rules, variables, and types were found
- Processing warnings - Content that couldn't be interpreted
- Success/failure status for each extraction step

#### 4. QUALITY_REPORT - Policy Quality Analysis

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "QUALITY_REPORT"
```

**What it contains:**
- Conflicting rules - Rules that contradict each other
- Unused variables - Variables not referenced by any rules
- Unused type values - Enum values not used in rules
- Disjoint rule sets - Groups of rules that don't interact

#### 5. GENERATED_TEST_CASES - Auto-Generated Tests

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "GENERATED_TEST_CASES"
```

**What it contains:**
- Automatically generated test cases based on the policy rules

#### 6. POLICY_SCENARIOS - Policy Test Scenarios

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "POLICY_SCENARIOS"
```

**What it contains:**
- AI-generated scenarios for comprehensive policy validation

#### 7. FIDELITY_REPORT - Policy Fidelity Analysis

```bash
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "FIDELITY_REPORT"
```

**What it contains:**
- Fidelity analysis results from a GENERATE_FIDELITY_REPORT build workflow

#### 8. SOURCE_DOCUMENT - Original Source Documents

```bash
# Requires --asset-id obtained from the ASSET_MANIFEST
aws bedrock get-automated-reasoning-policy-build-workflow-result-assets \
  --policy-arn "arn:aws:bedrock:region:account:automated-reasoning-policy/policy-id" \
  --build-workflow-id "workflow-123" \
  --asset-type "SOURCE_DOCUMENT" \
  --asset-id "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5"
```

**What it contains:**
- The original source document used in the build workflow
- The `--asset-id` parameter is required because multiple source documents may have been used