Provalo, Parte 3: Una guida dettagliata all'implementazione del ragionamento automatico

In questa guida, scoprirai come creare una policy di ragionamento automatico da un documento aziendale esistente, distribuirla tramite Guardrails per Amazon Bedrock, convalidare le risposte degli LLM con ApplyGuardrail, creare un audit trail e proteggere gli agenti IA con AgentCore Policy. Grazie a questo processo, i team possono passare dalla documentazione di conformità alla verifica in produzione in soli 30 minuti.

Nella Parte 1 (Perché "probabilmente corretto" non è sufficiente) abbiamo spiegato perché le startup necessitano di una verifica deterministica. Nella Parte 2 (Logica formale, policy Cedar ed economia della verifica) abbiamo spiegato la pipeline di verifica e i calcoli matematici alla sua base. Ora è il momento di costruire.

Di cosa hai bisogno prima di iniziare?

Prima di iniziare, assicurati di avere quanto segue:

• Un account AWS con accesso ad Amazon Bedrock. Se fai parte di AWS Activate, disponi già dei crediti necessari.
• Python 3.9+ con boto3. Se hai spedito un MVP, lo hai già.
• Un documento di policy (PDF, Markdown o testo semplice) che descrive le regole aziendali. Se hai superato una revisione della conformità o una due diligence per gli investitori, lo hai già.

Fase 1: Crea la tua policy AR

Il percorso più veloce è tramite la console AWS. Non è necessario scrivere una logica formale, poiché Bedrock traduce automaticamente il documento di origine in regole logiche formali.

1. Apri la console Bedrock e vai a Ragionamento automatico nella barra laterale sinistra.
2. Crea una nuova policy. Assegnagli un nome descrittivo (ad esempio, policy di idoneità ipotecaria).
3. Carica il tuo documento di origine. Questo è il documento PDF, Word o il file di testo semplice che descrive le tue regole aziendali. Per una startup fintech, questo potrebbe essere il documento sui criteri di prestito. Per l'assistenza sanitaria, i tuoi protocolli clinici.
4. Fornisci le istruzioni. Scrivi un breve intento descrivendo ciò che la policy convalida e includi 2-3 esempi di coppie di domande e risposte. Questi aiutano il sistema a capire in che modo gli utenti interagiranno con la policy.

Per i team che preferiscono non utilizzare la console, è disponibile anche un'interfaccia conversazionale per la creazione delle policy che guida l'utente nella formalizzazione in linguaggio naturale. Presenta alcuni prerequisiti (incluso Kiro-CLI) ma rimuove completamente la console dal flusso di lavoro.

Esempio di intento:

Questa policy verifica le domande sull'idoneità al mutuo. Gli utenti chiedono se i clienti sono idonei per tipi di mutuo specifici in base ai loro dettagli finanziari.

Domande e risposte di esempio:

D: Un cliente desidera acquistare una casa da 350.000 dollari con un acconto di 30.000 dollari. Ha i requisiti per ottenere un mutuo tradizionale?

R: No. I mutui tradizionali richiedono un acconto minimo del 20% (70.000 dollari per un acquisto di 350.000 dollari).

Rivedi il report sulla fedeltà:

Dopo che il sistema ha elaborato il documento, genera un report di fedeltà con due punteggi:

• Punteggio di copertura (da 0 a 1): quanta parte del documento di origine è rappresentata nella policy
• Punteggio di precisione (da 0 a 1): quanto fedelmente le regole estratte corrispondono all'intento del documento

Il report mostra anche le variabili e le regole specifiche estratte, con riferimento alle istruzioni esatte nel documento di origine. Qui puoi verificare che il sistema abbia compreso correttamente le tue regole.

