Introdução aos guardrails na CLI AgentCore

Os guardrails permitem que você adicione políticas de filtragem de conteúdo ao gateway do seu agente. Quando uma solicitação corresponde a uma regra de política (por exemplo, conteúdo violento), o gateway a bloqueia antes que ela chegue ao seu agente.

Este guia explica como configurar uma grade de proteção que bloqueia conteúdo violento em um gateway HTTP usando a CLI AgentCore . Para obter detalhes de referência sobre as proteções, categorias, efeitos e limites de proteção, consulte proteções nas políticas.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

Instale a AgentCore CLI:

npm install -g @aws/agentcore

Verifique a instalação:

agentcore --version

Etapa 1: criar um projeto

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

cd MyAgent

Etapa 2: Conecte o motor, o gateway e o alvo

# 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

Etapa 3: implantar a infraestrutura primeiro

agentcore deploy

Isso implanta o tempo de execução, o gateway, o destino do gateway e o mecanismo de políticas. A política em si é adicionada em seguida, porque ela precisa do ARN do gateway implantado.

Etapa 4: Adicionar a política de proteção

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

Isso gera uma política do Cedar que bloqueia solicitações com conteúdo violento. Você também pode usar o assistente interativo:

agentcore add policy

Etapa 4b: Adicionar uma política permissiva

Como um mecanismo de política no modo ENFORCE nega todas as ações, a menos que seja explicitamente permitido, adicione uma política permissiva para que solicitações benignas possam passar e chegar ao seu agente:

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

Etapa 5: implantar as políticas

agentcore deploy

Etapa 6: Invocar por meio do 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"

Resultado bloqueado esperado (forbid+ACTIVE):

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

Categorias de guardrail disponíveis

Efeitos políticos

Etapa 7: limpar

agentcore remove all --json
agentcore deploy