View a markdown version of this page

Guardrail nelle politiche - Amazon Bedrock AgentCore

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à.

Guardrail nelle politiche

Questa sezione spiega come inserire dei limiti nelle politiche, in modo che la decisione di una politica dipenda dal fatto che il contenuto della richiesta o della risposta contenga materiale non sicuro. Il controllo dei contenuti stesso viene eseguito da un guardrail, chiamato da Policy in AgentCore durante la valutazione. Oggi i guardrail sono supportati da Amazon Bedrock Guardrails.

Una condizione di guardrail indica tre elementi: il tipo di guardrail, le categorie che il tipo deve valutare e il contenuto da valutare. Il guardrail restituisce un punteggio di confidenza e la politica decide cosa farne.

Se non conosci i guardrail nelle politiche, inizia con la Guida introduttiva ai guardrails, che ti guiderà nella creazione di un sistema end-to-end. Ad esempio, le politiche che coprono MCP, runtime e ogni API di inferenza, consulta Esempi di policy di Guardrail.

Elementi costitutivi di una condizione di guardrail

Policy in AgentCore supporta tre tipi di guardrail. Ciascuno accetta una serie di categorie da valutare e restituisce il risultato in modo diverso.

ContentFilter

Harmful-content categorie come VIOLENCE oHATE. Restituisce un punteggio di affidabilità per ogni categoria nominata, indipendentemente dal fatto che il contenuto lo mostri o meno.

PromptAttack

Prompt-manipulation categorie come JAILBREAK oPROMPT_INJECTION. Restituisce un punteggio di affidabilità per ogni categoria nominata.

SensitiveInformation

Entità sensibili come EMAIL oUS_SOCIAL_SECURITY_NUMBER. Restituisce un rilevamento per entità trovata anziché un punteggio per categoria, quindi non ha un punteggio per categoria e richiede un'aggregazione.

Per le categorie accettate da ogni tipo, vedi Guardrails supportati. Per il contenuto da valutare, vedi Passing context to your guardrail.

Un punteggio di confidenza è un decimale compreso tra 0 e 1 che esprime la forza con cui il contenuto presenta la proprietà valutata. Sei tu a decidere cosa fare con quel punteggio, e la politica esprime la tua decisione come condizione sul risultato del guardrail, molto spesso un confronto di soglie, ad esempio. .confidenceScore.greaterThan(decimal("0.4")) Per le soglie e gli operatori di confronto, vedi Soglie per i guardrail.

I punteggi possono anche essere ridotti tra le categorie anziché confrontati uno alla volta. Un'aggregazione esegue questa operazione: maxConfidenceScore() minConfidenceScore() restituisce un punteggio, mentre count() restituisce quanti rilevamenti sono stati rilevati e categories() restituisce l'insieme di categorie rilevate, quindi per queste due categorie non è necessaria alcuna soglia. Per l'elenco completo, consulta Aggregazioni.

Disponibilità regionale di Guardrails

La tabella seguente mostra quali AWS regioni supportano i guardrail nelle politiche.

Nome della Regione I guardrail nelle politiche

Stati Uniti orientali (Virginia settentrionale)

✓ Sì

Stati Uniti orientali (Ohio)

✓ Sì

Stati Uniti occidentali (California settentrionale)

No

Stati Uniti occidentali (Oregon)

✓ Sì

Asia Pacifico (Hyderabad)

No

Asia Pacifico (Malesia)

No

Asia Pacifico (Mumbai)

No

Asia Pacifico (Seul)

No

Asia Pacifico (Singapore)

No

Asia Pacifico (Sydney)

✓ Sì

Asia Pacifico (Thailandia)

No

Asia Pacifico (Tokyo)

✓ Sì

Canada (Centrale)

No

Europa (Francoforte)

No

Europa (Irlanda)

No

Europa (Londra)

✓ Sì

Europa (Milano)

No

Europa (Parigi)

No

Europa (Spagna)

No

Europa (Stoccolma)

✓ Sì

Sud America (San Paolo)

No

AWS GovCloud (US-West)

No

Prima di iniziare

Prima di iniziare, devi configurare correttamente il tuo ruolo IAM.

