View a markdown version of this page

Konfigurasikan kait siklus hidup untuk AgentCore Waktu pelaksanaan - Batu Dasar Amazon AgentCore

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

Konfigurasikan kait siklus hidup untuk AgentCore Waktu pelaksanaan

Kait siklus hidup adalah titik akhir dalam wadah Anda yang AgentCore Panggilan runtime pada titik tertentu dalam siklus proses runtime agen Anda. Gunakan kait untuk menjalankan kode Anda sendiri pada titik-titik tersebut, misalnya untuk mempersiapkan agen Anda sebelum sesi dimulai. Anda mengkonfigurasi kait dengan hooksConfiguration bidang CreateAgentRuntime dan UpdateAgentRuntime, dikelompokkan berdasarkan fase siklus hidup tempat mereka berada.

Kait siklus hidup tersedia untuk runtime agen yang menggunakan versi platform V2 di MicroVM. Untuk informasi lebih lanjut, lihat Versi platform.

Persyaratan

  • Runtime agen harus menggunakan versi platform V2. Pada V1, permintaan gagal dengan a ValidationException.

  • Runtime agen harus menggunakan tipe komputasi MicroVMS. Kait siklus hidup tidak didukung pada Instans: jika Anda menggabungkan hooksConfiguration bersama capacityProviderConfiguration, permintaan gagal dengan a ValidationException.

Cara kerja panggilan kait

Saat runtime agen Anda mencapai titik hook dalam siklus hidupnya, AgentCore Runtime menjalankan aksi hook sekali. Itu membuat satu permintaan ke wadah Anda dan menunggu implementasi Anda melaporkan keberhasilan dalam batas waktu hook. AgentCore Runtime tidak mencoba lagi panggilan hook.

Jika panggilan gagal, atau tidak berhasil dalam batas waktu, operasi yang memicu hook gagal. Misalnya, ketika build hook gagal, runtime pindah ke CREATE_FAILED atau UPDATE_FAILED dengan failureReason yang menggambarkan kegagalan. Untuk informasi lebih lanjut, lihat Memecahkan masalah kait siklus hidup.

Bagaimana implementasi Anda melaporkan keberhasilan tergantung pada tindakan hook.

Tindakan kait

Setiap kait memiliki satu tindakan, yang mendefinisikan bagaimana AgentCore Runtime memanggil wadah Anda.

Tindakan HTTP

Tindakan HTTP mengirimkan permintaan HTTP ke path dan port yang Anda pilih, di server di wadah Anda. Implementasi Anda melaporkan keberhasilan dengan mengembalikan apa pun 2xx kode status setelah pekerjaannya selesai. Kode status lainnya, atau koneksi yang gagal, gagal dalam panggilan. Setiap permintaan dapat menyertakan header yang mengidentifikasi panggilan. Setiap hook mencantumkan header dan nilai yang dikirimkannya.

Kait mendukung httpPost tindakan, yang mengirimkan POST permintaan. Anda mengkonfigurasinya di hook action.httpPost bidang, yang memiliki bidang berikut.

Bidang Jenis Diperlukan Deskripsi

path

Tali

Ya

Jalan yang AgentCore Runtime mengirim permintaan ke. Jalur harus memenuhi aturan ini:

  • Ini berisi 1-32 karakter dan cocok dengan pola ^/[A-Za-z0-9._~/-]*$.

  • Ini dalam bentuk kanonik. Itu tidak berakhir pada / (kecuali jalan / itu sendiri), dan tidak mengandung //, atau . atau .. segmen.

  • Ini tidak bertentangan dengan rute yang AgentCore Runtime sudah digunakan pada port yang sama. Untuk informasi lebih lanjut, lihat Rute platform.

port

Bilangan Bulat

Tidak

Pelabuhan yang AgentCore Runtime mengirim permintaan ke. Rentang yang didukung adalah 8000--12000, inklusif. Pilih port selain port platform yang dicadangkan. Jika Anda tidak menentukan port, defaultnya adalah port servis agen Anda: protocolConfiguration.port jika Anda mengaturnya, jika tidak port default protokol (8080 Untuk HTTP dan AG-UI, 8000 untuk MCP, dan 9000 untuk A2A).

