# Pagar pembatas dalam kebijakan
<a name="policy-guardrails-in-policies"></a>

Bagian ini menjelaskan cara mendefinisikan Bedrock Guardrails dalam kebijakan. Bedrock Guardrails menyediakan perlindungan yang dapat dikonfigurasi yang dapat berjalan pada permintaan dan tanggapan untuk menjaga keamanan aplikasi AI. Saat ini Anda dapat menentukan serangan cepat, filter konten, dan pagar pembatas informasi sensitif dalam kebijakan. Setiap pagar pembatas harus dikonfigurasi dengan kategori dan ambang batas antara 0 dan 1.

Ketika pagar pembatas mengevaluasi konteks, ia mengembalikan skor kepercayaan antara 0 dan 1, menunjukkan tingkat kepercayaan bahwa konten yang dievaluasi menunjukkan properti yang ditentukan (misalnya). `PROMPT_INJECTION`

## Ketersediaan regional pagar pembatas
<a name="guardrails-regional-availability"></a>

Tabel berikut menunjukkan AWS Daerah mana yang memiliki dukungan untuk pagar pembatas dalam kebijakan:


|  | Timur AS (N. Virginia) | AS Timur (Ohio) | AS Barat (Oregon) | Eropa (Frankfurt) | Eropa (Irlandia) | Eropa (London) | Eropa (Paris) | Eropa (Stockholm) | Asia Pasifik (Mumbai) | Asia Pasifik (Singapura) | Asia Pasifik (Sydney) | Asia Pasifik (Tokyo) | Asia Pasifik (Seoul) | Kanada (Pusat) | Amerika Selatan (Sao Paulo) |  AWS GovCloud (US-West) | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| Support Guardrails | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 

## Sebelum Anda mulai
<a name="policy-guardrails-before-you-begin"></a>

Sebelum Anda mulai, Anda perlu mengkonfigurasi peran IAM Anda dengan benar.

### Izin
<a name="policy-guardrails-permissions"></a>

Peran Eksekusi AgentCore Gateway yang dikonfigurasi pada gateway yang terkait dengan mesin kebijakan Anda harus memiliki izin untuk AgentCore operasi Bedrock dan Bedrock Guardrails. `bedrock:InvokeGuardrailChecks`Izin diperlukan karena bidang data Kebijakan menggunakan kredensyal FAS (Forward Access Session) yang berasal dari peran eksekusi gateway untuk memanggil Bedrock Guardrails API atas nama Anda.

```
{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "*"
    }
  ]
}
```

### Pagar pembatas yang didukung
<a name="supported-guardrails"></a>


| Nama Safeguard | Jenis Entitas | Kategori Safeguard | 
| --- | --- | --- | 
| Filter konten |  `ContentFilter`  |  `VIOLENCE`, `HATE`, `SEXUAL`, `MISCONDUCT`, `INSULTS`  | 
| Deteksi serangan yang cepat |  `PromptAttack`  |  `JAILBREAK`, `PROMPT_INJECTION`, `PROMPT_LEAKAGE`  | 
| Informasi sensitif |  `SensitiveInformation`  |  `CREDIT_DEBIT_CARD_NUMBER`,`US_SOCIAL_SECURITY_NUMBER`,`EMAIL`,`PHONE`,,`ADDRESS`,`AWS_ACCESS_KEY`,`AWS_SECRET_KEY`,`PASSWORD`,`IP_ADDRESS`,`NAME`,`USERNAME`, dan [20\+ lainnya](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html)  | 

## Mendefinisikan pagar pembatas dalam kebijakan
<a name="defining-guardrails-in-policies"></a>

Untuk menentukan pagar pembatas dalam kebijakan, Anda dapat menulis kebijakan sebagai kode atau menjelaskan kebijakan dalam bahasa alami. Mirip dengan kebijakan yang ada yang mungkin telah Anda buat, Anda perlu menentukan efek (misalnya`permit`) dengan kondisi (`when guardrails`). Dalam kondisi tersebut, Anda perlu memberikan perlindungan pagar pembatas khusus yang ingin Anda aktifkan, kategori perlindungan yang akan digunakan, konteks yang Anda inginkan untuk dievaluasi oleh pelindung pagar pembatas, dan ambang batas skor kepercayaan.

 **Contoh definisi pagar pembatas** 

```
suppressOutput (principal, action == AgentCore::Action::"<TARGET_NAME>_<METHOD>:<URI>", resource == AgentCore::Gateway::"<GATEWAY_ARN>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};
```

### Menentukan perlindungan pagar pembatas
<a name="specifying-a-guardrail-safeguard"></a>

Untuk memilih jenis entitas safeguard tertentu, gunakan namespace: BedrockGuardrails 


| Pengamanan | Nama fungsi pagar pembatas | 
| --- | --- | 
| Filter Konten |  `BedrockGuardrails::ContentFilter`  | 
| Serangan Cepat |  `BedrockGuardrails::PromptAttack`  | 
| Informasi Sensitif |  `BedrockGuardrails::SensitiveInformation`  | 

