View a markdown version of this page

設定 AgentCore 執行期的生命週期掛鉤 - Amazon Bedrock AgentCore

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

設定 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 欄位中設定它,其中包含下列欄位。

欄位 類型 必要 描述

path

字串

是

AgentCore 執行期傳送請求的路徑。路徑必須符合下列規則:

  • 它包含 1-32 個字元,並符合模式 ^/[A-Za-z0-9._~/-]*$。

  • 它採用正式形式。它不會以 結尾 /(路徑/本身除外),也不會包含 //、 或 ...區段。

  • 它不會與 AgentCore 執行期已在相同連接埠上使用的路由衝突。如需詳細資訊,請參閱平台路由。

port

整數

否

AgentCore 執行期傳送請求的連接埠。支援的範圍為 8000–12000,包含 。選擇預留平台連接埠以外的連接埠。如果您未指定連接埠,則預設為代理程式的服務連接埠:protocolConfiguration.port如果您設定它,否則通訊協定的預設連接埠 (8080適用於 HTTP 和 AG-UI、8000適用於 MCP 和9000適用於 A2A)。

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

勾點無法使用的平台路由
通訊協定 勾點無法使用的路由

所有通訊協定

  • POST 至呼叫路徑:protocolConfiguration.path如果您設定它,否則通訊協定的預設 (/invocations適用於 HTTP 和 AG-UI、/mcp適用於 MCP 和/適用於 A2A)

  • GET /ws

  • GET /ping

MCP

POST /mcp,即使您變更調用路徑

A2A

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

衝突會比較方法和路徑。例如, POST /ping 是有效的勾點路由,因為 AgentCore 執行期使用 GET /ping。如需您的服務連接埠和調用路徑,請參閱設定代理程式的服務連接埠和調用路徑。

注意

如果您的代理程式執行期使用工作階段端點,AgentCore 執行期會保護您的勾點免於工作階段端點請求:

  • 以勾點路由為目標的請求會遭到 HTTP 拒絕,403並在到達您的容器AccessDenied之前遭到拒絕。路徑比對會忽略案例,並將路徑的常見同等拼寫視為相同的路徑。這些包括重複或結尾斜線、...區段、百分比編碼字元和;參數。

  • 保留勾點標頭。AgentCore Runtime 會從工作階段端點請求中捨棄它們,因此您的應用程式只會在掛接呼叫時接收掛接標頭。

設定生命週期掛鉤

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

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

支援的掛鉤

階段 勾點 當 AgentCore Runtime 呼叫它時 將其用於

build

warmup

當它準備您的代理程式時,在 CreateAgentRuntime和 期間 UpdateAgentRuntime

準備記憶體和磁碟,讓工作階段更快開始。如需詳細資訊,請參閱建置暖機掛鉤。

建置暖機掛勾

AgentCore 執行期會在準備您的代理程式時CreateAgentRuntimeUpdateAgentRuntime呼叫建置暖機掛鉤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 秒到到達 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]失敗。如需這些行以及如何對其採取行動,請參閱針對生命週期掛鉤進行故障診斷。