Rute hook adalah metode HTTP, path, dan portnya. Tidak dapat mencocokkan rute yang AgentCore Runtime sudah digunakan pada port servis agen Anda. Tabel berikut mencantumkan rute platform ini.

Rute platform yang tidak dapat digunakan oleh hook
Protokol Rute yang tidak dapat digunakan pengait

Semua protokol

  • POST ke jalur pemanggilan: protocolConfiguration.path jika Anda mengaturnya, jika tidak, protokol default (/invocations Untuk HTTP dan AG-UI, /mcp untuk MCP, dan / untuk A2A)

  • GET /ws

  • GET /ping

MCP

POST /mcp, bahkan jika Anda mengubah jalur pemanggilan

A2A

GET /.well-known/agent-card.json

Konflik membandingkan metode serta jalurnya. Contohnya, POST /ping adalah rute kait yang valid, karena AgentCore Penggunaan runtime GET /ping. Untuk port penyajian dan jalur pemanggilan, lihat Konfigurasikan port penayangan agen dan jalur pemanggilan.

catatan

Jika runtime agen Anda menggunakan titik akhir sesi, AgentCore Runtime melindungi hook Anda dari permintaan titik akhir sesi:

  • Permintaan yang menargetkan rute hook ditolak dengan HTTP 403 dan AccessDenied sebelum mencapai wadah Anda. Pencocokan jalur mengabaikan case, dan memperlakukan ejaan ekuivalen umum dari jalur sebagai jalur yang sama. Ini termasuk garis miring berulang atau tertinggal, . dan .. segmen, karakter yang dikodekan persen, dan ; parameter.

  • Header kait dicadangkan. AgentCore Runtime menghapusnya dari permintaan titik akhir sesi, sehingga aplikasi Anda menerima header hook hanya pada panggilan hook.

Konfigurasikan kait siklus hidup

Tentukan hooksConfiguration saat Anda membuat atau memperbarui runtime agen. Contoh berikut membuat runtime V2 dengan hook pemanasan build yang memanggil POST /warmup di pelabuhan 8080. Untuk apa yang dilakukan kait, lihat Bangun kait pemanasan. Ganti Region, container image URI, dan peran eksekusi ARN dengan nilai-nilai Anda.

contoh
AWS SDK
import boto3 client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') try: response = client.create_agent_runtime( agentRuntimeName='my_agent_runtime', agentRuntimeArtifact={ 'containerConfiguration': { 'containerUri': '123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest' } }, networkConfiguration={'networkMode': 'PUBLIC'}, roleArn='arn:aws:iam::123456789012:role/AgentRuntimeRole', platformVersion='V2', hooksConfiguration={ 'build': { 'warmup': { 'action': { 'httpPost': { 'path': '/warmup', 'port': 8080 } } } } } ) print(f"Agent runtime created: {response['agentRuntimeArn']}") except client.exceptions.ValidationException as e: print(f"Validation error: {e}")
AWS CLI
aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name "my_agent_runtime" \ --role-arn "arn:aws:iam::123456789012:role/AgentRuntimeRole" \ --agent-runtime-artifact '{ "containerConfiguration": { "containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest" } }' \ --network-configuration '{"networkMode": "PUBLIC"}' \ --platform-version V2 \ --hooks-configuration '{ "build": { "warmup": { "action": { "httpPost": {"path": "/warmup", "port": 8080} } } } }'

UpdateAgentRuntime menggantikan seluruh konfigurasi kait. Termasuk hooksConfiguration di setiap permintaan pembaruan yang ingin Anda simpan kait Anda. Untuk menghapus kait Anda, hubungi UpdateAgentRuntime tanpa hooksConfiguration.

Kait yang didukung

Fase Kait Kapan AgentCore Runtime menyebutnya Gunakan untuk

build

warmup

Sementara itu mempersiapkan agen Anda, selama CreateAgentRuntime dan UpdateAgentRuntime

Siapkan memori dan disk sehingga sesi dimulai lebih cepat. Untuk informasi lebih lanjut, lihat Bangun kait pemanasan.

Bangun kait pemanasan

AgentCore Runtime memanggil hook pemanasan build saat mempersiapkan agen Anda, selama CreateAgentRuntime dan UpdateAgentRuntime, sebelum runtime mencapai READY. Itu membuat dua panggilan, dalam urutan ini, dan memberi tahu implementasi Anda yang menyebutnya:

