本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
設定 AgentCore 執行期的生命週期掛鉤
生命週期關聯是容器中的端點,AgentCore 執行期會在代理執行期生命週期中的特定時間點呼叫該端點。使用勾點在這些點執行您自己的程式碼,例如在工作階段開始之前準備您的代理程式。您可以使用 CreateAgentRuntime 和 UpdateAgentRuntime hooksConfiguration 欄位來設定勾點,依其所屬的生命週期階段分組。
生命週期掛鉤適用於在微型虛擬機器上使用平台版本 V2 的代理程式執行期。 microVMs 如需詳細資訊,請參閱平台版本。
要求
-
代理程式執行時間必須使用平台版本 V2。在 V1 上,請求會失敗並顯示
ValidationException。 -
代理程式執行時間必須使用 microVMs運算類型。執行個體不支援生命週期掛鉤:如果您
hooksConfiguration與 結合capacityProviderConfiguration,請求會失敗並顯示ValidationException。
掛接呼叫的運作方式
當您的代理程式執行時間到達其生命週期中的勾點時,AgentCore 執行時間會執行勾點動作一次。它對您的容器發出單一請求,並等待您的實作在勾點時間限制內報告成功。AgentCore 執行期不會重試掛接呼叫。
如果呼叫失敗,或未在時間限制內成功,則觸發勾點的操作會失敗。例如,當組建勾點失敗時,執行時間會移至failureReason描述失敗的 CREATE_FAILED或 UPDATE_FAILED 。如需詳細資訊,請參閱針對生命週期掛鉤進行故障診斷。
您的實作如何報告成功取決於勾點的動作。
勾點動作
每個勾點都有一個動作,定義 AgentCore 執行期如何呼叫您的容器。
HTTP 動作
HTTP 動作會在您容器中的伺服器上,將 HTTP 請求傳送至port您選擇的 path和 。您的實作會在工作完成後傳回任何2xx狀態碼,以回報成功。任何其他狀態碼或連線失敗,呼叫會失敗。每個請求可能包含識別呼叫的標頭。每個勾點都會列出其傳送的標頭和值。
勾點支援傳送POST請求httpPost的動作。您可以在勾點的 action.httpPost 欄位中設定它,其中包含下列欄位。
| 欄位 | 類型 | 必要 | 描述 |
|---|---|---|---|
|
|
字串 |
是 |
AgentCore 執行期傳送請求的路徑。路徑必須符合下列規則:
|
|
|
整數 |
否 |
AgentCore 執行期傳送請求的連接埠。支援的範圍為 |
勾點的路由是其 HTTP 方法、路徑和連接埠。它無法比對 AgentCore 執行期已在客服人員的服務連接埠上使用的路由。下表列出這些平台路由。
| 通訊協定 | 勾點無法使用的路由 |
|---|---|
|
所有通訊協定 |
|
|
MCP |
|
|
A2A |
|
衝突會比較方法和路徑。例如, POST /ping 是有效的勾點路由,因為 AgentCore 執行期使用 GET /ping。如需您的服務連接埠和調用路徑,請參閱設定代理程式的服務連接埠和調用路徑。
如果您的代理程式執行期使用工作階段端點,AgentCore 執行期會保護您的勾點免於工作階段端點請求:
-
以勾點路由為目標的請求會遭到 HTTP 拒絕,
403並在到達您的容器AccessDenied之前遭到拒絕。路徑比對會忽略案例,並將路徑的常見同等拼寫視為相同的路徑。這些包括重複或結尾斜線、...區段、百分比編碼字元和;參數。 -
保留勾點標頭。AgentCore Runtime 會從工作階段端點請求中捨棄它們,因此您的應用程式只會在掛接呼叫時接收掛接標頭。
設定生命週期掛鉤
當您建立或更新代理程式執行時間hooksConfiguration時,請指定 。下列範例會使用在連接埠 POST /warmup 上呼叫的建置暖機掛鉤來建立 V2 執行期8080。如需勾點的功能,請參閱建置暖機勾點。將區域、容器映像 URI 和執行角色 ARN 取代為您的值。
範例
UpdateAgentRuntime 會取代整個勾點組態。在您要保留掛鉤的每個更新請求hooksConfiguration中包含 。若要移除掛鉤,請呼叫 UpdateAgentRuntime 而不使用 hooksConfiguration。
支援的掛鉤
| 階段 | 勾點 | 當 AgentCore Runtime 呼叫它時 | 將其用於 |
|---|---|---|---|
|
|
|
當它準備您的代理程式時,在 |
準備記憶體和磁碟,讓工作階段更快開始。如需詳細資訊,請參閱建置暖機掛鉤。 |
建置暖機掛勾
AgentCore 執行期會在準備您的代理程式時CreateAgentRuntimeUpdateAgentRuntime呼叫建置暖機掛鉤READY。它會依此順序進行兩次呼叫,並告知實作其呼叫方式:
| 暖機類型 | 順序 | 處理方式 |
|---|---|---|
|
|
首先,在您的代理程式通過運作 |
載入每個工作階段所需的記憶體,例如匯入、模型和快取。每個新執行個體都從您在此載入的內容開始。 |
|
|
秒 |
讀取您的代理程式在工作階段開始時讀取的檔案。AgentCore Runtime 使用這些讀取,讓這些檔案更快地可供新工作階段使用。 |
使用 HTTP 動作時,AgentCore Runtime 會在 X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type標頭中傳送暖機類型,且值為 memory或 disk。
這兩個呼叫總共共用 120 秒的時間限制。由於memory呼叫會先執行,disk因此呼叫會取得memory呼叫離開的時間。例如,如果memory呼叫需要 50 秒,則disk呼叫會有 70 秒。您無法變更此限制。
暖機掛鉤最多可以加 120 秒到到達 CreateAgentRuntimeUpdateAgentRuntime所需的時間READY。對於一個建立或更新,每個暖機日誌行可以出現多次。
寫入暖機處理常式
您的暖機處理常式會在代理程式的伺服器中執行,以及/ping您的調用處理常式:
-
保持
/ping回應。伺服器必須在暖機執行/ping時持續接聽。請勿在暖機處理常式內封鎖伺服器的唯一執行緒。在單獨的執行緒或程序中執行工作,或使用同時處理請求的伺服器。 -
2xx僅在工作完成後傳回 。您在回應時載入的內容是工作階段的開頭。
下列 FastAPI 應用程式在連接埠 POST /warmup上的 提供 /ping、 /invocations和暖機掛鉤8080。它會在工作者執行緒中執行暖機工作,因此伺服器會持續回答 /ping。STARTUP_FILES 將 load_shared_state和 取代為代理程式自己的工作和檔案。
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,請使用下列命令在容器中啟動應用程式:
uvicorn app:app --host 0.0.0.0 --port 8080
如需每個呼叫中要放置的內容,請參閱使用生命週期掛鉤準備記憶體和磁碟。
檢視掛鉤日誌
AgentCore 執行期會在名稱開頭為 的日誌串流中/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT,將每個組建掛鉤呼叫的進度和結果寫入執行期的日誌群組 build-logs-。每一行都以 開頭[LIFECYCLE-HOOK <epoch-milliseconds>],接著[LIFECYCLE]是進度或[ERROR]失敗。如需這些行以及如何對其採取行動,請參閱針對生命週期掛鉤進行故障診斷。