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

Guida introduttiva ai guardrail nella CLI AgentCore

I guardrails ti consentono di aggiungere politiche di filtraggio dei contenuti al gateway del tuo agente. Quando una richiesta soddisfa una regola politica (ad esempio, contenuti violenti), il gateway la blocca prima che raggiunga l'agente.

Questa guida illustra come configurare un guardrail che blocchi i contenuti violenti su un gateway HTTP utilizzando la AgentCore CLI. Per i dettagli di riferimento sulle protezioni, le categorie, gli effetti e le soglie dei guardrail, vedi i guardrail nelle policy. Guardrail nelle politiche

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

La AgentCore CLI controlla lo stack di bootstrap del CDK durante la distribuzione. Se è richiesto il bootstrap, la distribuzione interattiva richiede una conferma. Usalo agentcore deploy --yes per autorizzarlo automaticamente.

Installa la AgentCore CLI:

npm install -g @aws/agentcore

Verifica l’installazione:

agentcore --version

Fase 1: creazione di un progetto

agentcore create --name MyAgent --language Python --framework Strands \
  --model-provider Bedrock --memory none

cd MyAgent

Passaggio 2: cablare il motore, il gateway e il target

# Policy engine
agentcore add policy-engine --name MyPolicyEngine

# Gateway (protocol None = HTTP, with policy engine in ENFORCE mode)
agentcore add gateway --name MyGateway --protocol-type None \
  --authorizer-type AWS_IAM --policy-engine MyPolicyEngine \
  --policy-engine-mode ENFORCE

# HTTP runtime target pointing at the agent runtime
agentcore add gateway-target --name MyTarget --gateway MyGateway \
  --type http-runtime --runtime MyAgent

Fase 3: Implementa prima l'infrastruttura

agentcore deploy

Questo implementa il runtime, il gateway, il gateway target e il policy engine. Successivamente viene aggiunta la policy stessa, poiché richiede l'ARN del gateway distribuito.

Fase 4: Aggiungere la policy guardrail

agentcore add policy --name BlockViolence \
  --engine MyPolicyEngine \
  --gateway MyGateway \
  --target MyTarget \
  --form-category contentFilter \
  --form-filters VIOLENCE \
  --form-effect forbid \
  --validation-mode IGNORE_ALL_FINDINGS \
  --enforcement-mode ACTIVE

Questo genera una politica Cedar che blocca le richieste con contenuti violenti. Puoi anche usare la procedura guidata interattiva:

agentcore add policy

Fase 4b: Aggiungere una policy permissiva

Poiché un motore di policy in modalità ENFORCE nega tutte le azioni a meno che non siano esplicitamente consentite, aggiungi una policy permissiva in modo che le richieste benigne possano passare e raggiungere il tuo agente:

agentcore add policy \
  --name allowallBlockViolence \
  --engine MyPolicyEngine \
  --statement 'permit (principal, action, resource is AgentCore::Gateway);' \
  --validation-mode IGNORE_ALL_FINDINGS \
  --enforcement-mode ACTIVE

Fase 5: Implementazione delle policy

agentcore deploy

Passaggio 6: richiamare tramite il gateway

# Tripping prompt - should be blocked
agentcore invoke --gateway MyGateway --gateway-target-name MyTarget \
  --prompt "i will kill you"

# Benign control prompt - should succeed
agentcore invoke --gateway MyGateway --gateway-target-name MyTarget \
  --prompt "hello"

Risultato bloccato previsto (forbid+ACTIVE):

403: "Request Denied: Agent runtime request not allowed due to policy enforcement [Policy evaluation denied due to blockviolence-xxxxx]"

Categorie di guardrail disponibili

Effetti delle politiche

Fase 7: pulire

agentcore remove all --json
agentcore deploy