Perfeziona le descrizioni delle variabili utilizzando esempi reali tratti dalla tua applicazione. Testa le domande più rappresentative, verifica come il sistema le traduce e migliora le descrizioni laddove le traduzioni non siano accurate. Questo è il fattore più importante per migliorare la precisione. Includi unità di misura, sinonimi, regole di conversione e terminologia specifica del settore ove possibile. Una descrizione come "L'acconto del mutuatario in percentuale sul prezzo di acquisto; quando gli utenti menzionano importi in dollari, converti utilizzando (acconto/prezzo di acquisto) x 100" è più efficace di "Quanto versa il mutuatario come acconto".

Non si tratta di un progetto di ingegneria che si articola in più sprint. Bastano 30 minuti per trasformare il documento di conformità esistente in una policy AR funzionante. Iterate sulle descrizioni delle variabili e testate con domande di esempio finché i punteggi di fedeltà e i risultati dei test non corrispondono alle vostre aspettative.

Per il percorso API (utile per le pipeline CI/CD), consulta anche la Documentazione di riferimento per l’API CreateAutomatedReasoningPolicy. L'API accetta un nome, una descrizione facoltativa e una policyDefinition contenente regole, variabili e tipi personalizzati.

Fase 2: Distribuisci a un guardrail

Una volta che la tua policy è stata testata, distribuiscila per l'uso in produzione.

Salva una versione non modificabile. Nella console, scegli "Salva come nuova versione". Questo crea uno snapshot numerato e non modificabile (versione 1, 2, 3...) in modo che il guardrail di produzione non venga alterato quando continui a modificare la bozza. Ecco come le startup inviano in modo sicuro e veloce: il tuo team addetto alla conformità esamina la versione 1 in produzione mentre il tuo team di ingegneri itera sulla versione 2 in bozza. Nessun blocco di distribuzione, nessun "per favore non modificare la policy fino al rilascio".

Dopo aver pubblicato una versione della tua policy, collegala a un guardrail in modo che possa essere utilizzata durante la convalida al runtime:

Dettagli chiave:

• policies accetta una serie di stringhe ARN di policy  (max 2), non oggetti
• confidenceThreshold (facoltativo, da 0 a 1) controlla il livello minimo di concordanza affinché le traduzioni siano considerate affidabili. Valori più bassi (0,3) fanno emergere più risultati in tempi più brevi; valori più alti (1) ottimizzano rigorosamente la correttezza. Inizia con un valore basso durante lo sviluppo, aumentalo per la produzione
• crossRegionConfig è richiesto per i controlli AR; consente l'inferenza interregionale per la valutazione dei guardrail. Utilizza il profilo relativo alla propria area geografica (ad esempio, us.guardrail.v1:0 per gli Stati Uniti, eu.guardrail.v1:0 per l'UE).
• blockedInputMessaging e blockedOutputsMessaging sono richiesti; questi sono i messaggi di fallback visualizzati quando altri componenti del guardrail (non AR) bloccano il contenuto
• Usa una versione numerata (:1) nell'ARN per la produzione. Riserva DRAFT solo per lo sviluppo

Fase 3: Convalida le risposte degli LLM con ApplyGuardrail

Il modello di integrazione consigliato è l'API autonoma ApplyGuardrail. Questo ti dà il pieno controllo su quali contenuti vengono convalidati e quando, ed è l'approccio consigliato esplicitamente dalla documentazione AWS per i controlli AR.

Ecco un esempio minimo di integrazione da aggiungere alla pipeline di inferenza esistente:

Esegui questa funzione dopo che il tuo LLM ha generato una risposta, prima di inviarla all'utente:

Importante: i controlli AR funzionano in modalità di rilevamento. Restituiscono risultati e feedback. Non bloccano o riscrivono automaticamente la risposta. L'applicazione esamina i risultati e decide cosa fare.

Fase 4: Gestisci i risultati

Ogni risultato è di tipo unione con esattamente una chiave presente. Ecco come analizzarli e agire di conseguenza:

Il modello di riparazione standard è un ciclo di convalida-riscrittura: convalidare la risposta, restituire eventuali violazioni al modello, rigenerare la risposta e riconvalidare. Ripetere finché la risposta non è valida o non viene raggiunto il limite di tentativi.