### Memilih kategori perlindungan
<a name="selecting-a-safeguard-category"></a>

Pilih kategori untuk perlindungan yang diberikan (lihat). [Pagar pembatas yang didukung](#supported-guardrails)

mis. `BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])` 

### Efek untuk pagar pembatas
<a name="effects-for-guardrails"></a>

Untuk membuat pagar pembatas untuk digunakan dalam permintaan otorisasi, gunakan dan efek. `permit` `forbid` Ini terus mengatur otorisasi permintaan.

```
forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6"))
};
```

Untuk membuat pagar pembatas untuk digunakan dalam menekan output dari alat, agen, atau model, gunakan efeknya. `suppressOutput` `suppressOutput`adalah efek baru yang beroperasi pada data yang dikembalikan tindakan. Setelah tindakan resmi selesai, ia mengevaluasi output terhadap pagar pembatas dan menekan output ketika pagar pembatas dilanggar.

```
suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])["US_SOCIAL_SECURITY_NUMBER"]
    .confidenceScore
    .greaterThan(decimal("0.5"))
};
```

### Meneruskan konteks ke pagar pembatas Anda
<a name="passing-context-to-your-guardrail"></a>

Saat mendefinisikan pagar pembatas dalam kebijakan, Anda harus menentukan jalur data (misalnya`context.input.message`) yang mengidentifikasi nilai yang akan diekstrak dari muatan tindakan. Pagar pembatas mengevaluasi nilai yang diekstraksi. Anda dapat menentukan satu atau beberapa jalur ke data berdasarkan permintaan atau skema respons Anda.

mis. `[context.input.message, context.input.systemPrompt]` 

### Ambang batas untuk pagar pembatas
<a name="thresholds-for-guardrails"></a>

Dengan filter konten dan deteksi serangan cepat, pagar pembatas mengembalikan skor kepercayaan, yang merupakan nilai numerik dalam kisaran [0, 1], di mana 0 adalah kepercayaan rendah dan 1 adalah kepercayaan tinggi. Skor tersebut menunjukkan seberapa percaya diri pagar pembatas mendeteksi pelanggaran. Skor yang mungkin saat ini adalah nilai diskrit {0, 0.2, 0.4, 0.6, 0.8, dan 1.0}.

Untuk menetapkan ambang batas, Anda perlu memberikan nilai desimal ke operator perbandingan (misalnya). `greaterThan(decimal("0.4"))`

 **Operator perbandingan skor** 

Anda dapat menerapkan operator perbandingan di bawah ini ke salah satu dari`confidenceScore`,`maxConfidenceScore()`, atau`minConfidenceScore()`:


| Operator | Penggunaan | 
| --- | --- | 
|  `.greaterThan(decimal("X.X"))`  | Skor > ambang | 
|  `.greaterThanOrEqual(decimal("X.X"))`  | Skor ≥ ambang batas | 
|  `.lessThan(decimal("X.X"))`  | Skor < ambang batas | 
|  `.lessThanOrEqual(decimal("X.X"))`  | Skor ≤ ambang batas | 

Anda dapat menggunakan agregasi dalam kebijakan Anda untuk mengekstrak dan membandingkan skor yang dikembalikan oleh pagar pembatas:

 **Agregasi** 


| Agregasi | Deskripsi | Contoh | 
| --- | --- | --- | 
|  `[<category>].confidenceScore`  | Akses skor kepercayaan untuk kategori tertentu ([desimal](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `["HATE"].confidenceScore`  | 
|  `maxConfidenceScore()`  | Keyakinan maksimum di semua kategori yang dipindai ([desimal](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `.maxConfidenceScore()`  | 
|  `minConfidenceScore()`  | Keyakinan minimum di semua kategori yang dipindai ([desimal](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-decimal)) |  `.minConfidenceScore()`  | 
|  `count()`  | Jumlah temuan yang terdeteksi ([Panjang](https://docs.cedarpolicy.com/policies/syntax-datatypes.html#datatype-long)) |  `.count()`  | 

#### Bagaimana memilih ambang batas
<a name="how-to-choose-a-threshold"></a>

Jika Anda tidak menentukan ambang batas saat meminta layanan authoring, AgentCore tetapkan nilai default. Jika Anda menulis kebijakan Anda tanpa bantuan layanan authoring, Anda harus memberikan nilai ambang batas.

Default di bawah ini dikalibrasi untuk memberikan cakupan luas dengan presisi yang dapat diterima untuk sebagian besar beban kerja:


| Pengamanan | Ambang batas default | 
| --- | --- | 
| Filter Konten | 0.2 | 
| Deteksi Serangan Cepat | 0,4 | 
| Informasi Sensitif | 0.2 | 

##### Memilih ambang batas khusus
<a name="_choosing_a_custom_threshold"></a>

Jika ambang batas default tidak memenuhi persyaratan Anda, Anda dapat menentukan ambang batas optimal untuk beban kerja Anda menggunakan salah satu pendekatan berikut.

 **Opsi 1: Evaluasi terhadap set tes emas** 

Gunakan pendekatan ini ketika Anda memiliki serangkaian input pengujian yang dikuratori dengan hasil yang diharapkan yang jelas.

1. Buat kebijakan Anda dan setel mode mesin kebijakan Anda ke LOG\_ONLY.

1. Jalankan set pengujian Anda melalui gateway yang dilampirkan oleh mesin kebijakan Anda.

1. Tinjau log untuk setiap evaluasi. Setiap entri log mencakup konten yang dievaluasi dan skor kepercayaan yang dikembalikan oleh pagar pembatas.

1. Untuk setiap hasil, beri label apakah pagar pembatas seharusnya menandai konten atau tidak melakukan apa pun (masing-masing benar dan salah).

1. Dengan menggunakan label ini, dikombinasikan dengan skor kepercayaan yang tersedia di log Anda, buat matriks kebingungan pada beberapa nilai ambang batas. Bandingkan presisi dan ingat di setiap ambang batas untuk memilih nilai yang sesuai dengan toleransi Anda untuk positif palsu versus deteksi yang terlewat.

 **Opsi 2: Evaluasi terhadap lalu lintas produksi** 

Gunakan pendekatan ini ketika Anda tidak memiliki set pengujian pra-bangun dan ingin mengkalibrasi menggunakan pola lalu lintas nyata.

1. Buat kebijakan Anda dan setel mode mesin kebijakan Anda ke LOG\_ONLY.

1. Izinkan mesin kebijakan untuk mengevaluasi lalu lintas produksi. Setiap entri log mencakup konten yang dievaluasi dan skor kepercayaan yang dikembalikan oleh pagar pembatas.

1. Gunakan LLM-as-a-judge untuk memberi label pada setiap hasil yang dicatat sebagai true (pagar pembatas seharusnya menandai konten) atau false (pagar pembatas seharusnya tidak menandai konten).

1. Dengan menggunakan label ini, buat matriks kebingungan pada beberapa nilai ambang batas. Bandingkan presisi dan ingat di setiap ambang batas untuk memilih nilai yang sesuai dengan toleransi Anda untuk positif palsu versus deteksi yang terlewat.

### Uji pagar pembatas dalam kebijakan
<a name="_test_guardrails_in_policy"></a>

AgentCore menyediakan beberapa mekanisme untuk menguji kebijakan pagar pembatas sebelum menegakkannya pada lalu lintas produksi. Anda dapat mengontrol penegakan hukum di tingkat mesin kebijakan, di tingkat kebijakan individu, atau keduanya, memungkinkan Anda untuk memvalidasi perilaku pagar pembatas secara bertahap. Lihat [menguji kebijakan](policy-test-a-policy.md) untuk informasi selengkapnya.

## Bagaimana pagar pembatas bekerja dengan kebijakan
<a name="how-guardrails-works-with-policy"></a>

Kebijakan pagar pembatas dapat diterapkan ke target gateway apa pun. **Pagar pembatas berjalan pada: \* Target **MCP — `POST /mcp` (JSON-RPC `tools/call`) \* Target** **runtime HTTP — \* Target Inferensi** HTTP — `POST /<target>/invocations`** `POST /inference` 

Saat panggilan tiba di gateway Anda, Penilai Kebijakan melakukan hal berikut:

1.  **Lingkup kecocokan** - Mengidentifikasi kebijakan pagar pembatas mana yang berlaku untuk permintaan ini

1.  **Mengekstrak konten** - Menarik bidang yang ditentukan oleh `dataPath` (misalnya,`context.input.message`) dari badan permintaan

1.  **Calls Bedrock InvokeGuardrailChecks API** — Mengevaluasi konten dan menyuntikkan skor kepercayaan yang dikembalikan ke dalam konteks evaluasi kebijakan

1.  **Mengevaluasi kebijakan menggunakan skor pagar pembatas - Membandingkan skor** kepercayaan yang dikembalikan dengan ambang batas yang ditentukan dalam kebijakan

1.  **Mengembalikan keputusan** — `ALLOW` atau `DENY` dengan anotasi kebijakan kembali ke gateway

Catatan: Pagar pembatas tidak deterministik. Masukan yang sama dapat menghasilkan output yang berbeda. Kebijakan, bagaimanapun, bersifat deterministik, input yang sama akan selalu menghasilkan output yang sama.

## Batasan pagar pembatas dalam kebijakan
<a name="guardrails-in-policy-limitations"></a>
+  **Tidak ada dukungan untuk regex atau pencocokan pola** - pagar pembatas menggunakan penilaian HTML, bukan ekspresi reguler
+  **Anda tidak dapat mencampur kebijakan Cedar standar dengan pagar pembatas** — menggantikan `when guardrails {…​}` `when {…​}` 
+  **Pagar pembatas diperlukan di `when guardrails {…​}` blok — blok pagar pembatas harus memiliki setidaknya satu** pagar pembatas yang ditentukan di dalamnya