Permissions

Il ruolo di esecuzione del gateway necessita bedrock:InvokeGuardrailChecks di ulteriori autorizzazioni oltre alle AgentCore autorizzazioni di cui già dispone. Per quest'ultimo, consulta AgentCore Gateway and Policy in AgentCore IAM Permissions.

Policy in AgentCore utilizza le credenziali FAS (Forward Access Session) derivate dal ruolo di esecuzione del gateway per chiamare l'API Bedrock Guardrails per conto dell'utente, motivo per cui l'autorizzazione appartiene a quel ruolo.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "bedrock:InvokeGuardrailChecks", "Resource": "arn:aws:bedrock:us-west-2:123456789012:guardrail/abc123" } ] }

Guardrail supportati

Tipo di guardrail Tipo di entità Categories

Filtro dei contenuti

ContentFilter

VIOLENCE, HATE, SEXUAL, MISCONDUCT, INSULTS

Rilevamento tempestivo degli attacchi

PromptAttack

JAILBREAK, PROMPT_INJECTION, PROMPT_LEAKAGE

Informazioni sensibili

SensitiveInformation

Identità personale — ADDRESSAGE, NAMEEMAIL,PHONE,USERNAME,PASSWORD,PIN,DRIVER_ID,LICENSE_PLATE, VEHICLE_IDENTIFICATION_NUMBER

Finanziario — CREDIT_DEBIT_CARD_NUMBERCREDIT_DEBIT_CARD_CVV,CREDIT_DEBIT_CARD_EXPIRY,US_BANK_ACCOUNT_NUMBER,US_BANK_ROUTING_NUMBER,INTERNATIONAL_BANK_ACCOUNT_NUMBER, SWIFT_CODE

Identificatori governativi e sanitari — US_SOCIAL_SECURITY_NUMBERUS_PASSPORT_NUMBER,US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER,,CA_SOCIAL_INSURANCE_NUMBER,CA_HEALTH_NUMBER,UK_NATIONAL_INSURANCE_NUMBER, UK_NATIONAL_HEALTH_SERVICE_NUMBER UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER

Credenziali e rete —AWS_ACCESS_KEY,,,AWS_SECRET_KEY, IP_ADDRESS MAC_ADDRESS URL

Nota

Questa tabella è l'elenco corrente dei guardrail e delle categorie supportati da Policy in. AgentCore Una categoria al di fuori di essa non viene convalidata quando si crea la policy. In particolare non esiste una ACCOUNT_NUMBER categoria: usa US_BANK_ACCOUNT_NUMBER oINTERNATIONAL_BANK_ACCOUNT_NUMBER.

Scrivere barriere nelle politiche

Per inserire un guardrail in una politica, puoi creare la politica come codice o descriverla in linguaggio naturale. Come con altre politiche, specifica un effetto, ad esempio permit con una condizione (when guardrails). Nella condizione, fornite il guardrail da abilitare, le categorie da valutare, il contenuto da valutare e il confronto dei punteggi che desiderate.

Esempio di definizione del guardrail

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___<METHOD>:<uri>", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"] .confidenceScore .greaterThan(decimal("0.2")) };
Nota

suppressOutputviene eseguito dopo che lo strumento ha prodotto un risultato e nega la risposta al chiamante. Lo strumento continua a funzionare; viene soppressa solo la risposta.

suppressOutputfunziona solo in condizioni di guardrail. La sua condizione deve consistere esclusivamente nei controlli del guardrail. Scrivi questi controlli in un when guardrails {…​} blocco o in un when {…​} blocco semplice. suppressOutputnon supporta Cedar o temporal {…​} condizioni standard.

Nota i tre caratteri di sottolineatura che separano il nome della destinazione dal metodo e dall'URI. Per esempi relativi a un gateway di riferimento completo, consulta Esempi di politiche di Guardrail.

Creazione di una politica con guardrail

Per creare la politica, inserisci la dichiarazione nel policy campo della definition proprietà. Per ulteriori informazioni, consulta Creare una politica. Altrimenti viene creata come qualsiasi altra politica.

Esempio
AgentCore CLI

