

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

# 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`フィールドを使用してフックを設定し、それらが属するライフサイクルフェーズ別にグループ化します。

ライフサイクルフックは、microVMs でプラットフォームバージョン V2 を使用するエージェントランタイムで使用できます。詳細については、[「プラットフォームのバージョン](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 Runtime はフックのアクションを 1 回実行します。コンテナに 1 つのリクエストを行い、実装がフックの時間制限内に成功を報告するのを待ちます。AgentCore Runtime はフック呼び出しを再試行しません。

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

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

### フックアクション
<a name="runtime-lifecycle-hooks-actions"></a>

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

#### HTTP アクション
<a name="runtime-lifecycle-hooks-http-actions"></a>

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

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


| フィールド | Type | 必須 | 説明 | 
| --- | --- | --- | --- | 
|  `path`  | 文字列 | はい | AgentCore Runtime がリクエストを送信するパス。パスは、次のルールを満たす必要があります。+  これには 1～32 文字が含まれ、パターン と一致します`^/[A-Za-z0-9._~/-]*$`。 <br />+  これは正規形式です。末尾は ではなく `/` (パス`/`自体を除く）、`//`、、`.`または `..`セグメントは含まれません。 <br />+  AgentCore Runtime が同じポートで既に使用しているルートと競合することはありません。詳細については、[「プラットフォームルート](#runtime-lifecycle-hooks-routes)」を参照してください。  | 
|  `port`  | 整数 | いいえ | AgentCore Runtime がリクエストを送信するポート。サポートされている範囲は `12000``8000`～ です。[リザーブドプラットフォームポート以外のポート](runtime-service-contract.md#runtime-reserved-ports)を選択します。ポートを指定しない場合、デフォルトはエージェントのサービングポートです。設定`protocolConfiguration.port`した場合、プロトコルのデフォルトポート (`8080`HTTP および AG-UI の場合は 、MCP `8000`の場合は 、A2A `9000`の場合は )。 | 

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


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

| プロトコル | フックが使用できないルート | 
| --- | --- | 
| すべてのプロトコル |  +   `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`  | 

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

**注記**  
エージェントランタイムが[セッションエンドポイント](runtime-session-endpoints.md)を使用する場合、AgentCore ランタイムはセッションエンドポイントリクエストからフックを保護します。  
フックのルートをターゲットとするリクエストは、コンテナに到達する`403``AccessDenied`前に HTTP で拒否されます。パスマッチングは大文字と小文字を無視し、パスの一般的な同等のスペルを同じパスとして扱います。これには、繰り返しまたは末尾のスラッシュ、`.``..`セグメント、パーセントエンコードされた文字、`;`パラメータが含まれます。
フックヘッダーは予約されています。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 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 秒です。この制限は変更できません。

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

#### ウォームアップハンドラーを記述する
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

ウォームアップハンドラーは、 `/ping`と呼び出しハンドラーとともにエージェントのサーバーで実行されます。
+  **`/ping`応答性を維持します。**ウォームアップの実行`/ping`中、サーバーは応答し続ける必要があります。ウォームアップハンドラー内でサーバーの唯一のスレッドをブロックしないでください。別のスレッドまたはプロセスで作業を実行するか、リクエストを同時に処理するサーバーを使用します。
+  **作業が完了した後に`2xx`のみ を返します。**応答時にロードした内容は、セッションの開始点です。

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

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