# CLI 中的护栏入门 AgentCore
<a name="policy-guardrails-getting-started"></a>

Guardrails 允许您将内容过滤策略添加到代理的网关。当请求与政策规则（例如暴力内容）相匹配时，网关会在请求到达您的代理之前将其阻止。

本指南介绍如何使用 CLI AgentCore 设置护栏，屏蔽 HTTP 网关上的暴力内容。有关护栏防护措施、类别、影响和阈值的参考详情，请参阅政策中的[护栏](policy-guardrails-in-policies.md)。

**Topics**
+ [先决条件](#policy-guardrails-getting-started-prerequisites)
+ [步骤 1：创建项目](#policy-guardrails-getting-started-create)
+ [第 2 步：连接引擎、网关和目标](#policy-guardrails-getting-started-wire)
+ [步骤 3：首先部署基础架构](#policy-guardrails-getting-started-deploy-infra)
+ [第 4 步：添加护栏政策](#policy-guardrails-getting-started-add-policy)
+ [步骤 5：部署策略](#policy-guardrails-getting-started-deploy-policy)
+ [步骤 6：通过网关调用](#policy-guardrails-getting-started-invoke)
+ [可用的护栏类别](#policy-guardrails-getting-started-categories)
+ [政策影响](#policy-guardrails-getting-started-effects)
+ [步骤 7：清除](#policy-guardrails-getting-started-cleanup)

## 先决条件
<a name="policy-guardrails-getting-started-prerequisites"></a>

在开始之前，请确保您具备以下条件：
+  AWS 已配置@@ **凭据**。
+  **一个自启动的 CDK 环境**。

安装 C AgentCore LI：

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

验证安装：

```
agentcore --version
```

## 步骤 1：创建项目
<a name="policy-guardrails-getting-started-create"></a>

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

cd MyAgent
```

## 第 2 步：连接引擎、网关和目标
<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
```

## 步骤 3：首先部署基础架构
<a name="policy-guardrails-getting-started-deploy-infra"></a>

```
agentcore deploy
```

这将部署运行时、网关、网关目标和策略引擎。接下来将添加策略本身，因为它需要已部署的网关 ARN。

## 第 4 步：添加护栏政策
<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
```

这会生成一个 Cedar 政策，该策略可以阻止包含暴力内容的请求。您也可以使用交互式向导：

```
agentcore add policy
```

### 步骤 4b：添加宽松策略
<a name="policy-guardrails-getting-started-add-permissive"></a>

由于除非明确允许，否则处于 “强制” 模式的策略引擎会拒绝所有操作，因此请添加允许策略，这样良性请求就可以通过并到达您的代理：

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

## 步骤 5：部署策略
<a name="policy-guardrails-getting-started-deploy-policy"></a>

```
agentcore deploy
```

## 步骤 6：通过网关调用
<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"
```

预期屏蔽结果 (`forbid`\+`ACTIVE`)：

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

## 可用的护栏类别
<a name="policy-guardrails-getting-started-categories"></a>


| 类别 | 筛选条件 | 说明 | 
| --- | --- | --- | 
|  `contentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | 内容安全过滤器 | 
|  `promptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | 提示安全过滤器 | 
|  `sensitiveInformation`  |  `ADDRESS`、`EMAIL``PHONE`、`CREDIT_DEBIT_CARD_NUMBER`、、[等等](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | 个人身份信息检测 | 

## 政策影响
<a name="policy-guardrails-getting-started-effects"></a>


| 效果 | 行为 | 
| --- | --- | 
|  `forbid`  | 阻止超过可信度阈值的请求 | 
|  `permit`  | 仅允许低于阈值的请求 | 
|  `suppressOutput`  | 当模型的响应（输出阶段）超过阈值时，将其屏蔽 | 

## 步骤 7：清除
<a name="policy-guardrails-getting-started-cleanup"></a>

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