La procedura guidata interattiva è il modo più semplice per aggiungere un guardrail, perché crea la dichiarazione automaticamente.

  1. Esegui senza agentcore add policy bandiere:

    agentcore add policy

    La procedura guidata richiede il nome del gateway, della destinazione, del motore e della policy. Scegliete il modulo guardrail come sorgente, quindi vi chiederà di inserire l'effetto, la categoria del guardrail, i filtri e il percorso dei dati e vi mostrerà l'istruzione che ha creato prima di crearlo.

  2. Implementa il progetto:

    agentcore deploy --yes

    Per scrivere la stessa cosa in modo non interattivo, passate i flag del modulo —--form-category,,, --form-filters e. --form-effect --form-data-path La fornitura di uno di essi salta la procedura guidata. Per fornire una dichiarazione scritta da te, salvala in un file e invia: --source

    agentcore add policy --name BlockViolentReason \ --engine my_policy_engine \ --source block_violent_reason.dw \ --validation-mode IGNORE_ALL_FINDINGS

    Per ulteriori informazioni, consulta Guida introduttiva all'uso dei guardrails.

AWS CLI
  1. Esegui il seguente comando AWS CLI in un terminale per creare la policy:

    aws bedrock-agentcore-control create-policy \ --policy-engine-id my_policy_engine-a1b2c3d4e5 \ --name BlockViolentReason \ --validation-mode IGNORE_ALL_FINDINGS \ --definition '{ "policy": { "statement": "forbid (principal, action == AgentCore::Action::\"RefundTool___process_refund\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.reason])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.4\")) };" } }'
AWS Python SDK (Boto3)
  1. Esegui il seguente codice Python per creare la policy utilizzando l' AWS SDK per Python:

    import boto3 client = boto3.client("bedrock-agentcore-control") GATEWAY_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5" statement = ( 'forbid (principal, ' 'action == AgentCore::Action::"RefundTool___process_refund", ' f'resource == AgentCore::Gateway::"{GATEWAY_ARN}") ' 'when guardrails { ' 'BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"]' '.confidenceScore.greaterThan(decimal("0.4")) };' ) response = client.create_policy( policyEngineId="my_policy_engine-a1b2c3d4e5", name="BlockViolentReason", validationMode="IGNORE_ALL_FINDINGS", definition={"policy": {"statement": statement}}, ) # CreatePolicy returns 202 - wait for the terminal status client.get_waiter("policy_active").wait( policyEngineId="my_policy_engine-a1b2c3d4e5", policyId=response["policyId"], ) print(response["policyId"])

Qualunque sia la superficie che utilizzi, preferisci esprimere la regola come una permit con il confronto inverso. La valutazione delle policy è negata per impostazione predefinita, quindi una singola permit opzione valida solo finché il punteggio rimane basso concede l'azione e la annulla:

permit (principal, action == AgentCore::Action::"RefundTool___process_refund", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5") when guardrails { BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"] .confidenceScore.lessThanOrEqual(decimal("0.4")) };

forbidUtilizzala quando desideri limitare un'autorizzazione già esistente, un'azione consentita da altre policy, ad esempio sui relativi valori di input. A forbid sovrascrive qualsiasipermit, quindi sottrae dalla concessione esistente. Di per sé non concede nulla: l'azione rimane negata per impostazione predefinita e il guardrail non viene mai consultato, quindi un solitario forbid ha bisogno di un compagno per la stessa azione. permit

Importante

La convalida delle policy analizza l'intera policy impostata nel motore e non può interpretare una condizione di guardrail. Una persona forbid la cui unica porta è un guardrail quindi sembra incondizionata, quindi se nient'altro nel motore consente quel principio, azione e risorsa, il set viene segnalato come Overly Restrictive:. Overly Restrictive: Policy Engine will deny every request for the specified principal (…​), action (…​) and resource (…​) combination if the policy is added or updated In base all'impostazione predefinita, la politica viene rifiutata. --validation-mode FAIL_ON_ANY_FINDINGS Passa comunque --validation-mode IGNORE_ALL_FINDINGS per crearla.

