# AgentCore CLI 中的護欄入門
<a name="policy-guardrails-getting-started"></a>

護欄可讓您將內容篩選政策新增至代理程式的閘道。當請求符合政策規則 （例如暴力內容） 時，閘道會在到達您的代理程式之前封鎖它。

本指南逐步解說如何使用 AgentCore CLI 設定護欄，以封鎖 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 環境**。

安裝 AgentCore CLI：

```
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>

由於 ENFORCE 模式的政策引擎拒絕所有動作，除非明確允許，否則請新增寬鬆政策，讓良性請求可以通過並到達您的代理：

```
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>


| Category | 篩選條件 | 說明 | 
| --- | --- | --- | 
|  `contentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | 內容安全篩選條件 | 
|  `promptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | 提示安全性篩選條件 | 
|  `sensitiveInformation`  |  `ADDRESS`、`EMAIL`、`CREDIT_DEBIT_CARD_NUMBER`、 `PHONE`[等](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | PII 偵測 | 

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


| Effect | Behavior (行為) | 
| --- | --- | 
|  `forbid`  | 超過可信度閾值的封鎖請求 | 
|  `permit`  | 僅允許低於閾值的請求 | 
|  `suppressOutput`  | 當模型超過閾值時封鎖模型的回應 （輸出階段） | 

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

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