View a markdown version of this page

AgentCore のエージェントリソースのオブザーバビリティを理解する - Amazon Bedrock AgentCore
セッショントレーススパンセッション、トレース、スパン間の関係

AgentCore のエージェントリソースのオブザーバビリティを理解する

このセクションでは、エージェントのモニタリングとオブザーバビリティに関連するセッション、トレース、スパンの概念を定義します。

セッション

セッションは、ユーザーとエージェント間の完全なインタラクションコンテキストを表します。セッションは会話またはインタラクションフロー全体をカプセル化し、複数の交換にわたって状態とコンテキストを維持します。各セッションには一意の識別子があり、初期化から終了まで、エージェントとのユーザーエンゲージメントのライフサイクル全体をキャプチャします。

セッションは、エージェントに次の機能を提供します。

  • 同じ会話内の複数のインタラクションにわたるコンテキストの永続性

  • ユーザー固有の情報を維持するための状態管理

  • コンテキストを理解するための会話履歴の追跡

  • インタラクション中のリソースの割り当てと管理

  • 同じエージェントとの異なるユーザーインタラクション間の分離

オブザーバビリティの観点から見ると、セッションはユーザーエンゲージメントパターンの概要を把握できるため、メトリクス、トレース、スパンにわたってエージェントのパフォーマンスをモニタリングし、時間の経過とともにさまざまなユースケースにわたってユーザーがエージェントとやり取りする方法を理解できます。

デフォルトでは、AgentCore は AgentCore ランタイムで実行されているエージェントのセッションレベルでオブザーバビリティメトリクスのセットを提供します。ランタイムメトリクスは、生成 AI オブザーバビリティページの Amazon CloudWatch コンソールで表示できます。このページには、エージェントのデータの解釈に役立つさまざまなグラフと視覚化が用意されています。AgentCore は、メモリリソース、ゲートウェイリソース、組み込みツールのデフォルトのメトリクスセットも出力します。これらのメトリクスはすべて CloudWatch で表示できます。提供されたメトリクスに加えて、メモリリソースのログとスパンはデフォルトで提供され、エージェントコードを計測することで、エージェントのカスタムメトリクス、ログ、スパンをキャプチャできます。これは、CloudWatch の生成 AI オブザーバビリティページでも表示できます。詳細については、以下のセクションおよび Amazon Bedrock AgentCore エージェントのオブザーバビリティデータを表示するを参照してください。

トレース

トレースは、エージェントの呼び出しから始まる単一のリクエスト/レスポンスサイクルの詳細なレコードを表し、他のエージェントへの追加の呼び出しが含まれる場合があります。トレースは、すべての内部処理ステップ、外部サービス呼び出し、決定ポイント、リソース使用率など、リクエストの完全な実行パスをキャプチャします。各トレースは特定のセッションに関連付けられ、特定のインタラクションに対するエージェントの動作をきめ細かく可視化します。

トレースには、エージェントの次のコンポーネントが含まれます。

  • タイムスタンプ、入力パラメータ、コンテキストなどのリクエストの詳細

  • 実行されたオペレーションのシーケンスを示す処理ステップ

  • 入出力パラメータと実行時間を含むツール呼び出し

  • 処理時間などのリソース使用率メトリクス

  • 例外の詳細や復旧の試行などのエラー情報

  • レスポンス生成の詳細と最終出力

オブザーバビリティの観点からは、トレースはエージェントの内部作業に関する深い洞察を提供し、問題のトラブルシューティング、パフォーマンスの最適化、動作パターンの理解を可能にします。トレースデータを分析することで、ボトルネックを特定し、異常を検出し、エージェントがさまざまなシナリオや入力で期待どおりに機能していることを確認できます。

トレースデータを収集するには、 AWS Distro for Open Telemetry (ADOT) を使用してエージェントコードを計測する必要があります。詳細については、AgentCore がホストするエージェントのエージェントコードでオブザーバビリティを有効にする」およびAgentCore の外部でホストされるエージェントのオブザーバビリティを有効にする」を参照してください。

スパン

スパンは、エージェントの実行フロー内の個別の測定可能な作業単位を表します。スパンは、リクエスト処理中に発生するきめ細かなオペレーションをキャプチャし、トレース全体を構成する内部コンポーネントとステップを詳細に可視化します。各スパンには開始時刻と終了時刻が定義されており、エージェントのアクティビティとその期間の正確なタイムラインが作成されます。

