View a markdown version of this page

Optimalkan agen Anda untuk Amazon Bedrock AgentCore Waktu Pelaksanaan V2 - Batu Dasar Amazon AgentCore

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

Optimalkan agen Anda untuk Amazon Bedrock AgentCore Waktu Pelaksanaan V2

Batu Dasar Amazon AgentCore Runtime V2 memulai agen Anda dengan memulihkan snapshot. Ini mengubah cara Anda menyusun kode agen Anda. Pekerjaan yang dilakukan agen Anda saat startup ditangkap dalam snapshot dan dibagikan oleh setiap instans yang dipulihkan. Hasilkan nilai apa pun yang harus berbeda antar permintaan, atau yang dapat kedaluwarsa, di handler permintaan Anda sebagai gantinya. Topik ini menjelaskan cara menyusun agen Anda di sekitar pekerjaan startup dan pekerjaan per permintaan sehingga tetap benar setelah setiap pemulihan. Untuk ikhtisar platform versi V2, lihat Versi platform.

Agen Anda memiliki dua konteks eksekusi:

Startup

Kode yang berjalan sekali saat proses Anda dimulai, sebelumnya AgentCore Runtime mengambil snapshot. AgentCore Runtime menangkap kode ini dalam snapshot, dan setiap instance mewarisi hasilnya.

Penanganan permintaan

Kode di Anda /invocations pawang. Kode ini berjalan pada setiap permintaan pada setiap instance.

Gunakan satu aturan untuk memutuskan di mana kode berada. Hitung nilai saat startup jika tetap sama selama masa pakai snapshot. Hitung di handler Anda jika bervariasi per permintaan atau dapat kedaluwarsa. AgentCore Runtime mengambil satu snapshot per versi agen dan menggunakannya sampai Anda membuat atau memperbarui agen, sehingga umur snapshot adalah masa pakai versi tersebut.

Inisialisasi sekali saat startup

Lakukan pekerjaan yang mahal dan dapat digunakan kembali saat proses Anda dimulai, sebelum snapshot. Misalnya, impor dependensi, beban model beban, atau baca konfigurasi statis dari bundel penerapan Anda. Dengan AgentCore SDK, lakukan pekerjaan ini di cakupan modul, sebelum Anda memanggil app.run(). Agen Anda tidak mendengarkan pada port 8080 sampai app.run() berjalan, jadi tidak /ping dapat berhasil dan tidak ada snapshot yang dapat diambil sampai pekerjaan startup Anda selesai. Snapshot menangkap agen yang diinisialisasi sepenuhnya berdasarkan konstruksi, dan Anda tidak perlu melakukan gerbang /ping. Selesaikan inisialisasi dalam 120 detik setelah startup. Jika agen Anda tidak menjadi sehat tepat waktu, runtime gagal dalam pemeriksaan kesehatan. Untuk informasi lebih lanjut tentang /ping dan /invocations titik akhir, lihat Memahami AgentCore Kontrak layanan runtime.

import json, pathlib from bedrock_agentcore.runtime import BedrockAgentCoreApp # Runs once at import, before app.run() starts the server and before the # snapshot. Every restored instance inherits these objects. MODEL = load_model_weights() SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text()) app = BedrockAgentCoreApp() @app.entrypoint def invoke(payload): # Per-request work runs here on every instance. ... app.run() # starts listening on 8080; the snapshot is taken after this

Jika agen Anda menjalankan server HTTP-nya sendiri alih-alih AgentCore SDK, snapshot harus menangkap agen yang diinisialisasi sepenuhnya. Anda dapat melakukannya dengan salah satu dari dua cara berikut:

  • Laporkan status sehat dari /ping hanya setelah inisialisasi selesai.

  • Laporkan status sehat segera setelah server Anda dimulai, dan lakukan inisialisasi dalam hook siklus hidup memory menelepon. Sesi dimulai dengan apa yang dimuat panggilan itu. Untuk informasi selengkapnya, lihat Siapkan memori dan disk dengan kait siklus hidup.

Baca saja data saat startup yang sama untuk setiap instance dan tidak kedaluwarsa. Tangani nilai yang sensitif terhadap waktu, seperti kredenSIAL berumur pendek, di handler Anda.

catatan

