

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](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html) dan [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html), 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](runtime-how-it-works.md#runtime-platform-versions).

**Topics**
+ [Persyaratan](#runtime-lifecycle-hooks-requirements)
+ [Cara kerja panggilan kait](#runtime-lifecycle-hooks-how-it-works)
+ [Konfigurasikan kait siklus hidup](#runtime-lifecycle-hooks-configure)
+ [Kait yang didukung](#runtime-lifecycle-hooks-supported)
+ [Lihat log kait](#runtime-lifecycle-hooks-logs)

## Persyaratan
<a name="runtime-lifecycle-hooks-requirements"></a>
+ 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
<a name="runtime-lifecycle-hooks-how-it-works"></a>

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](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).

Bagaimana implementasi Anda melaporkan keberhasilan tergantung pada tindakan hook.

### Tindakan kait
<a name="runtime-lifecycle-hooks-actions"></a>

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

#### Tindakan HTTP
<a name="runtime-lifecycle-hooks-http-actions"></a>

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._~/-]*$`. <br />+  Ini dalam bentuk kanonik. Itu tidak berakhir pada `/` (kecuali jalan `/` itu sendiri), dan tidak mengandung `//`, atau `.` atau `..` segmen. <br />+  Ini tidak bertentangan dengan rute yang AgentCore Runtime sudah digunakan pada port yang sama. Untuk informasi lebih lanjut, lihat [Rute platform](#runtime-lifecycle-hooks-routes).  | 
|  `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](runtime-service-contract.md#runtime-reserved-ports). 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) <br />+   `GET /ws`  <br />+   `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](runtime-configure-invocation.md).

**catatan**  
Jika runtime agen Anda menggunakan [titik akhir sesi](runtime-session-endpoints.md), 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
<a name="runtime-lifecycle-hooks-configure"></a>

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](#runtime-lifecycle-hooks-warmup). Ganti Region, container image URI, dan peran eksekusi ARN dengan nilai-nilai Anda.

**Example**  

```python
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}")
```

```bash
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
<a name="runtime-lifecycle-hooks-supported"></a>


| 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](#runtime-lifecycle-hooks-warmup). | 

### Bangun kait pemanasan
<a name="runtime-lifecycle-hooks-warmup"></a>

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
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

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.

```python
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:

```bash
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](runtime-v2-optimize.md#runtime-v2-optimize-warmup).

## Lihat log kait
<a name="runtime-lifecycle-hooks-logs"></a>

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](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).