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 definire Bedrock Guardrails nelle policy. Bedrock Guardrails fornisce protezioni configurabili che possono essere eseguite sia su richieste che su risposte per proteggere le applicazioni AI. Attualmente è possibile definire un attacco tempestivo, un filtro dei contenuti e protezioni relative alle informazioni sensibili nella policy. Ogni guardrail deve essere configurato con una categoria e una soglia compresa tra 0 e 1.

Quando un guardrail valuta il contesto, restituisce un punteggio di confidenza compreso tra 0 e 1, che indica il grado di confidenza che il contenuto valutato presenti la proprietà definita (ad esempio). PROMPT_INJECTION

Disponibilità regionale dei guardrail

La tabella seguente mostra quali AWS regioni prevedono il ricorso ai guardrail nelle politiche:

Prima di iniziare

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

Permissions

Il ruolo di esecuzione del AgentCore gateway configurato sul gateway associato al motore delle policy deve disporre delle autorizzazioni sia per le AgentCore operazioni di Bedrock che per Bedrock Guardrails. L'bedrock:InvokeGuardrailChecksautorizzazione è necessaria perché il piano dati della policy utilizza le credenziali FAS (Forward Access Session) derivate dal ruolo di esecuzione del gateway per chiamare l'API Bedrock Guardrails per conto dell'utente.

{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "*"
    }
  ]
}

Guardrail supportati

Definire i guardrail nelle politiche

Per definire i guardrail nelle policy, puoi scrivere la policy come codice o descriverla in linguaggio naturale. Analogamente a qualsiasi policy esistente che potresti aver già creato, devi specificare un effetto (ad esempiopermit) con una condizione (when guardrails). In questa condizione, è necessario fornire la specifica protezione del guardrail che si desidera attivare, la categoria di protezione da utilizzare, il contesto che si desidera che la protezione guardrail valuti e la soglia del punteggio di confidenza.

Esempio di definizione del guardrail

suppressOutput (principal, action == AgentCore::Action::"<TARGET_NAME>_<METHOD>:<URI>", resource == AgentCore::Gateway::"<GATEWAY_ARN>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};

Specificazione di una protezione del guardrail

Per scegliere un tipo di entità di protezione specifico, usa il namespace: BedrockGuardrails

Selezione di una categoria di protezione

Seleziona una categoria per la protezione specificata (vediGuardrail supportati).

ad es. BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Effetti per i guardrail

Per creare guardrail da utilizzare nelle richieste di autorizzazione, usate gli effetti and. permit forbid Questi continuano a governare l'autorizzazione delle richieste.

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

Per creare barriere da utilizzare per sopprimere gli output di strumenti, agenti o modelli, usate l'effetto. suppressOutput suppressOutputè un nuovo effetto che opera 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) when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])["US_SOCIAL_SECURITY_NUMBER"]
    .confidenceScore
    .greaterThan(decimal("0.5"))
};

Trasferimento del contesto al guardrail

Quando si definiscono i guardrail nella policy, è necessario specificare 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 di accesso ai dati in base allo schema di richiesta o risposta.

ad es. [context.input.message, context.input.systemPrompt]

Soglie per i guardrail

Grazie ai filtri dei contenuti e al rilevamento tempestivo degli attacchi, il guardrail restituisce un punteggio di confidenza, che è un valore numerico compreso nell'intervallo [0, 1], dove 0 indica bassa confidenza e 1 è alta. Il punteggio indica la sicurezza con cui il guardrail ha rilevato una violazione. I punteggi attualmente possibili sono valori discreti {0, 0,2, 0,4, 0,6, 0,8 e 1,0}.

Per impostare una soglia, è necessario fornire il valore decimale all'operatore di confronto (ad es.). greaterThan(decimal("0.4"))

Operatori di confronto dei punteggi

È possibile applicare i seguenti operatori di confronto a uno qualsiasi deiconfidenceScore,maxConfidenceScore(), ominConfidenceScore():

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

Aggregazioni

Come scegliere una soglia

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

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

Scelta di una soglia personalizzata

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

Opzione 1: esegui la valutazione sulla base di un set di test d'oro

Usa questo approccio quando hai una serie accurata di input di test con risultati attesi chiari.

Opzione 2: valuta in base al traffico di produzione

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

Metti alla prova i guardrail nella politica

AgentCore fornisce diversi meccanismi per testare le politiche di guardrail prima di applicarle al traffico di produzione. È possibile controllare l'applicazione a livello di motore delle politiche, a livello di singola policy o entrambi, consentendo di convalidare il comportamento dei guardrail in modo incrementale. Per ulteriori informazioni, vedere test a policy.

Come funzionano i guardrails con le policy

Le politiche Guardrail possono essere applicate a qualsiasi destinazione del gateway. I guardrail vengono eseguiti su: * obiettivi MCP — POST /mcp (JSON-RPC tools/call) * obiettivi di runtime HTTP — * obiettivi di inferenza HTTP — POST /<target>/invocations POST /inference

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

Nota: i guardrail non sono deterministici. Lo stesso input può generare output diversi. Le politiche, tuttavia, sono deterministiche, lo stesso input produrrà sempre lo stesso risultato.

Limitazioni dei guardrail nelle politiche