Poiché il risultato è una proprietà del set di politiche piuttosto che di una singola istruzione, la sua visibilità dipende da ciò che già contiene il motore.

Il rifiuto è asincrono. La chiamata restituisce 202 conCREATING, e la politica stabilisce quindi il motivostatusReasons, quindi verifica lo stato del terminale anziché considerare il 202 come un successo. CREATE_FAILED

Per una procedura dettagliata sull'utilizzo della CLI, consulta Guida introduttiva AgentCore ai guardrails. Per le dichiarazioni su ogni tipo di bersaglio, consulta gli esempi di policy di Guardrail.

Specificare un tipo di guardrail

Per scegliere un tipo di guardrail specifico, usa il namespace: BedrockGuardrails

Tipo di guardrail Nome della funzione Guardrail

Filtro dei contenuti

BedrockGuardrails::ContentFilter

Attacco rapido

BedrockGuardrails::PromptAttack

Informazioni sensibili

BedrockGuardrails::SensitiveInformation

Selezione di una categoria di guardrail

Seleziona una categoria per il tipo di parapetto scelto (vediGuardrail supportati).

Ad esempio, BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Effetti per i guardrail

Per annullare una richiesta di autorizzazione su un guardrail, usa gli permit effetti and. forbid Questi continuano a regolare le richieste di autorizzazione.

forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6")) };

Per sopprimere gli output di strumenti, agenti o modelli, utilizzate l'effetto. suppressOutput suppressOutputopera sui dati restituiti da un'azione. Una volta completata un'azione autorizzata, valuta le uscite rispetto al guardrail e sopprime l'output quando il guardrail viene violato.

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text]) .count() > 0 };
Importante

Due regole stabiliscono il lato della richiesta che un guardrail può leggere ed entrambe vengono applicate al momento della creazione della policy.

  • Un effetto di autorizzazione, permit oppure, può leggere forbid solo i percorsi. context.input.* L'suppressOutputeffetto può leggere solo context.output.* i percorsi. Si usa context.output con permit o forbid viene rifiutato conGuardrail '<name>' references 'context.output' but the policy has an authorization effect.

  • Una singola chiamata guardrail non può combinare context.input.* context.output.* percorsi diversi; ogni percorso di una chiamata deve trovarsi sullo stesso lato. Per esaminare sia una richiesta che la sua risposta, scrivi due chiamate guardrail secondo la stessa suppressOutput politica, una per lato. La restrizione è per chiamata, non per politica.

Poiché una policy nomina un'azione specifica, deve anche assegnare un nome ARN a un gateway specifico. resource == Lasciare la risorsa non vincolata viene rifiutato. Per ulteriori informazioni, consulta Requisiti di specificità delle risorse.

Passare il contesto al guardrail

In una condizione di guardrail, specifica i percorsi di dati, ad esempiocontext.input.message, che identificano i valori da estrarre dal payload dell'azione. Il guardrail valuta i valori estratti. È possibile specificare uno o più percorsi in base allo schema di richiesta o risposta.

Ad esempio, [context.input.message, context.input.systemPrompt]

Puoi fornire un percorso dati in due modi:

Un percorso di campo, context.input.<field> oppure context.output.<field>

Usalo quando il valore che desideri è una singola stringa, ad esempio un argomento dello strumento o un campo scalare del corpo di una richiesta. Il percorso di un campo deve risolversi in una stringa; il puntamento verso un oggetto o un elenco viene rifiutato quando si crea la politica.

Un JSONPath: una stringa letterale che inizia con $

Usalo quando il testo si trova all'interno di un elenco o di un oggetto, che un percorso di campo non può raggiungere: una conversazione o un elenco di blocchi di contenuto. Scrivilo radicato nel payload, senza context.input. prefisso: per esempio. "$.messages[*].content" Un JSONPath viene valutato come una query, quindi un jolly può corrispondere a molti valori, inclusi valori annidati a profondità diverse. Queste corrispondenze vengono appiattite in un'unica sequenza di testo anziché conservate come elenco.

È possibile assegnare a ciascuna chiamata diversi percorsi di dati. Ogni percorso viene estratto in modo indipendente e inviato al guardrail come un blocco di contenuto a sé stante, quindi per far sì che un elenco venga valutato come elementi distinti, assegna agli elementi un nome con percorsi separati anziché un percorso con caratteri jolly.

