View a markdown version of this page

AgentCore ランタイムのライフサイクルフックを設定する - Amazon Bedrock AgentCore

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AgentCore ランタイムのライフサイクルフックを設定する

ライフサイクルフックは、エージェントのランタイムのライフサイクルの特定の時点で AgentCore ランタイムが呼び出すコンテナ内のエンドポイントです。フックを使用して、セッションの開始前にエージェントを準備するなど、これらのポイントで独自のコードを実行します。CreateAgentRuntime および UpdateAgentRuntime の hooksConfigurationフィールドを使用してフックを設定し、それらが属するライフサイクルフェーズ別にグループ化します。

ライフサイクルフックは、microVMs でプラットフォームバージョン V2 を使用するエージェントランタイムで使用できます。詳細については、「プラットフォームのバージョン」を参照してください。

要件

  • エージェントランタイムはプラットフォームバージョン V2 を使用する必要があります。V1 では、リクエストは で失敗しますValidationException。

  • エージェントランタイムは microVMsコンピューティングタイプを使用する必要があります。ライフサイクルフックは インスタンスではサポートされていません。 hooksConfigurationと組み合わせた場合capacityProviderConfiguration、リクエストは で失敗しますValidationException。

フック呼び出しの仕組み

エージェントランタイムがライフサイクルのフックのポイントに達すると、AgentCore Runtime はフックのアクションを 1 回実行します。コンテナに 1 つのリクエストを行い、実装がフックの時間制限内に成功を報告するのを待ちます。AgentCore Runtime はフック呼び出しを再試行しません。

呼び出しが失敗するか、時間制限内に成功しない場合、フックをトリガーしたオペレーションは失敗します。たとえば、ビルドフックが失敗すると、ランタイムは失敗を記述failureReasonする CREATE_FAILEDまたは UPDATE_FAILED に移動します。詳細については、「ライフサイクルフックのトラブルシューティング」を参照してください。

実装が成功を報告する方法は、フックのアクションによって異なります。

フックアクション

各フックには、AgentCore Runtime がコンテナを呼び出す方法を定義する 1 つのアクションがあります。

HTTP アクション

HTTP アクションは、コンテナ内のサーバーでport、選択した pathおよび に HTTP リクエストを送信します。実装は、作業が完了した後に2xxステータスコードを返すことで成功を報告します。その他のステータスコード、または接続の失敗は、呼び出しに失敗します。各リクエストには、呼び出しを識別するヘッダーを含めることができます。各フックには、送信するヘッダーと値が一覧表示されます。

フックは、POSTリクエストを送信する httpPostアクションをサポートします。次のaction.httpPostフィールドがあるフックの フィールドで設定します。

フィールド Type 必須 説明

path

文字列

はい

AgentCore Runtime がリクエストを送信するパス。パスは、次のルールを満たす必要があります。

  • これには 1~32 文字が含まれ、パターン と一致します^/[A-Za-z0-9._~/-]*$。

  • これは正規形式です。末尾は ではなく / (パス/自体を除く)、//、、.または ..セグメントは含まれません。

  • AgentCore Runtime が同じポートで既に使用しているルートと競合することはありません。詳細については、「プラットフォームルート」を参照してください。

port

整数

いいえ

AgentCore Runtime がリクエストを送信するポート。サポートされている範囲は 120008000~ です。リザーブドプラットフォームポート以外のポートを選択します。ポートを指定しない場合、デフォルトはエージェントのサービングポートです。設定protocolConfiguration.portした場合、プロトコルのデフォルトポート (8080HTTP および AG-UI の場合は 、MCP 8000の場合は 、A2A 9000の場合は )。

フックのルートは、HTTP メソッド、パス、ポートです。AgentCore Runtime がエージェントのサービングポートで既に使用しているルートと一致させることはできません。次の表に、これらのプラットフォームルートを示します。

フックが使用できないプラットフォームルート
プロトコル フックが使用できないルート