スパンには、エージェントのオブザーバビリティに以下の必須属性が含まれます。

  • 実行される特定の関数またはプロセスを識別するオペレーション名

  • オペレーションの正確な開始時刻と終了時刻を示すタイムスタンプ

  • オペレーションがより大きなプロセス内でどのようにネストされるかを示す親子関係

  • オペレーションに関するコンテキストメタデータを提供するタグと属性

  • スパンの存続期間中に重大な出現を示すイベント

  • 成功、失敗、またはその他の完了状態を示すステータス情報

  • オペレーションに固有のリソース使用率メトリクス

スパンはトレース内に階層構造を形成し、親スパンには、より詳細なオペレーションを表す子スパンが含まれます。たとえば、高レベルの「ユーザークエリの処理」スパンには、「入力の解析」、「コンテキストの取得」、「レスポンスの生成」、「フォーマット出力」の子スパンが含まれる場合があります。この階層組織は、エージェント内のオペレーションの完全なフローを明らかにする詳細な実行ツリーを作成します。

デフォルトでは、AgentCore はメモリリソースのみのスパンデータのセットを出力します。このデータは、CloudWatch Logs および CloudWatch Application シグナルで表示できます。エージェントまたはゲートウェイリソースのスパンデータを記録するには、エージェントを計測する必要があります。詳細については、AgentCore がホストするエージェントのエージェントコードでオブザーバビリティを有効にする」およびAgentCore の外部でホストされるエージェントのオブザーバビリティを有効にする」を参照してください。

セッション、トレース、スパン間の関係

セッション、トレース、スパンは、エージェントのオブザーバビリティフレームワークで 3 階層の階層関係を形成します。セッションには複数のトレースが含まれ、各トレースはセッションのより広範なコンテキスト内の個別のインタラクションを表します。各トレースには、そのインタラクション内のきめ細かなオペレーションとステップをキャプチャする複数のスパンが含まれます。この階層構造により、高レベルのセッションパターンから中間レベルのインタラクションフロー、特定のオペレーションの詳細な実行パスまで、さまざまな詳細レベルでエージェントの動作を分析できます。

これら 3 つのオブザーバビリティコンポーネントの関係は、次のように視覚化できます。

  • セッション (最高レベル) - 完全なユーザー会話またはインタラクションコンテキストを表します

  • トレース (中間レベル) - セッション内の個々のリクエスト/レスポンスサイクルを表します

  • スパン (最低レベル) - トレース内の特定のオペレーションまたはステップを表します。

この多層関係により、いくつかの重要なオブザーバビリティ機能が可能になります。

  • より広範な会話フロー内の個々のインタラクションのコンテキスト分析

  • ユーザーのインタラクションジャーニーにおける関連リクエストの相関関係

  • セッションレベルの異常からトレースレベルのパターン、スパンレベルの根本原因への段階的なトラブルシューティング

  • さまざまな時間的および機能的側面にわたる包括的なパフォーマンスプロファイリング

  • 会話中のエージェントの行動パターンと進化に関する全体的な理解

  • スパン分析によるオペレーションレベルでのパフォーマンスのボトルネックの正確な特定

トレースは完全なリクエスト/レスポンスサイクルを可視化しますが、スパンはそれらのサイクルの内部動作に関するより深いインサイトを提供します。スパンは、どのオペレーションが最も時間を消費するか、エラーが発生する場所、および 1 つのトレース内で異なるコンポーネントがどのように相互作用するかを正確に明らかにします。この詳細度は、複雑な問題のトラブルシューティングや、高度なエージェント実装でのパフォーマンスの最適化に特に役立ちます。

オブザーバビリティ戦略でセッション、トレース、スパンデータを活用することで、エージェントの行動、パフォーマンス、有効性に関する包括的なインサイトを複数のレベルで詳細に得ることができます。このオブザーバビリティへの多層アプローチは、高レベルの会話パターンから個々のオペレーションパフォーマンスまで、エージェントの実装の継続的な改善、堅牢なトラブルシューティング、情報に基づいた最適化をサポートします。