

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定 AgentCore 執行期的生命週期掛鉤

生命週期關聯是容器中的端點，AgentCore 執行期會在代理執行期生命週期中的特定時間點呼叫該端點。使用勾點在這些點執行您自己的程式碼，例如在工作階段開始之前準備您的代理程式。您可以使用 [CreateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html) 和 [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html) `hooksConfiguration` 欄位來設定勾點，依其所屬的生命週期階段分組。

生命週期掛鉤適用於在微型虛擬機器上使用平台版本 V2 的代理程式執行期。 microVMs 如需詳細資訊，請參閱[平台版本](runtime-how-it-works.md#runtime-platform-versions)。

**Topics**
+ [要求](#runtime-lifecycle-hooks-requirements)
+ [掛接呼叫的運作方式](#runtime-lifecycle-hooks-how-it-works)
+ [設定生命週期掛鉤](#runtime-lifecycle-hooks-configure)
+ [支援的掛鉤](#runtime-lifecycle-hooks-supported)
+ [檢視掛鉤日誌](#runtime-lifecycle-hooks-logs)

## 要求
<a name="runtime-lifecycle-hooks-requirements"></a>
+ 代理程式執行時間必須使用平台版本 V2。在 V1 上，請求會失敗並顯示 `ValidationException`。
+ 代理程式執行時間必須使用 microVMs運算類型。執行個體不支援生命週期掛鉤：如果您`hooksConfiguration`與 結合`capacityProviderConfiguration`，請求會失敗並顯示 `ValidationException`。

## 掛接呼叫的運作方式
<a name="runtime-lifecycle-hooks-how-it-works"></a>

當您的代理程式執行時間到達其生命週期中的勾點時，AgentCore 執行時間會執行勾點動作一次。它對您的容器發出單一請求，並等待您的實作在勾點時間限制內報告成功。AgentCore 執行期不會重試掛接呼叫。

如果呼叫失敗，或未在時間限制內成功，則觸發勾點的操作會失敗。例如，當組建勾點失敗時，執行時間會移至`failureReason`描述失敗的 `CREATE_FAILED`或 `UPDATE_FAILED` 。如需詳細資訊，請參閱[針對生命週期掛鉤進行故障診斷](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks)。

您的實作如何報告成功取決於勾點的動作。

### 勾點動作
<a name="runtime-lifecycle-hooks-actions"></a>

每個勾點都有一個動作，定義 AgentCore 執行期如何呼叫您的容器。

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

HTTP 動作會在您容器中的伺服器上，將 HTTP 請求傳送至`port`您選擇的 `path`和 。您的實作會在工作完成後傳回任何`2xx`狀態碼，以回報成功。任何其他狀態碼或連線失敗，呼叫會失敗。每個請求可能包含識別呼叫的標頭。每個勾點都會列出其傳送的標頭和值。

勾點支援傳送`POST`請求`httpPost`的動作。您可以在勾點的 `action.httpPost` 欄位中設定它，其中包含下列欄位。


| 欄位 | 類型 | 必要 | 描述 | 
| --- | --- | --- | --- | 
|  `path`  | 字串 | 是 | AgentCore 執行期傳送請求的路徑。路徑必須符合下列規則：+  它包含 1-32 個字元，並符合模式 `^/[A-Za-z0-9._~/-]*$`。 <br />+  它採用正式形式。它不會以 結尾 `/`（路徑`/`本身除外），也不會包含 `//`、 或 `.``..`區段。 <br />+  它不會與 AgentCore 執行期已在相同連接埠上使用的路由衝突。如需詳細資訊，請參閱[平台路由](#runtime-lifecycle-hooks-routes)。  | 
|  `port`  | 整數 | 否 | AgentCore 執行期傳送請求的連接埠。支援的範圍為 `8000`–`12000`，包含 。選擇[預留平台連接埠以外的連接埠](runtime-service-contract.md#runtime-reserved-ports)。如果您未指定連接埠，則預設為代理程式的服務連接埠：`protocolConfiguration.port`如果您設定它，否則通訊協定的預設連接埠 (`8080`適用於 HTTP 和 AG-UI、`8000`適用於 MCP 和`9000`適用於 A2A)。 | 

勾點的路由是其 HTTP 方法、路徑和連接埠。它無法比對 AgentCore 執行期已在客服人員的服務連接埠上使用的路由。下表列出這些平台路由。


**勾點無法使用的平台路由**  

| 通訊協定 | 勾點無法使用的路由 | 
| --- | --- | 
| 所有通訊協定 |  +   `POST` 至呼叫路徑：`protocolConfiguration.path`如果您設定它，否則通訊協定的預設 (`/invocations`適用於 HTTP 和 AG-UI、`/mcp`適用於 MCP 和`/`適用於 A2A) <br />+   `GET /ws`  <br />+   `GET /ping`    | 
| MCP |  `POST /mcp`，即使您變更調用路徑 | 
| A2A |  `GET /.well-known/agent-card.json`  | 

衝突會比較方法和路徑。例如， `POST /ping` 是有效的勾點路由，因為 AgentCore 執行期使用 `GET /ping`。如需您的服務連接埠和調用路徑，請參閱[設定代理程式的服務連接埠和調用路徑](runtime-configure-invocation.md)。

**注意**  
如果您的代理程式執行期使用[工作階段端點](runtime-session-endpoints.md)，AgentCore 執行期會保護您的勾點免於工作階段端點請求：  
以勾點路由為目標的請求會遭到 HTTP 拒絕，`403`並在到達您的容器`AccessDenied`之前遭到拒絕。路徑比對會忽略案例，並將路徑的常見同等拼寫視為相同的路徑。這些包括重複或結尾斜線、`.``..`區段、百分比編碼字元和`;`參數。
保留勾點標頭。AgentCore Runtime 會從工作階段端點請求中捨棄它們，因此您的應用程式只會在掛接呼叫時接收掛接標頭。

## 設定生命週期掛鉤
<a name="runtime-lifecycle-hooks-configure"></a>

當您建立或更新代理程式執行時間`hooksConfiguration`時，請指定 。下列範例會使用在連接埠 `POST /warmup` 上呼叫的建置暖機掛鉤來建立 V2 執行期`8080`。如需勾點的功能，請參閱[建置暖機勾點](#runtime-lifecycle-hooks-warmup)。將區域、容器映像 URI 和執行角色 ARN 取代為您的值。

**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` 會取代整個勾點組態。在您要保留掛鉤的每個更新請求`hooksConfiguration`中包含 。若要移除掛鉤，請呼叫 `UpdateAgentRuntime` 而不使用 `hooksConfiguration`。

## 支援的掛鉤
<a name="runtime-lifecycle-hooks-supported"></a>


| 階段 | 勾點 | 當 AgentCore Runtime 呼叫它時 | 將其用於 | 
| --- | --- | --- | --- | 
|  `build`  |  `warmup`  | 當它準備您的代理程式時，在 `CreateAgentRuntime`和 期間 `UpdateAgentRuntime`  | 準備記憶體和磁碟，讓工作階段更快開始。如需詳細資訊，請參閱[建置暖機掛鉤](#runtime-lifecycle-hooks-warmup)。 | 

### 建置暖機掛勾
<a name="runtime-lifecycle-hooks-warmup"></a>

AgentCore 執行期會在準備您的代理程式時`CreateAgentRuntime``UpdateAgentRuntime`呼叫建置暖機掛鉤`READY`。它會依此順序進行兩次呼叫，並告知實作其呼叫方式：


| 暖機類型 | 順序 | 處理方式 | 
| --- | --- | --- | 
|  `memory`  | 首先，在您的代理程式通過運作`/ping`狀態檢查之後 | 載入每個工作階段所需的記憶體，例如匯入、模型和快取。每個新執行個體都從您在此載入的內容開始。 | 
|  `disk`  | 秒 | 讀取您的代理程式在工作階段開始時讀取的檔案。AgentCore Runtime 使用這些讀取，讓這些檔案更快地可供新工作階段使用。 | 

使用 HTTP 動作時，AgentCore Runtime 會在 `X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type`標頭中傳送暖機類型，且值為 `memory`或 `disk`。

這兩個呼叫總共共用 120 秒的時間限制。由於`memory`呼叫會先執行，`disk`因此呼叫會取得`memory`呼叫離開的時間。例如，如果`memory`呼叫需要 50 秒，則`disk`呼叫會有 70 秒。您無法變更此限制。

暖機掛鉤最多可以加 120 秒到到達 `CreateAgentRuntime``UpdateAgentRuntime`所需的時間`READY`。對於一個建立或更新，每個暖機日誌行可以出現多次。

#### 寫入暖機處理常式
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

您的暖機處理常式會在代理程式的伺服器中執行，以及`/ping`您的調用處理常式：
+  **保持`/ping`回應。**伺服器必須在暖機執行`/ping`時持續接聽。請勿在暖機處理常式內封鎖伺服器的唯一執行緒。在單獨的執行緒或程序中執行工作，或使用同時處理請求的伺服器。
+  **`2xx`僅在工作完成後傳回 。**您在回應時載入的內容是工作階段的開頭。

下列 FastAPI 應用程式在連接埠 `POST /warmup`上的 提供 `/ping`、 `/invocations`和暖機掛鉤`8080`。它會在工作者執行緒中執行暖機工作，因此伺服器會持續回答 `/ping`。`STARTUP_FILES` 將 `load_shared_state`和 取代為代理程式自己的工作和檔案。

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

如果您將應用程式儲存為 `app.py`，請使用下列命令在容器中啟動應用程式：

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

如需每個呼叫中要放置的內容，請參閱[使用生命週期掛鉤準備記憶體和磁碟](runtime-v2-optimize.md#runtime-v2-optimize-warmup)。

## 檢視掛鉤日誌
<a name="runtime-lifecycle-hooks-logs"></a>

AgentCore 執行期會在名稱開頭為 的日誌串流中`/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT`，將每個組建掛鉤呼叫的進度和結果寫入執行期的日誌群組 `build-logs-`。每一行都以 開頭`[LIFECYCLE-HOOK <epoch-milliseconds>]`，接著`[LIFECYCLE]`是進度或`[ERROR]`失敗。如需這些行以及如何對其採取行動，請參閱[針對生命週期掛鉤進行故障診斷](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks)。