すべてのプロトコル

  • POST 呼び出しパスへの : 設定protocolConfiguration.pathした場合、プロトコルのデフォルト (/invocationsHTTP および AG-UI の場合は 、/mcpMCP の場合は 、A2A /の場合は )

  • GET /ws

  • GET /ping

MCP

POST /mcp呼び出しパスを変更した場合でも、

A2A

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

競合は、 メソッドとパスを比較します。例えば、 AgentCore ランタイムは を使用するため、 POST /pingは有効なフックルートですGET /ping。サービングポートと呼び出しパスについては、「エージェントのサービングポートと呼び出しパスを設定する」を参照してください。

注記

エージェントランタイムがセッションエンドポイントを使用する場合、AgentCore ランタイムはセッションエンドポイントリクエストからフックを保護します。

  • フックのルートをターゲットとするリクエストは、コンテナに到達する403AccessDenied前に HTTP で拒否されます。パスマッチングは大文字と小文字を無視し、パスの一般的な同等のスペルを同じパスとして扱います。これには、繰り返しまたは末尾のスラッシュ、...セグメント、パーセントエンコードされた文字、;パラメータが含まれます。

  • フックヘッダーは予約されています。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 Runtime は、ランタイムが に達するUpdateAgentRuntime前に、 CreateAgentRuntimeおよび 中にエージェントの準備中にビルドウォームアップフックを呼び出しますREADY。この順序で 2 つの呼び出しを行い、どの呼び出しを呼び出すかを実装に伝えます。

ウォームアップタイプ Order 対応方法

memory

まず、エージェントが/pingヘルスチェックに合格した後

インポート、モデル、キャッシュなど、すべてのセッションに必要なものをメモリにロードします。各新しいインスタンスは、ここでロードした内容から始まります。

disk

秒

セッションの開始時にエージェントが読み取るファイルを読み取ります。AgentCore Runtime はこれらの読み取りを使用して、これらのファイルを新しいセッションでより迅速に利用できるようにします。

HTTP アクションでは、AgentCore Runtime は X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Typeヘッダーのウォームアップタイプを memoryまたは の値で送信しますdisk。

2 つの呼び出しは、合計 120 秒の時間制限を共有します。memory 呼び出しが最初に実行されるため、disk呼び出しはmemory呼び出しが離れる時間を取得します。たとえば、memory呼び出しに 50 秒かかる場合、disk呼び出しは 70 秒です。この制限は変更できません。

ウォームアップフックは、 に達するCreateAgentRuntimeUpdateAgentRuntimeまでに最大 120 秒かかることがありますREADY。各ウォームアップログ行は、1 つの作成または更新に対して複数回表示できます。

ウォームアップハンドラーを記述する

ウォームアップハンドラーは、 /pingと呼び出しハンドラーとともにエージェントのサーバーで実行されます。

  • /ping応答性を維持します。ウォームアップの実行/ping中、サーバーは応答し続ける必要があります。ウォームアップハンドラー内でサーバーの唯一のスレッドをブロックしないでください。別のスレッドまたはプロセスで作業を実行するか、リクエストを同時に処理するサーバーを使用します。

  • 作業が完了した後に2xxのみ を返します。応答時にロードした内容は、セッションの開始点です。

次の FastAPI アプリケーションは/ping、ポート の POST /warmupで 、/invocations、およびウォームアップフックを提供します8080。ワーカースレッドでウォームアップ作業を実行するため、サーバーは に応答し続けます/ping。load_shared_state と をエージェント独自の作業とファイルSTARTUP_FILESに置き換えます。

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 Runtime は、名前が で始まるログストリームで/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT、各ビルドフック呼び出しの進行状況と結果をランタイムのロググループ に書き込みますbuild-logs-。各行は で始まり[LIFECYCLE-HOOK <epoch-milliseconds>]、進行状況[LIFECYCLE]の場合は 、失敗[ERROR]の場合は が続きます。行とその対処方法については、「ライフサイクルフックのトラブルシューティング」を参照してください。