Importante

Un JSONPath non contiene alcun indicatore di direzione, quindi l'effetto della policy ne determina la direzione: suppressOutput legge la risposta e qualsiasi altro effetto legge la richiesta. Un guardrail di output che utilizza un JsonPath deve quindi essere unsuppressOutput, mentre uno di input può essere un o unforbid: entrambi leggono la richiesta. permit Non mischiate un JsonPath e un bare context.input.* field nella stessa chiamata undersuppressOutput: i due implicano direzioni opposte e la richiesta viene respinta come conflitto laterale.

Tutte le corrispondenze di un singolo JSONPath vengono concatenate in un'unica stringa, senza alcun carattere di separazione tra di esse. Questo è intenzionale: uno schema suddiviso su due blocchi di contenuto, ad esempio il numero di previdenza sociale 123- seguito da45-6789, rimane contiguo e non può sfuggire a un rilevatore che cerca l'intero pattern. Significa anche che il testo delle corrispondenze adiacenti scorre insieme, quindi un percorso che elimina campi non correlati può produrre un valore che nessun campo contiene.

Un percorso che non corrisponde a nulla non contribuisce a nulla, purché almeno un altro percorso configurato si risolva. Ciò consente di denominare diverse forme candidate in un'unica chiamata, per payload la cui struttura varia, e di utilizzare quella esistente come percorso utilizzato.

avvertimento

Un JSONPath non viene convalidato quando si crea la policy. A differenza di un percorso di campo, non AgentCore verifica né la sua sintassi né la sua compatibilità con lo schema. Un percorso non valido o un percorso che assegna un nome a un campo che il payload non invia mai, raggiunge comunque. ACTIVE Ciò che accade al momento della valutazione dipende dal fatto che qualcos'altro si risolva.

Se nessun percorso di dati configurato si risolve in un punto qualsiasi dell'ambito, la valutazione non viene chiusa. Non è possibile eseguire alcun guardrail, quindi la richiesta viene respintaAuthorization denied: request missing field(s) required for guardrail evaluation, indicando i percorsi che non è riuscita a risolvere. Il traffico che funzionava si interrompe. Controlla prima JSONPath quando riscontri questo errore.

Se almeno un percorso configurato si risolve, i guardrail con contenuto vengono eseguiti e decidono normalmente e viene ignorato solo il controllo il cui percorso non è stato risolto. Questo controllo non serve a nulla e non genera risultati, quindi un singolo percorso digitato erroneamente tra diversi percorsi funzionanti fallisce silenziosamente anziché a voce alta.

Testa ogni guardrail JsonPath confrontandolo con il contenuto che dovrebbe catturare e prendi i percorsi da Reaching text inside array con un JSONPath anziché adattarli da un'altra API.

Per esempi su ogni percorso dell'API di inferenza, consulta Raggiungere il testo all'interno degli array con un JsonPath.

Soglie per i guardrail

Grazie ai filtri di contenuto e al rilevamento tempestivo degli attacchi, il guardrail restituisce un punteggio di confidenza, che è un valore numerico compreso nell'intervallo [0, 1], dove 0 è bassa confidenza e 1 è alta. Il punteggio indica la sicurezza con cui il guardrail ha rilevato una violazione. I punteggi attualmente possibili sono i valori discreti {0.0, 0.2, 0.4, 0.6, 0.8, 1.0}.

Per impostare una soglia, fornite il valore decimale all'operatore di confronto, ad esempio. greaterThan(decimal("0.4"))

Operatori di confronto dei punteggi

È possibile applicare i seguenti operatori di confronto a confidenceScoremaxConfidenceScore(), oppureminConfidenceScore():

Operatore Utilizzo

.greaterThan(decimal("X.X"))

Punteggio > soglia

.greaterThanOrEqual(decimal("X.X"))

Punteggio ≥ soglia

.lessThan(decimal("X.X"))

Punteggio < soglia

.lessThanOrEqual(decimal("X.X"))

Punteggio ≤ soglia