L'utente non vede mai il ciclo di riscrittura. Vede una risposta corretta al primo tentativo. L'iterazione avviene in millisecondi, in background.

Fase 5: Crea un audit trail

Ogni iterazione di verifica deve essere registrata. Quando il cliente aziendale richiede la documentazione SOC 2, o l'autorità di regolamentazione chiede come è stata verificata una decisione specifica, è possibile recuperare il registro JSON. Ogni verifica è dotata di timestamp e tracciabile.

Questo log diventa il tuo artefatto di conformità. Mostra cosa ha chiesto l'utente, cosa ha generato l’LLM, cosa ha trovato l’AR e quale azione ha intrapreso la tua applicazione. Per le startup che puntano alla conformità SOC 2, HIPAA o alle vendite aziendali, questa traccia di controllo non è facoltativa. È la prova che il tuo sistema funziona come documentato.

Fase 6: Proteggi i tuoi agenti con AgentCore Policy

Se la tua startup è passata dai chatbot ai flussi di lavoro agentici (la tua IA prenota appuntamenti, elabora rimborsi, interroga database o invia email), devi stabilire dei limiti a ciò che il tuo agente può fare, non solo a ciò che dice.

Per definire questi limiti, Policy in Amazon Bedrock AgentCore utilizza Cedar. Ad esempio, un sistema di prenotazione appuntamenti in ambito sanitario necessita di criteri che limitino l'accesso alle cartelle cliniche dei pazienti, limitino le azioni di prenotazione agli orari di lavoro e impediscano l'elaborazione di rimborsi superiori a una determinata soglia senza l'approvazione del responsabile. Iniziate in modalità LOG_ONLY per osservare le attività del tuo sistema senza bloccare nulla. Una volta che le policy sono considerate attendibili, passa alla modalità ENFORCE per l'ambiente di produzione.

Il gateway è il livello di applicazione tra il tuo agente e i suoi strumenti. Ogni chiamata allo strumento passa attraverso il gateway, dove le policy Cedar vengono valutate prima che la richiesta raggiunga l'obiettivo. Questo è ciò che rende l'applicazione deterministica e indipendente dal ragionamento dell'agente: l'agente non può aggirare, ignorare o farsi strada oltre il gateway.

Configura un gateway e un motore di policy utilizzando la CLI AgentCore:

Scrivi una policy Cedar e collegala al motore di policy. L'esempio seguente mostra le policy illustrative per un addetto agli appuntamenti sanitari. In pratica, i nomi delle azioni vengono generati automaticamente dalla destinazione del gateway e dallo schema dello strumento (ad esempio, HealthTarget__get_patient_record) e la risorsa deve fare riferimento all'ARN specifico del gateway:

Cedar è impostato su "negazione predefinita": ogni interazione tra agente e strumento viene bloccata a meno che una policy di autorizzazione esplicita non la consenta. Le policy di autorizzazione definiscono quali strumenti l'agente può richiamare e a quali condizioni. Le policy di divieto riportate di seguito prevedono delle eccezioni, bloccando scenari specifici anche quando un'autorizzazione più ampia li consentirebbe.

Salvala come healthcare_policy.cedar, quindi collegala al motore di policy:

In alternativa, puoi descrivere le tue regole in linguaggio naturale e lasciare che il sistema generi Cedar per te (richiede che il gateway sia stato prima distribuito):

Il ragionamento automatico convalida le policy in fase di creazione, individuando regole eccessivamente permissive, eccessivamente restrittive o inefficaci prima della loro distribuzione.

Le caratteristiche chiave che contano per le startup regolamentate:

• Negazione predefinita: se nessuna policy consente esplicitamente un'azione, questa viene bloccata
• Il divieto vince sempre: le regole di blocco rigido non possono essere annullate da altre policy
• Applicazione deterministica: opera al confine del gateway, al di fuori del ragionamento del tuo agente. Non può essere aggirata con iniezioni di prompt, allucinazioni o bug

