Memulai Kebijakan di AgentCore

Dalam tutorial ini, Anda akan belajar cara mengatur Kebijakan AgentCore dan mengintegrasikannya dengan Amazon Bedrock AgentCore Gateway menggunakan AgentCore CLI. Anda akan membuat alat pemrosesan pengembalian dana dengan kebijakan Cedar yang memberlakukan aturan bisnis untuk jumlah pengembalian dana.

Prasyarat

Sebelum memulai, pastikan Anda memiliki yang berikut:

Langkah 1: Pengaturan dan instal

Instal AgentCore CLI:

npm install -g @aws/agentcore

Buat AgentCore proyek baru:

Langkah 2: Tambahkan gateway dengan mesin kebijakan

Gunakan AgentCore CLI untuk menambahkan gateway, target fungsi Lambda, dan mesin kebijakan ke proyek Anda.

Tambahkan gateway

Buat gateway tanpa otorisasi masuk (untuk kesederhanaan dalam tutorial ini) dan lampirkan agen Anda ke dalamnya:

Tambahkan target fungsi Lambda dengan alat pengembalian dana

Daftarkan fungsi Lambda Anda sebagai target gateway dengan skema alat yang mendefinisikan alat pemrosesan pengembalian dana:

Menambahkan mesin kebijakan

Buat mesin kebijakan dan lampirkan ke gateway dalam mode ENFORCE:

Buat kebijakan Cedar

Berikan file kebijakan Cedar secara langsung:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --source refund_policy.cedar

Atau, setelah menerapkan sumber daya Anda di Langkah 3, Anda dapat membuat kebijakan Cedar dari deskripsi bahasa alami:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --generate "Only allow refunds under 1000 dollars" \
  --gateway PolicyGateway

--generateBendera mengharuskan gateway untuk digunakan terlebih dahulu, karena memanggil AWS API yang membutuhkan ARN gateway untuk mengonversi bahasa alami menjadi Cedar. Pendekatan ini secara otomatis menyelesaikan ARN gateway, menjadikannya jalur paling sederhana untuk membuat kebijakan.

Memahami pengaturan

Perintah CLI di atas mengkonfigurasi beberapa sumber daya dalam proyek Anda AgentCore . Berikut penjelasan rinci dari masing-masing komponen.

Buat Gateway

Perintah agentcore add gateway membuat gateway yang bertindak sebagai titik akhir server MCP Anda. Pengaturan --authorizer-type NONE menonaktifkan otorisasi masuk untuk kesederhanaan dalam tutorial ini. Dalam produksi, gunakan otorisasi IAM atau JWT untuk mengamankan gateway Anda.

Tambahkan target Lambda

Perintah agentcore add gateway-target mendaftarkan fungsi Lambda sebagai target di gateway. File skema alat mendefinisikan input yang dapat diteruskan agen ke fungsi, seperti jumlah pengembalian dana.

Buat Mesin Kebijakan

Perintah agentcore add policy-engine menciptakan mesin kebijakan — kumpulan kebijakan Cedar yang mengevaluasi dan mengotorisasi panggilan alat agen. Mesin kebijakan mencegat semua permintaan di batas gateway dan menentukan apakah akan mengizinkan atau menolak setiap tindakan berdasarkan kebijakan yang ditentukan. Ini memberikan otorisasi deterministik di luar kode agen, memastikan penegakan keamanan yang konsisten terlepas dari bagaimana agen diimplementasikan.

Buat Kebijakan Cedar

Cedar adalah bahasa kebijakan sumber terbuka yang dikembangkan oleh AWS untuk menulis kebijakan otorisasi. Perintah agentcore add policy membuat kebijakan Cedar yang mengatur panggilan alat melalui gateway. Anda dapat membuat kebijakan dari deskripsi bahasa alami menggunakan--generate, atau menyediakan file kebijakan Cedar secara langsung menggunakan. --source

Berikut ini adalah contoh kebijakan Cedar yang memungkinkan pengembalian uang di bawah $1000:

permit(principal,
  action == AgentCore::Action::"RefundTarget___process_refund",
  resource == AgentCore::Gateway::"<gateway-arn>")
when {
  context.input.amount < 1000
};

Kebijakan ini menggunakan:

Lampirkan Kebijakan ke Gateway

--attach-mode ENFORCETanda --attach-to-gateways dan pada perintah agentcore add policy-engine melampirkan mesin kebijakan ke gateway dalam mode ENFORCE. Dalam mode ini:

Ini memastikan semua operasi agen melalui gateway diatur oleh kebijakan keamanan Anda.

Langkah 3: Deploy

Menyebarkan semua sumber daya ke AWS:

agentcore deploy

AgentCore CLI membuat gateway, mendaftarkan target Lambda, menyediakan mesin kebijakan, dan melampirkan kebijakan Cedar. Proses ini memakan waktu sekitar 2-3 menit.

Setelah penerapan selesai, Anda dapat memverifikasi status sumber daya Anda:

agentcore status

Langkah 4: Uji kebijakan

Uji kebijakan dengan mengirimkan permintaan ke gateway. Karena gateway menggunakan--authorizer-type NONE, Anda dapat mengirim permintaan langsung dengan curl.

Tes 1: Pengembalian dana $500 (harus diizinkan)

Jumlah pengembalian dana sebesar $500 berada di bawah batas $1000, sehingga mesin kebijakan mengizinkan permintaan:

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":500}}}'

Tes 2: Pengembalian dana $2000 (harus ditolak)

Jumlah pengembalian dana $2000 melebihi batas $1000, sehingga mesin kebijakan menolak permintaan:

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'

Apa yang telah Anda bangun

Melalui tutorial ini, Anda telah membuat:

Pemecahan masalah

Jika Anda mengalami masalah selama penyiapan atau pengujian, lihat masalah dan solusi umum berikut:

Bersihkan

Untuk menghapus sumber daya yang dibuat dalam tutorial ini, hapus gateway dan mesin kebijakan, lalu gunakan kembali:

agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy

Menghapus gateway tidak secara otomatis menghapus mesin kebijakan terlampirnya. Anda harus menghapus mesin kebijakan secara terpisah menggunakanagentcore remove policy-engine.