Guida introduttiva ai guardrail nella CLI AgentCore

Guardrails ti consente di aggiungere politiche di filtraggio dei contenuti al gateway del tuo agente. Quando una richiesta corrisponde a una regola di policy (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 del guardrail, consulta guardrails in policies.

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

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

Fase 2: Collegare il motore, il gateway e il bersaglio

# 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. La policy stessa viene aggiunta successivamente, poiché richiede il gateway ARN distribuito.

Fase 4: Aggiungere la politica 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 policy Cedar che blocca le richieste con contenuti violenti. Puoi anche usare la procedura guidata interattiva:

agentcore add policy

Fase 4b: Aggiungere una politica 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 politiche

agentcore deploy

Fase 6: Richiama 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 politici

Fase 7: pulire

agentcore remove all --json
agentcore deploy