翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Bedrock AgentCore Runtime V2 のエージェントを最適化する
Amazon Bedrock AgentCore Runtime V2 は、スナップショットを復元してエージェントを開始します。これにより、エージェントコードの構造が変更されます。エージェントが起動時に行う作業はスナップショットにキャプチャされ、復元されたすべてのインスタンスによって共有されます。代わりに、リクエストハンドラーでリクエスト間で異なる値、または期限切れになる可能性のある値を生成します。このトピックでは、起動作業とリクエストごとの作業を中心にエージェントを構造化して、復元のたびに正しい状態を維持する方法について説明します。プラットフォームバージョン V2 の概要については、[「プラットフォームバージョン](runtime-how-it-works.md#runtime-platform-versions)」を参照してください。
エージェントには 2 つの実行コンテキストがあります。
スタートアップ
AgentCore ランタイムがスナップショットを作成する前に、プロセスの開始時に 1 回実行されるコード。AgentCore Runtime はこのコードをスナップショットにキャプチャし、すべてのインスタンスがその結果を継承します。
リクエスト処理
`/invocations` ハンドラーのコード。このコードは、すべてのインスタンスのすべてのリクエストで実行されます。
1 つのルールを使用して、コードが属する場所を決定します。スナップショットの存続期間中、値が変わらない場合は、起動時に値を計算します。リクエストごとに異なる場合や期限切れになる可能性がある場合は、ハンドラーで計算します。AgentCore Runtime は、エージェントバージョンごとに 1 つのスナップショットを取得し、エージェントを作成または更新するまで使用します。そのため、スナップショットの有効期間はそのバージョンの存続期間です。
## 起動時に 1 回初期化する
スナップショットを作成する前に、プロセスの開始時に高価で再利用可能な作業を行います。たとえば、デプロイバンドルから依存関係のインポート、モデルの重みのロード、静的設定の読み取りなどです。AgentCore SDK を使用して、 を呼び出す前に、この作業をモジュールスコープで実行します`app.run()`。エージェントは `app.run()`が実行されるまでポート 8080 をリッスンしないため、起動作業が完了するまで`/ping`成功することもスナップショットを作成することもできません。スナップショットは完全に初期化されたエージェントを構造別にキャプチャするため、 をゲートする必要はありません`/ping`。起動後 120 秒以内に初期化を完了します。エージェントが時間内に正常にならない場合、ランタイムはヘルスチェックに失敗します。`/ping` および `/invocations`エンドポイントの詳細については、[AgentCore ランタイムサービス契約の理解](runtime-service-contract.md)」を参照してください。
```
import json, pathlib
from bedrock_agentcore.runtime import BedrockAgentCoreApp
# Runs once at import, before app.run() starts the server and before the
# snapshot. Every restored instance inherits these objects.
MODEL = load_model_weights()
SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text())
app = BedrockAgentCoreApp()
@app.entrypoint
def invoke(payload):
# Per-request work runs here on every instance.
...
app.run() # starts listening on 8080; the snapshot is taken after this
```
エージェントが AgentCore SDK の代わりに独自の HTTP サーバーを実行している場合は、初期化が完了した後に`/ping`のみ から正常なステータスを報告し、スナップショットが完全に初期化されたエージェントをキャプチャします。
起動時に、すべてのインスタンスで同じで有効期限のない読み取り専用データ。短期間の認証情報などの時間的制約のある値をハンドラーで処理します。
**注記**
再起動時に変更したものは、再デプロイせずに計算しないでください。例えば、AgentCore Gateway から取得されたツールカタログは、ロードが遅くコストがかかるため、理想的な起動値のように見えますが、起動時にキャッシュすると、スナップショット作成時にエージェントのツールインベントリがフリーズされます。
## リクエストごとの状態を最新の状態に保つ
スナップショットは 1 回キャプチャされ、復元されたすべてのインスタンスで共有されるため、起動時にエージェントが生成する値はインスタンス間で同一であり、スナップショットの作成時に固定されます。スナップショットが`/invocations`ハンドラーに持ち込めない値を処理します。次の表は、起動時ではなくハンドラーで計算する値を示しています。
| これを実行するには | ハンドラーで実行する | Reason |
| --- | --- | --- |
| ランダムな値、識別子、トークンを生成する | リクエストごとに `os.urandom()`、`secrets`、または `uuid.uuid4()`を呼び出す | `os.urandom()` は、復元後に呼び出すたびに新しいエントロピーを返します。起動時に読み取られた値はスナップショットにコピーされ、すべてのインスタンスで同じですが、エントロピーソースは読み取り時に良好でした。`random` モジュールは同様に起動時にシードされるため、復元されたインスタンスは同じシーケンスを繰り返します。 |
| 現在の時刻を読み取る | リクエストごとに計算する | 起動時にキャプチャされたタイムスタンプは、スナップショットの時刻に固定されます。 |
| 経過時間の測定 | ハンドラーで参照タイムスタンプを取得する | `time.monotonic()` は復元を横断して進行しないため、スタートアップリファレンスから測定された期間は間違えずに間違っています。 |
| 認証情報またはトークンを使用する | 有効期限が切れたら更新する | 起動時にロードされた認証情報は、インスタンスの起動前に期限切れになる可能性があります。 |
| インスタンスまたはワーカーを特定する | リクエストごとに ID を生成します。ホストから取得しないでください | 復元されたインスタンスはすべて同じホスト名 (`localhost`) と PID (`1`) を報告するため、 のいずれかを ID として使用すると、フリート全体のメトリクス、ログストリーム、ロック所有者が折りたたまれます。 |
起動時に再利用可能なクライアントを構築し、呼び出しごとにリクエストごとの値を計算します。
```
import os, time
# Build reusable clients at startup, before the snapshot. Exercise them here too
# (for example, with a warm-up call) so the setup the client caches — endpoint and
# credential resolution, connection pool — is captured in the snapshot.
client = build_client()
warm_up(client)
@app.entrypoint
def invoke(payload):
creds = get_credentials() # refreshed when expired, not read at startup
request_id = os.urandom(16).hex() # unique per request
now = time.time() # current time, not snapshot time
# Handle the request.
```
## スナップショットセーフな暗号化ライブラリを使用する
AgentCore Runtime がスナップショットからインスタンスを復元すると、起動時にランダム状態をキャッシュした暗号化ライブラリはインスタンス間でその状態を再利用できます。暗号化ライブラリは、復元後に再シードするスナップショットセーフ (スナップセーフ) ビルドを使用する必要があります。
コードの直接デプロイ
サービスマネージドベースイメージには、暗号化ライブラリのスナップショットセーフビルドがすでに含まれているため、それらに対してアクションを実行する必要はありません。
Bring-your-own 暗号化ライブラリ
コンテナエージェントなどに独自の暗号化ライブラリを持ち込む場合は、復元後に再シードするように、スナップショットセーフビルドを使用します。Amazon Linux 2023 では、 を使用します`openssl-snapsafe-libs`。
## ネットワーク
起動時にクライアントを構築し、透過的な再接続を期待する
起動時に開いたソケットは復元後も存続しませんが、サービスモデルの解析、エンドポイント解決、認証情報解決、接続プールなど、クライアントライブラリがキャッシュするセットアップは、復元後も存続します。起動時にクライアントを構築して演習し、復元後の最初の呼び出しが接続を透過的に再確立することを期待します。
一意のインスタンス識別子としてホスト名または PID を使用しないでください。
復元されたインスタンスはすべて同じスナップショットから開始され、同じホスト名とプロセス ID を報告します。各リクエストで一意の識別子を生成します。
固定ソースポートへのバインドを避ける
復元後、スナップショット時に保持されている接続が再確立され、固定ソースポートがインスタンス内のその置換と衝突する可能性があります。復元されたインスタンスは、独自のネットワーク名前空間を持つ個別のmicroVMs であるため、競合はインスタンス内に存在し、インスタンス間では発生しません。