View a markdown version of this page

テレメトリのセットアップと配信 - Amazon Bedrock AgentCore
オブザーバビリティを設定するテレメトリ配信モードサービスがスパンから読み取る内容リファレンスサンプルエージェント

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

テレメトリのセットアップと配信

エージェントは、Amazon Bedrock AgentCore Evaluations が各セッションを再構築するために使用するスパンを出力します。AgentCore がセッション、トレース、スパンを表す方法については、AgentCore のエージェントリソースのオブザーバビリティを理解する」を参照してください。

セッションをスコアリングするには、サービスに、モデルプロンプト、モデルの完了、ツールの入力と出力などの会話コンテンツが必要です。コンテンツの場所は、エージェントがテレメトリをどのように配信するかによって異なります。このページでは、これについて説明します。

トピック

オブザーバビリティを設定する

エージェントを計測することは、評価サービスが読み取ることができるテレメトリの生成の一部です。エージェントは、テレメトリを Amazon CloudWatch にエクスポートするために、オブザーバビリティも有効にする必要があります。以下のステップを実行します。

  1. Amazon CloudWatch トランザクション検索を有効にします。評価では、両方の配信モードで評価する必要があります。AgentCore オブザーバビリティの有効化」を参照してください。

  2. エージェントをホストする場所に基づいて、エージェントのオブザーバビリティを有効にします。

  3. エージェントが使用している配信モードをチェックして、テレメトリの場所を確認します。2026 年 7 月 20 日以降に作成したエージェントはデフォルトで統合テレメトリを使用し、その日付より前に作成したエージェントは分割テレメトリを使用します。統合テレメトリには ADOT バージョン 0.18.0 以降 (aws-opentelemetry-distro>=0.18.0) が必要です。以前のバージョンでは、スパンを共有aws/spansロググループに送信します。

    AgentCore ランタイムのエージェントの場合、 UNIFIED_TRACES_DESTINATION_ENABLED環境変数を使用してモードを切り替えます。統合テレメトリtrueの場合は に設定し、分割テレメトリfalseの場合は に設定します。環境変数、IAM アクセス許可、および各ホスティングオプションの完全な手順については、「Amazon Bedrock AgentCore ランタイムでホストされているエージェントのスパン送信先」を参照してください。

配信モードを変更しても、AgentCore が既に配信したテレメトリは移動しません。古いスパンは書き込まれたロググループに留まるため、サービスは変更前に記録したセッションを引き続き評価します。

テレメトリ配信モード

AgentCore は、次の 2 つのモードのいずれかでエージェントのテレメトリを配信します。

  • 統合テレメトリ (推奨) は、すべてをまとめます。モデルペイロードとツールのリクエストとレスポンスを処理する属性はスパンにとどまり、エージェントのテレメトリはすべて 1 つのロググループに送られます。

  • 分割テレメトリは 2 つを分離します。 AWS Distro for OpenTelemetry (ADOT) は、これらの属性をスパンから別々のレコードに移動し、スパンとは異なるロググループに移動します。

AgentCore Evaluations は両方のモードを読み取ります。評価サービスでそれらから選択することはなく、同じ評価者から同じ結果が得られます。AgentCore ランタイムが利用可能なすべての AWS 商用リージョンで利用できる統合テレメトリをお勧めします。

統合テレメトリ (推奨)

統合テレメトリでは、エージェントのテレメトリはすべて 1 つのロググループに送られます。スパンは、エージェント自身のspansログとコンソール出力の横にある、そのロググループのログストリームに移動します。スパンは、モデルペイロードとツールのリクエストとレスポンスを処理する属性を保持するため、サービスはスパン自体から必要なものをすべて読み取ります。

統合テレメトリ: ADOT は、コンテンツを含む各スパンを 1 つのロググループに送信します。

スパンを保持するロググループは、エージェントのホスト先によって異なります。

  • Amazon Bedrock AgentCore ランタイムの場合: エージェントのロググループ /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>。AgentCore はこれをセットアップします。

  • AgentCore ランタイムの外部でホスト: OTEL_EXPORTER_OTLP_TRACES_HEADERS環境変数で名前を付けたロググループ。

スパンとログを 1 か所に保持すると、評価にとどまりません。トレースとログを一緒に確認したり、 AWS Identity and Access Management (IAM) ポリシーを記述して、単一のエージェントにカスタマーマネージドキー暗号化を設定したり、1 つのロググループにサブスクライブしてエージェントが生成するすべてをエクスポートしたりできます。

テレメトリを分割する

分割テレメトリでは、ADOT はスパンから大きなペイロードを取ります。各スパンをエクスポートすると、モデルペイロードとツールのリクエストとレスポンスを格納する属性がプルされ、個別のイベントレコードとして送信され、スパンにはメタデータと小さな属性が残ります。イベントレコードはこのモードにのみ存在し、OpenTelemetry イベント規則に従います。

各イベントレコードは、共有 traceIdと を介してスパンにリンクしspanId、コンテンツはレコード に配置されます。たとえばbody、 body.input.messagesと ですbody.output.messages。

分割テレメトリ: ADOT はスパンを aws/spans に送信し、会話コンテンツをイベントレコードとしてエージェントロググループに送信します

その後、2 種類のレコードは別の場所に移動します。

  • スパンは共有aws/spansロググループに送られます。トランザクション検索を有効にすると、CloudWatch はこのロググループを作成します。

  • イベントレコードは別のロググループに送られます。AgentCore ランタイム、つまりエージェントのロググループでは、AgentCore が設定するotel-rt-logsログストリームにあります。AgentCore ランタイム外では、OTEL_EXPORTER_OTLP_LOGS_HEADERS環境変数で名前を付けるロググループです。

セッションを評価するために、サービスは からスパンを読み取りaws/spans、イベントレコードに一致させます。

サービスがスパンから読み取る内容

セッション内の各スパンについて、サービスは以下を実行します。

  1. フレームワークセットの属性に基づいて、どのようなスパンであるかを調べます。スパンは、呼び出しエージェントスパン (最上位のエージェント実行）、実行ツールスパン (単一のツール呼び出し）、または推論スパン (単一のモデル呼び出し) です。

  2. ユーザープロンプト、エージェントのレスポンス、ツールの入力と出力など、必要な値を読み取ります。たとえば、ユーザープロンプトはエージェント入力のユーザーロールメッセージから取得され、エージェントのレスポンスはエージェント出力のアシスタントロールメッセージから取得されます。

スパンを識別する属性は、両方の配信モードで常にスパンに保持されます。会話コンテンツのみが移動します。コンテンツがスパン内にある場所は計測ライブラリにも依存します。ほとんどのライブラリはコンテンツをスパン属性として記録し、一部のライブラリはそれをイベントとしてスパンにアタッチします。各ライブラリについて、フレームワークごとのページには識別属性が一覧表示され、コンテンツが置かれている場所が示され、両方のモードのスパンの例が表示されます。

リファレンス

AgentCore Evaluations は、次の OpenTelemetry 仕様に基づいています。

サンプルエージェント

次の例は、Amazon Bedrock AgentCore ランタイムの外部でホストされている Strands エージェントを計測する方法を示しています。各例では、ADOT を使用してテレメトリを Amazon CloudWatch にエクスポートします。これらは、評価 API ではなくオブザーバビリティの設定に焦点を当てています。この例では Strands を使用していますが、同じホスティングおよびテレメトリエクスポートパターンが LangGraph などのサポートされている他のフレームワークに適用されます。