Jangan menghitung apa pun saat startup yang Anda ubah tanpa menyebarkan ulang. Misalnya, katalog alat diambil dari AgentCore Gateway terlihat seperti nilai startup yang ideal karena lambat dan mahal untuk dimuat, tetapi cache saat startup membekukan inventaris alat agen Anda pada saat snapshot.

Siapkan memori dan disk dengan kait siklus hidup

Sementara AgentCore Runtime mempersiapkan agen Anda, hook siklus hidup pemanasan build membuat dua panggilan ke hook Anda, pertama memory dan kemudian disk, dan memberi tahu handler Anda yang menyebutnya. Misalnya, dengan tindakan HTTP, kedua panggilan masuk ke jalur dan port yang Anda konfigurasikan, dan X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type header mengidentifikasi panggilan. Di memory panggilan, jalankan inisialisasi yang membutuhkan server Anda untuk berjalan. Di disk panggil, baca file yang dibaca agen Anda saat sesi dimulai, sehingga sesi baru dapat menggunakannya lebih cepat. Ini membantu agen yang sesinya dimulai dengan membaca file besar, seperti biner besar, satu set paket Python yang berat, atau browser tanpa kepala.

Jenis pemanasan Apa yang dipersiapkannya Gunakan untuk

memory

Memori yang dimulai dengan setiap sesi

Inisialisasi yang membutuhkan server Anda untuk berjalan, atau yang ingin Anda lakukan setelahnya /ping melaporkan sehat

disk

File yang dibaca sesi saat dimulai

Membaca file-file tersebut, sehingga sesi baru dapat menggunakannya lebih cepat

Yang memory dan disk panggilan berbagi 120 detik, dan memory panggilan berjalan lebih dulu. Lakukan pekerjaan mahal di memory Panggil, dan pertahankan disk panggilan ke file yang dibaca satu sesi saat dimulai. Untuk cara mengkonfigurasi hook dan menulis handlernya, lihat Konfigurasikan kait siklus hidup untuk AgentCore Waktu pelaksanaan.

Jaga agar status per permintaan tetap segar

Snapshot diambil sekali dan dibagikan oleh setiap instans yang dipulihkan, sehingga nilai apa pun yang dihasilkan agen Anda saat startup identik di seluruh instans dan diperbaiki pada saat snapshot. Tangani nilai yang tidak dapat dibawa oleh snapshot di Anda /invocations pawang. Tabel berikut menjelaskan nilai yang harus dihitung di handler Anda alih-alih saat startup.

Untuk melakukannya: Lakukan di handler Alasan

Hasilkan nilai acak, pengidentifikasi, atau token

Panggilan os.urandom(), secrets, atau uuid.uuid4() pada setiap permintaan. Dalam Node.js, baca /dev/urandom pada setiap permintaan.

os.urandom() mengembalikan entropi baru hanya setiap kali Anda memanggilnya setelah pemulihan. Nilai yang dibaca saat startup disalin ke snapshot dan identik pada setiap contoh, betapapun baiknya sumber entropi saat dibaca. Yang random modul juga disemai saat startup, jadi instance yang dipulihkan mengulangi urutan yang sama. Dalam Node.js, crypto modul dapat mengulangi nilai di seluruh instance bahkan di handler. Untuk informasi lebih lanjut, lihat Gunakan pustaka kriptografi yang aman untuk snapshot di halaman ini.

Baca waktu saat ini

Hitung untuk setiap permintaan

Stempel waktu yang diambil saat startup diperbaiki pada saat snapshot.

Mengukur waktu yang telah berlalu

Ambil stempel waktu referensi di handler Anda

time.monotonic() tidak maju melalui pemulihan, jadi durasi yang diukur dari referensi startup salah tanpa terlihat salah.

Gunakan kredensi atau token

Segarkan mereka saat kedaluwarsa

KredenSIAL yang dimuat saat startup dapat kedaluwarsa sebelum instance dimulai.

Identifikasi instance atau pekerja

Hasilkan id per permintaan; jangan mendapatkannya dari host

Setiap instance yang dipulihkan melaporkan nama host yang sama (localhost) dan PID (1), jadi menggunakan keduanya sebagai id akan meruntuhkan metrik, aliran log, dan mengunci pemilik di seluruh armada.

