# Getting started with guardrails in the AgentCore CLI
<a name="policy-guardrails-getting-started"></a>

Guardrails let you add content filtering policies to your agent’s gateway. When a request matches a policy rule (for example, violent content), the gateway blocks it before it reaches your agent.

This guide walks through setting up a guardrail that blocks violent content on an HTTP gateway using the AgentCore CLI. For reference details on the guardrail safeguards, categories, effects, and thresholds, see [guardrails in policies](policy-guardrails-in-policies.md).

**Topics**
+ [Prerequisites](#policy-guardrails-getting-started-prerequisites)
+ [Step 1: Create a project](#policy-guardrails-getting-started-create)
+ [Step 2: Wire the engine, gateway, and target](#policy-guardrails-getting-started-wire)
+ [Step 3: Deploy infrastructure first](#policy-guardrails-getting-started-deploy-infra)
+ [Step 4: Add the guardrail policy](#policy-guardrails-getting-started-add-policy)
+ [Step 5: Deploy the policies](#policy-guardrails-getting-started-deploy-policy)
+ [Step 6: Invoke through the gateway](#policy-guardrails-getting-started-invoke)
+ [Available guardrail categories](#policy-guardrails-getting-started-categories)
+ [Policy effects](#policy-guardrails-getting-started-effects)
+ [Step 7: Clean up](#policy-guardrails-getting-started-cleanup)

## Prerequisites
<a name="policy-guardrails-getting-started-prerequisites"></a>

Before starting, make sure you have the following:
+  ** AWS credentials** configured.
+  **A bootstrapped CDK environment**.

Install the AgentCore CLI:

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

Verify the installation:

```
agentcore --version
```

## Step 1: Create a project
<a name="policy-guardrails-getting-started-create"></a>

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

cd MyAgent
```

## Step 2: Wire the engine, gateway, and target
<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
```

## Step 3: Deploy infrastructure first
<a name="policy-guardrails-getting-started-deploy-infra"></a>

```
agentcore deploy
```

This deploys the runtime, gateway, gateway target, and policy engine. The policy itself is added next, because it needs the deployed gateway ARN.

## Step 4: Add the guardrail policy
<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
```

This generates a Cedar policy that blocks requests with violent content. You can also use the interactive wizard:

```
agentcore add policy
```

### Step 4b: Add a permissive policy
<a name="policy-guardrails-getting-started-add-permissive"></a>

Because a policy engine in ENFORCE mode denies all actions unless explicitly permitted, add a permissive policy so benign requests can pass through and reach your agent:

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

## Step 5: Deploy the policies
<a name="policy-guardrails-getting-started-deploy-policy"></a>

```
agentcore deploy
```

## Step 6: Invoke through the 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"
```

Expected blocked result (`forbid` \+ `ACTIVE`):

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

## Available guardrail categories
<a name="policy-guardrails-getting-started-categories"></a>


| Category | Filters | Description | 
| --- | --- | --- | 
|  `contentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULT`  | Content safety filters | 
|  `promptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | Prompt security filters | 
|  `sensitiveInformation`  |  `ADDRESS`, `EMAIL`, `PHONE`, `CREDIT_DEBIT_CARD_NUMBER`, and [more](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | PII detection | 

## Policy effects
<a name="policy-guardrails-getting-started-effects"></a>


| Effect | Behavior | 
| --- | --- | 
|  `forbid`  | Block requests that exceed the confidence threshold | 
|  `permit`  | Allow only requests below the threshold | 
|  `suppressOutput`  | Block the model’s response (output phase) when it exceeds the threshold | 

## Step 7: Clean up
<a name="policy-guardrails-getting-started-cleanup"></a>

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