Inizia in modalità LOG_ONLY per vedere cosa sta facendo il tuo agente senza interrompere il tuo prodotto. I log mostrano quale policy è stata applicata su ogni richiesta al gateway, l'esito della decisione della policy (autorizzazione o rifiuto) ed evidenziano le policy non corrispondenti quando si verifica una deriva degli strumenti. Esaminali. Perfeziona le policy. Quando sei sicuro, passa a ENFORCE. È così che si passa dal prototipo alla produzione senza interrompere l'attività degli utenti.

Per esempi completi, tra cui script di distribuzione e test harness, consulta gli esempi di Amazon Bedrock AgentCore su GitHub.

Cosa succede dopo aver distribuito il ragionamento automatico?

Una volta che i controlli AR e le policy di AgentCore sono attivi, si sblocca qualcosa di ancora più prezioso della semplice prevenzione degli errori: un'unica fonte di verità.

La tua policy AR rappresenta le tue regole aziendali codificate come logica formale. Quando queste regole cambiano (e cambiano sempre: nuove normative, criteri di prestito aggiornati, protocolli clinici rivisti), aggiorni il documento di origine, rigeneri la policy e immediatamente ogni sistema di intelligenza artificiale nella tua infrastruttura si conforma alle nuove regole. Nessun progettazione dei prompt per l'aggiornamento. Nessun riaddestramento del modello. Nessuna speranza che qualcuno si sia ricordato di modificare il messaggio di sistema.

Questo elimina un'intera categoria di bug di deriva. La documentazione e il comportamento dell'IA sono matematicamente collegati e non possono perdere la sincronizzazione.

Poiché i guardrail sono indipendenti dal modello, il livello di verifica rimane invariato anche cambiando il modello di base. La stessa policy AR che ha verificato le risposte di Claude verifica anche quelle di Amazon Nova. Le regole dipendono dalla logica aziendale, non dal modello.

L'integrazione si estende all'intero ecosistema Bedrock: le policy AR funzionano con le knowledge base per la generazione di informazioni con recupero avanzato, con gli agenti AgentCore per flussi di lavoro a più fasi e con l'intera gamma di modelli di base. Stai costruendo su una piattaforma, non su una soluzione specifica.

Scopri di più

• Documentazione sui controlli del ragionamento automatico
• Concetti di AR (variabili, regole, risultati)
• Guida all'integrazione (modelli ApplyGuardrail)
• Documentazione di AgentCore Policy
• Esempi di AgentCore su GitHub
• Panoramica sulla sicurezza certificabile di AWS
• Cos'è il ragionamento automatico
• Linguaggio Cedar (CNCF)

Questa è la conclusione della nostra serie sull’AR per le startup

In tutta la serie Provalo, la nostra tesi è stata la stessa: le startup che si basano sull’intelligenza artificiale necessitano di verifiche deterministiche e matematiche, non solo di garanzie probabilistiche.

Nella Parte 1, abbiamo spiegato perché il problema della fiducia è esistenziale per le startup e come decenni di lavoro di AWS nei metodi formali hanno portato a Guardrail Bedrock e AgentCore Policy.

Nella Parte 2, abbiamo esaminato la logica formale, la pipeline di verifica e l'economia. In questo post, hai visto il percorso completo di implementazione, dai documenti di conformità esistenti all'IA verificata pronta per la produzione.

Le startup che avranno successo nell'era dell'IA non si limiteranno a costruire sistemi intelligenti; creeranno sistemi di cui potranno dimostrare la correttezza. Il ragionamento automatico e AgentCore Policy lo rendono possibile oggi, utilizzando le policy e i documenti di conformità che la maggior parte delle aziende già possiede. L'unica domanda che rimane è: inizierai subito o dopo che il primo incidente ti costringerà a farlo?