View a markdown version of this page

Amazon Bedrock AgentCore Runtime V2 のエージェントを最適化する - Amazon Bedrock AgentCore

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

Amazon Bedrock AgentCore Runtime V2 のエージェントを最適化する

Amazon Bedrock AgentCore Runtime V2 は、スナップショットを復元してエージェントを開始します。これにより、エージェントコードの構造が変更されます。エージェントが起動時に行う作業はスナップショットにキャプチャされ、復元されたすべてのインスタンスによって共有されます。代わりに、リクエストハンドラーでリクエスト間で異なる値を生成するか、期限切れになる可能性のある値を生成します。このトピックでは、起動作業とリクエストごとの作業を中心にエージェントを構造化して、復元のたびに正しい状態を維持する方法について説明します。プラットフォームバージョン V2 の概要については、「プラットフォームバージョン」を参照してください。

エージェントには 2 つの実行コンテキストがあります。

スタートアップ

AgentCore ランタイムがスナップショットを作成する前に、プロセスの開始時に 1 回実行されるコード。AgentCore Runtime はこのコードをスナップショットにキャプチャし、すべてのインスタンスがその結果を継承します。

リクエスト処理

/invocations ハンドラーのコード。このコードは、すべてのインスタンスのすべてのリクエストで実行されます。

1 つのルールを使用して、コードが属する場所を決定します。スナップショットの有効期間中、値が変わらない場合は、起動時に値を計算します。リクエストごとに異なる場合や期限切れになる可能性がある場合は、ハンドラーで計算します。AgentCore ランタイムは、エージェントバージョンごとに 1 つのスナップショットを取得し、エージェントを作成または更新するまで使用します。そのため、スナップショットの有効期間はそのバージョンの存続期間です。

起動時に 1 回初期化する

スナップショットを作成する前に、プロセスの開始時に高価で再利用可能な作業を行います。たとえば、デプロイバンドルから依存関係のインポート、モデルの重みのロード、静的設定の読み取りなどです。AgentCore SDK を使用して、 を呼び出す前に、この作業をモジュールスコープで実行しますapp.run()。エージェントは app.run()が実行されるまでポート 8080 をリッスンしないため、 /pingは成功せず、起動作業が完了するまでスナップショットを作成できません。スナップショットは、完全に初期化されたエージェントを構造別にキャプチャするため、 をゲートする必要はありません/ping。起動後 120 秒以内に初期化を完了します。エージェントが正常に動作しない場合、ランタイムはヘルスチェックに失敗します。/ping および /invocationsエンドポイントの詳細については、AgentCore ランタイムサービス契約の理解」を参照してください。

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

ランダムな値、識別子、トークンを生成する

各リクエストuuid.uuid4()で os.urandom()、secrets、または を呼び出す

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 がスナップショットからインスタンスを復元すると、そのスナップショットから作成されたすべてのインスタンスは、スナップショット時にキャプチャされたメモリの同じコピーから始まります。これには、暗号化ライブラリ内の乱数ジェネレーターの内部状態、および初期化中にエージェントが作成したキー、トークン、または識別子が含まれます。復元後にその状態が更新されない限り、インスタンスは同じ「ランダム」値を生成できます。

現在の制限

AgentCore ランタイムでは、暗号化ライブラリのスナップショットセーフビルドは現在、復元後に再シードされません。これは、直接コードデプロイとコンテナデプロイの両方に適用されます。

回避策

  • エージェントの起動時ではなく、リクエストの処理中にシークレット、キー、トークン、セッション識別子を生成します。これにより、AgentCore Runtime がそのスナップショットから復元された各インスタンスでスナップショットを取得する前に作成された値を使用する必要がなくなります。

  • リクエストを処理している場合でも、Python の secretsまたは 、Go の os.urandom、 の読み取りなどcrypto/rand、オペレーティングシステムから直接ランダムな値を取得します/dev/urandom。OpenSSL などの暗号化ライブラリのランダムな値は、インスタンス間で繰り返す可能性があるため、使用しないでください。

ネットワーク

起動時にクライアントを構築し、透過的な再接続を期待する

起動時に開いたソケットは復元後も存続しませんが、サービスモデルの解析、エンドポイント解決、認証情報解決、接続プールなど、クライアントライブラリがキャッシュするセットアップは、復元後も存続します。起動時にクライアントを構築して演習し、復元後の最初の呼び出しが接続を透過的に再確立することを期待します。

一意のインスタンス識別子としてホスト名または PID を使用しないでください。

復元されたインスタンスはすべて同じスナップショットから開始され、同じホスト名とプロセス ID を報告します。各リクエストで一意の識別子を生成します。

固定ソースポートへのバインドを避ける

復元後、スナップショット時に保持されている接続が再確立され、固定ソースポートがインスタンス内のその置き換えと衝突する可能性があります。復元されたインスタンスは、独自のネットワーク名前空間を持つ個別のmicroVMs であるため、競合はインスタンス内に存在し、インスタンス間では発生しません。

クロスアカウントメトリクスとクォータ

クロスアカウント呼び出しでは、あるアカウントのプリンシパルがリソースベースのポリシーを通じて別のアカウントが所有するエージェントランタイムを呼び出す場合、CloudWatch メトリクスと呼び出しのレート制限クォータの使用状況はリソース所有者のアカウントに帰属します。リソース所有者は、エージェントのランタイムを所有するアカウントです。

Service Quotas コンソールで、クォータにカウントされるメトリクスを表示することもできます。