Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Memulai dengan 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 menegakkan aturan bisnis untuk jumlah pengembalian dana.

Prasyarat

Sebelum memulai, pastikan Anda memiliki yang berikut:

AgentCore CLI memeriksa tumpukan bootstrap CDK selama penerapan. Jika bootstrap diperlukan, penerapan interaktif meminta konfirmasi. Gunakan agentcore deploy --yes untuk mengotorisasinya secara otomatis.

Langkah 1: Setup 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. Buat refund_tools.json file di direktori proyek Anda dengan konten berikut:

[
  {
    "name": "process_refund",
    "description": "Process a customer refund request for a given dollar amount",
    "inputSchema": {
      "type": "object",
      "description": "Input for processing a refund",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "The refund amount in dollars"
        }
      },
      "required": ["amount"]
    }
  }
]

Menambahkan mesin kebijakan

Buat mesin kebijakan dan lampirkan ke gateway dalam mode ENFORCE:

Buat kebijakan Cedar

Berikan file kebijakan Cedar secara langsung. Cedar tidak mengizinkan sumber daya wildcard dalam pernyataan kebijakan. Ini memerlukan penyebaran dua fase: pertama penerapan tanpa kebijakan untuk membuat gateway, lalu ambil gateway ARN. Kemudian tambahkan kebijakan dan gunakan kembali.

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 ia memanggil AWS API yang membutuhkan gateway ARN untuk mengubah bahasa alami menjadi Cedar. Pendekatan ini secara otomatis menyelesaikan ARN gateway, menjadikannya jalur paling sederhana untuk membuat kebijakan.

Memahami penyiapannya

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

Buat Gateway

Per intah 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

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

Buat Mesin Kebijakan

Per intah agentcore add policy-engine membuat 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. Per intah 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 mengizinkan pengembalian uang di bawah USD $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 ENFORCEF --attach-to-gateways lag 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, dan menyediakan mesin kebijakan. Jika Anda menyediakan file kebijakan ARN-based Cedar, tambahkan setelah penerapan ini dan jalankan agentcore deploy lagi untuk melampirkannya. Proses ini memakan waktu sekitar 2-3 menit per penerapan.

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

agentcore status

Langkah 4: Uji kebijakan

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

URL gateway yang ditampilkan dalam output status agentcore adalah titik akhir dasar. Permintaan MCP pergi ke /mcp jalur pada titik akhir itu, jadi tambahkan /mcp ke URL sebelum mengirim permintaan.

Tes 1: Pengembalian uang USD $500 (harus diizinkan)

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

curl -X POST ++<GATEWAY_URL>++/mcp \
  -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 uang USD $2000 (harus ditolak)

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

curl -X POST ++<GATEWAY_URL>++/mcp \
  -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 yang terlampir. Anda harus menghapus mesin kebijakan secara terpisah menggunakanagentcore remove policy-engine.