Puoi utilizzare un'aggregazione nella tua politica per estrarre e confrontare i punteggi restituiti dai guardrail:

Aggregazioni

Aggregazione Description Esempio

[<category>].confidenceScore

Accedi al punteggio di confidenza per una categoria specifica (decimale). Non disponibile per. SensitiveInformation

["HATE"].confidenceScore

maxConfidenceScore()

Massima affidabilità in tutte le categorie scansionate (decimali)

.maxConfidenceScore()

minConfidenceScore()

Confidenza minima in tutte le categorie scansionate (decimale)

.minConfidenceScore()

count()

Numero di risultati rilevati (lungo). Confrontalo con un operatore intero, non con un decimal metodo.

.count() > 0

categories()

L'insieme di categorie rilevate dal guardrail (Set of String)

.categories().contains("HATE")

Importante

SensitiveInformationrichiede uno dei metodi di aggregazione e non supporta l'indicizzazione per categoria. Una dichiarazione come quella che BedrockGuardrails::SensitiveInformation(["EMAIL"], [context.input.text])["EMAIL"].confidenceScore viene rifiutata quando si crea la politica, con. Per-category indexing is not supported for SensitiveInformation Usacount(), categories()maxConfidenceScore(), o minConfidenceScore() invece. ContentFiltere PromptAttack supporta entrambi i moduli.

Come scegliere una soglia

Se non si specifica una soglia quando si richiede il servizio di creazione, AgentCore imposta un valore predefinito. Se si scrivono le politiche senza l'aiuto del servizio di creazione, è necessario fornire il valore di soglia.

Le seguenti impostazioni predefinite sono calibrate per fornire un'ampia copertura con una precisione accettabile per la maggior parte dei carichi di lavoro:

Tipo di guardrail Soglia predefinita

Filtro dei contenuti

0.2

Rilevamento tempestivo degli attacchi

0.4

Informazioni sensibili

0.2

Scelta di una soglia personalizzata

Se le soglie predefinite non soddisfano i tuoi requisiti, puoi determinare la soglia ottimale per il tuo carico di lavoro utilizzando uno dei seguenti approcci.

Opzione 1: valuta in base a un set di test aureo

Usa questo approccio quando disponi di una serie curata di input di test con risultati attesi chiari.

  1. Crea le tue politiche e imposta la modalità del motore delle politiche su LOG_ONLY.

  2. Esegui il set di test tramite il gateway a cui è collegato il tuo policy engine.

  3. Esamina i log per ogni valutazione. Ogni voce di registro include il contenuto valutato e il punteggio di confidenza restituito dal guardrail.

  4. Per ogni risultato, indica se il guardrail avrebbe dovuto contrassegnare il contenuto o non fare nulla (rispettivamente vero e falso).

  5. Utilizzando queste etichette, combinate con i punteggi di confidenza disponibili nei registri, create una matrice di confusione con più valori di soglia. Confrontate la precisione e il richiamo a ciascuna soglia per selezionare il valore in linea con la vostra tolleranza per i falsi positivi rispetto ai rilevamenti mancati.

Opzione 2: valutazione in base al traffico di produzione

Utilizzate questo approccio quando non disponete di un set di test predefinito e desiderate eseguire la calibrazione utilizzando modelli di traffico reali.

  1. Crea le tue politiche e imposta la modalità del motore delle politiche su LOG_ONLY.

  2. Consenti al motore delle politiche di valutare il traffico di produzione. Ogni voce di registro include il contenuto valutato e il punteggio di confidenza restituito dal guardrail.

  3. Usa an LLM-as-a-judge per etichettare ogni risultato registrato come vero (il guardrail avrebbe dovuto contrassegnare il contenuto) o false (il guardrail non avrebbe dovuto contrassegnare il contenuto).

  4. Usando queste etichette, crea una matrice di confusione con più valori di soglia. Confrontate la precisione e il richiamo a ciascuna soglia per selezionare il valore in linea con la vostra tolleranza per i falsi positivi rispetto ai rilevamenti non rilevati.

Testare i limiti di sicurezza in una politica

