# Introdução aos guardrails na CLI AgentCore
<a name="policy-guardrails-getting-started"></a>

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.](policy-guardrails-in-policies.md)

**Topics**
+ [Pré-requisitos](#policy-guardrails-getting-started-prerequisites)
+ [Etapa 1: criar um projeto](#policy-guardrails-getting-started-create)
+ [Etapa 2: Conecte o motor, o gateway e o alvo](#policy-guardrails-getting-started-wire)
+ [Etapa 3: implantar a infraestrutura primeiro](#policy-guardrails-getting-started-deploy-infra)
+ [Etapa 4: Adicionar a política de proteção](#policy-guardrails-getting-started-add-policy)
+ [Etapa 5: implantar as políticas](#policy-guardrails-getting-started-deploy-policy)
+ [Etapa 6: Invocar por meio do gateway](#policy-guardrails-getting-started-invoke)
+ [Categorias de guardrail disponíveis](#policy-guardrails-getting-started-categories)
+ [Efeitos políticos](#policy-guardrails-getting-started-effects)
+ [Etapa 7: limpar](#policy-guardrails-getting-started-cleanup)

## Pré-requisitos
<a name="policy-guardrails-getting-started-prerequisites"></a>

Antes de começar, verifique se você tem o seguinte:
+  ** AWS credenciais** configuradas.
+  **Um ambiente de CDK inicializado**.

Instale a AgentCore CLI:

```
npm install -g @aws/agentcore
```

Verifique a instalação:

```
agentcore --version
```

## Etapa 1: criar um projeto
<a name="policy-guardrails-getting-started-create"></a>

```
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
<a name="policy-guardrails-getting-started-wire"></a>

```
# 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
<a name="policy-guardrails-getting-started-deploy-infra"></a>

```
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
<a name="policy-guardrails-getting-started-add-policy"></a>

```
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
<a name="policy-guardrails-getting-started-add-permissive"></a>

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
<a name="policy-guardrails-getting-started-deploy-policy"></a>

```
agentcore deploy
```

## Etapa 6: Invocar por meio do gateway
<a name="policy-guardrails-getting-started-invoke"></a>

```
# 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
<a name="policy-guardrails-getting-started-categories"></a>


| Categoria | Filtros | Description | 
| --- | --- | --- | 
|  `contentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | Filtros de segurança de conteúdo | 
|  `promptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | Filtros de segurança imediatos | 
|  `sensitiveInformation`  |  `ADDRESS`,`EMAIL`,`PHONE`,`CREDIT_DEBIT_CARD_NUMBER`, e [muito mais](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | Detecção de PII | 

## Efeitos políticos
<a name="policy-guardrails-getting-started-effects"></a>


| Efeito | Comportamento | 
| --- | --- | 
|  `forbid`  | Bloqueie solicitações que excedam o limite de confiança | 
|  `permit`  | Permitir somente solicitações abaixo do limite | 
|  `suppressOutput`  | Bloqueie a resposta do modelo (fase de saída) quando ele excede o limite | 

## Etapa 7: limpar
<a name="policy-guardrails-getting-started-cleanup"></a>

```
agentcore remove all --json
agentcore deploy
```