Bangun klien yang dapat digunakan kembali saat startup, dan hitung nilai per permintaan pada setiap panggilan.

import os, time # Build reusable clients at startup, before the snapshot. Exercise them here too # (for example, with a warm-up call) so the setup the client caches — endpoint and # credential resolution, connection pool — is captured in the snapshot. client = build_client() warm_up(client) @app.entrypoint def invoke(payload): creds = get_credentials() # refreshed when expired, not read at startup request_id = os.urandom(16).hex() # unique per request now = time.time() # current time, not snapshot time # Handle the request.

Gunakan pustaka kriptografi yang aman untuk snapshot

Kapan AgentCore Runtime mengembalikan instance dari snapshot, setiap instance yang dibuat dari snapshot tersebut dimulai dengan salinan identik dari memori yang diambil pada waktu snapshot. Ini termasuk status internal generator nomor acak di dalam pustaka kriptografi, dan kunci, token, atau pengidentifikasi apa pun yang dibuat agen Anda selama inisialisasi. Kecuali status itu disegarkan setelah pemulihan, instance dapat menghasilkan nilai “acak” yang sama.

Batasan saat ini

Pada AgentCore Runtime, build pustaka kriptografi yang aman untuk snapshot tidak di-reset setelah pemulihan. Ini berlaku untuk penerapan kode langsung dan penerapan kontainer.

Solusi

  • Hasilkan rahasia, kunci, token, dan pengenal sesi saat menangani permintaan, bukan saat agen Anda memulai. Ini menghindari penggunaan nilai apa pun yang dibuat sebelumnya AgentCore Runtime mengambil snapshot di setiap instance yang dipulihkan dari snapshot itu.

  • Bahkan saat menangani permintaan, dapatkan nilai acak langsung dari sistem operasi, misalnya Python secrets atau os.urandom, Pergilah crypto/rand, atau membaca /dev/urandom. Jangan gunakan nilai acak dari pustaka kriptografi seperti OpenSSL, karena nilai tersebut dapat diulang di seluruh instance.

  • Dalam Node.js, crypto modul menggunakan OpenSSL. Ini termasuk crypto.randomBytes(), crypto.randomUUID() (juga dengan disableEntropyCache: true), crypto.randomInt(), crypto.getRandomValues(), dan paket yang dibangun di atasnya, seperti uuid. Nilai dari fungsi ini dapat diulang di seluruh instance, bahkan ketika Anda memanggilnya di handler Anda. Untuk mendapatkan nilai unik di Node.js, baca byte dari /dev/urandom.

Jaringan

Bangun klien saat startup dan harapkan koneksi kembali yang transparan

Soket yang Anda buka saat startup tidak bertahan dari pemulihan, tetapi pengaturan cache pustaka klien Anda di sekitarnya - penguraian model layanan, resolusi titik akhir, resolusi kredensia, dan kumpulan koneksi - berhasil. Bangun dan latih klien Anda saat startup, dan harapkan panggilan pertama setelah pemulihan untuk membangun kembali koneksi secara transparan.

Jangan gunakan nama host atau PID sebagai pengidentifikasi instance unik

Setiap instance yang dipulihkan dimulai dari snapshot yang sama dan melaporkan nama host dan ID proses yang sama. Hasilkan pengenal unik di setiap permintaan.

Hindari mengikat ke port sumber tetap

Setelah pemulihan, koneksi yang dipegang pada waktu snapshot dibuat kembali, dan port sumber tetap dapat bertabrakan dengan penggantian itu di dalam instance. Instans yang dipulihkan adalah microVM terpisah dengan ruang nama jaringannya sendiri, sehingga konflik ada di dalam instance, bukan di seluruh instans.

Cross-account metrik dan kuota

Untuk pemanggilan lintas akun, di mana prinsipal dalam satu akun memanggil runtime agen yang dimiliki oleh akun lain melalui kebijakan berbasis sumber daya, CloudWatch metrik dan penggunaan kuota batas tarif untuk pemanggilan dikaitkan dengan akun pemilik sumber daya. Pemilik sumber daya adalah akun yang memiliki runtime agen.

Anda juga dapat melihat metrik yang diperhitungkan dalam kuota Anda di Kuota Layanan konsol.