AgentCore fornisce diversi meccanismi per testare i guardrail prima di applicarli al traffico di produzione. È possibile controllare l'applicazione a livello di policy engine, a livello di policy individuale o entrambi, in modo da convalidare il comportamento del guardrail in modo incrementale. Per ulteriori informazioni, consulta Testare una policy in modalità LOG_ONLY.

Come funzionano i guardrail in una politica

Puoi inserire un guardrail in una policy su qualsiasi target del gateway. I guardrail funzionano su:

  • Obiettivi MCP: azione<TargetName>___<ToolName>, raggiunta tramite () POST /mcp JSON-RPC tools/call

  • AgentCore Obiettivi di runtime: azione <TargetName>___POST:/invocations

  • Obiettivi di inferenza: un obiettivo per forma dell'API, quindi un'azione per API:

    • <TargetName>___POST:/v1/chat/completions

    • <TargetName>___POST:/v1/responses

    • <TargetName>___POST:/v1/messages

    • <TargetName>___GET:/v1/models

  • Obiettivi proxy HTTP: azione <TargetName>___<METHOD>:<uri>

Quando una chiamata arriva al gateway, il Policy Evaluator esegue le seguenti operazioni:

  1. Corrisponde all'ambito: identifica quali politiche con guardrail si applicano a questa richiesta

  2. Estrae il contenuto: estrae il campo specificato da dataPath (ad esempio) dal corpo della richiesta context.input.message

  3. Richiama l' InvokeGuardrailChecks API Bedrock: valuta il contenuto e inserisce i punteggi di confidenza restituiti nel contesto di valutazione delle politiche

  4. Valuta la politica utilizzando i punteggi di guardrail: confronta i punteggi di confidenza restituiti con la soglia definita nella politica

  5. Restituisce una decisione, ALLOW o DENY con annotazioni sulla politica, al gateway

Nota: i guardrail non sono deterministici, quindi lo stesso input può generare output diversi. Le politiche sono deterministiche; lo stesso contesto di valutazione porterà sempre alla stessa decisione politica.

Limitazioni

  • Nessun supporto per regex o pattern matching: i guardrail utilizzano il punteggio ML, non le espressioni regolari

  • In un blocco è richiesto un guardrail: i when guardrails {…​} blocchi guardrail devono avere almeno un guardrail definito all'interno

  • Una chiamata guardrail non può leggere entrambi i lati di una richiesta: tutti i percorsi di dati in una chiamata devono essere uno o l'altro. context.input.* context.output.* Una suppressOutput policy può leggere entrambe le parti, ma non la stessa chiamata

  • I guardrail non sono deterministici: lo stesso contenuto può avere un punteggio diverso su chiamate separate, quindi una richiesta prossima alla soglia può essere accolta una volta e rifiutata la volta successiva

  • suppressOutputrichiede una condizione di guardrail: la sua condizione deve consistere esclusivamente in controlli di guardrail. Non supporta Cedar o condizioni standard temporal {…​}

  • Un $ percorso dati -JSONPath non viene convalidato al momento della creazione: non vengono verificate né la sua sintassi né la sua adattabilità allo schema. Se è l'unico percorso e non si risolve in nulla, la richiesta viene rifiutata anziché esaminata e il rifiuto indica il percorso irrisolto. Se un altro percorso si risolve, il controllo non risolto viene ignorato automaticamente. Vedi Passare il contesto al tuo guardrail

Nota

In base a un effetto di autorizzazione, permit oppureforbid, puoi combinare un guardrail con le normali condizioni Cedar in un'unica polizza. when guardrails { E }è equivalente a un piano when { E } il cui corpo richiama un guardrail; il guardrails tag documenta l'intento anziché limitare la politica. Inserisci la chiamata guardrail when e inserisci la richiesta o le condizioni principali. unless Una singola policy può comportare una chiamata guardrail, una condizione Cedar e una condizione temporale in questo modo: vedi Combinare un guardrail con condizioni di richiesta e Combina condizioni temporali, guardrail e richieste.

suppressOutputè l'eccezione: la sua condizione deve consistere esclusivamente nei controlli del guardrail. Per ulteriori informazioni, consulta Scrivere guardrails nelle politiche.