Jenis pemanasan Order Apa yang harus dilakukan

memory

Pertama, setelah agen Anda melewatinya /ping pemeriksaan kesehatan

Muat ke dalam memori apa yang dibutuhkan setiap sesi, seperti impor, model, dan cache. Setiap instance baru dimulai dengan apa yang Anda muat di sini.

disk

Detik

Baca file yang dibaca agen Anda saat sesi dimulai. AgentCore Runtime menggunakan pembacaan ini untuk membuat file-file tersebut tersedia lebih cepat untuk sesi baru.

Dengan tindakan HTTP, AgentCore Runtime mengirimkan jenis pemanasan di X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type header, dengan nilai memory atau disk.

Kedua panggilan tersebut berbagi batas waktu total 120 detik. Karena memory panggilan berjalan lebih dulu, disk Panggilan mendapatkan waktu yang memory panggil daun. Misalnya, jika memory panggilan membutuhkan waktu 50 detik, disk Panggilan memiliki 70 detik. Anda tidak dapat mengubah batas ini.

Pengait pemanasan dapat menambah hingga 120 detik pada waktu itu CreateAgentRuntime dan UpdateAgentRuntime ambil untuk mencapai READY. Setiap baris log pemanasan dapat muncul lebih dari sekali untuk satu kali pembuatan atau pembaruan.

Tulis pengendali pemanasan

Handler pemanasan Anda berjalan di server agen Anda, di samping /ping dan handler pemanggilan Anda:

  • Simpan /ping responsif. Server Anda harus terus menjawab /ping sementara pemanasan berjalan. Jangan memblokir satu-satunya utas server Anda di dalam pengendali pemanasan. Jalankan pekerjaan di thread atau proses terpisah, atau gunakan server yang menangani permintaan secara bersamaan.

  • Kembali 2xx hanya setelah pekerjaan selesai. Apa yang telah Anda muat ketika Anda merespons adalah sesi yang dimulai dengan apa.

Aplikasi FastAPI berikut berfungsi /ping, /invocations, dan kait pemanasan di POST /warmup di pelabuhan 8080. Ini menjalankan pekerjaan pemanasan di utas pekerja, sehingga server terus menjawab /ping. Ganti load_shared_state dan STARTUP_FILES dengan pekerjaan dan file agen Anda sendiri.

import asyncio from fastapi import FastAPI, Request, Response app = FastAPI() # Files that each session reads when it starts. STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"] def load_shared_state(): # Load what every session needs into memory, such as heavy imports, # model weights, and caches. ... def read_startup_files(): # Read the files that a session reads when it starts, so that new # sessions can use them faster. for path in STARTUP_FILES: with open(path, "rb") as f: while f.read(1024 * 1024): pass @app.get("/ping") def ping(): return {"status": "Healthy"} @app.post("/warmup") async def warmup(request: Request): # Header lookup in Starlette and FastAPI is case-insensitive. warmup_type = request.headers.get( "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", "" ).lower() # Run the work in a worker thread so that /ping keeps answering. if warmup_type == "memory": await asyncio.to_thread(load_shared_state) elif warmup_type == "disk": await asyncio.to_thread(read_startup_files) # Respond only after the work is done. return Response(status_code=200) @app.post("/invocations") async def invoke(request: Request): payload = await request.json() # Per-request work runs here on every session. return {"response": payload.get("prompt", "")}

Jika Anda menyimpan aplikasi sebagai app.py, mulai di wadah Anda dengan perintah berikut:

uvicorn app:app --host 0.0.0.0 --port 8080

Untuk apa yang harus dimasukkan dalam setiap panggilan, lihat Siapkan memori dan disk dengan kait siklus hidup.

Lihat log kait

AgentCore Runtime menulis kemajuan dan hasil dari setiap panggilan hook build ke grup log runtime Anda, /aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT, dalam aliran log yang namanya dimulai dengan build-logs-. Setiap baris dimulai dengan [LIFECYCLE-HOOK <epoch-milliseconds>], diikuti oleh [LIFECYCLE] untuk kemajuan atau [ERROR] untuk kegagalan. Untuk garis dan cara menindaklanjutinya, lihat Memecahkan masalah kait siklus hidup.