AI エージェントを開発している場合は、OpenTelemetry を使用してアプリケーションを計測し、エージェントがどのように推論し、ツールを呼び出し、プロンプトに応答するかをモニタリングできます。このガイドでは、LangGraph や Agent Development Kit（ADK）などのフレームワークを使用してエージェント テレメトリーをキャプチャする方法と、Cloud Trace でマルチモーダル プロンプトとレスポンスを分析する方法について説明します。
エージェントを計測して動作を把握する
生成 AI アプリケーションを開発または管理する場合、テレメトリー データは、自律型エージェントの推論ステップ、ツール呼び出し、外部インタラクションをキャプチャします。このデータは、次の理由で役立ちます。
- 非決定論的な動作を理解する: エージェントの推論プロセスは決定論的ではないため、エージェントが行った決定と選択したツールを検査する唯一の信頼できる方法は、テレメトリーです。
- エラーのトラブルシューティングと診断: トレースは、Agentic Workflows 全体で失敗した API リクエスト、無限実行ループ、レイテンシのボトルネックを特定するのに役立ちます。
- ガバナンスをサポートし、トラフィックを検証する: テレメトリーを使用すると、アプリケーション トポロジなどの通信フローを可視化して、エージェントが承認済みのエージェント、MCP サーバー、外部エンドポイントとのみ通信していることを確認できます。
- 出力の品質と費用を評価する: プロンプト、レスポンス、トークンの使用状況を収集することで、モデルの精度を評価し、ハルシネーションを検出して、リソース消費を最適化できます。
生成 AI アプリケーションを計測する方法
アプリケーションを計測するには、テレメトリーを生成して、保存、クエリ、分析が可能な宛先に送信します。たとえば、計測によってテレメトリーが Google Cloud プロジェクトに送信される場合は、Google Cloud Observability を使用してそのデータを表示および分析できます。
Cloud Trace は、生成 AI アプリケーションによって書き込まれたスパンがスパンとイベントのセマンティック規則に準拠している場合、それらのスパンからイベントを自動的に抽出します。これらの規則については、次のドキュメントをご覧ください。
Cloud Trace では、マルチモーダル プロンプトとレスポンスを表示することもできます。このシナリオでは、プロンプトとレスポンスはトレースデータに関連付けられておらず、代わりに Cloud Storage バケットに保存されます。この構成の詳細については、マルチモーダル プロンプトとレスポンスを収集して表示するをご覧ください。
ベスト プラクティス
アプリケーションの計測には、OpenTelemetry を使用することをおすすめします。OpenTelemetry は、アプリケーションの計測用の統合フレームワークを提供するオープンソース プロジェクトです。このドキュメントに記載されているインストルメンテーション サンプルでは、OpenTelemetry を使用しています。
また、プロンプトとレスポンスは、ログエントリではなく Cloud Storage バケットに保存することをおすすめします。
Cloud Storage バケット内のコンテンツをきめ細かく制御できます。たとえば、バケットに保存されている個々の会話を削除できます。ただし、個々のログエントリを削除することはできません。
Cloud Storage バケットには、ログエントリの最大サイズ（256 KiB に制限）よりもはるかに大きいオブジェクトを保存できます。受信したデータがログエントリの最大サイズを超えると、Cloud Logging は
INVALID_ARGUMENTエラーを返し、データを破棄します。コマンドがエラーなしで完了しても、個々のフィールドがサイズの上限を超えている場合、Cloud Logging はそのデータを切り捨てます。
OpenTelemetry の詳細については、OpenTelemetry とはをご覧ください。
インストルメンテーションのサンプル
エージェントの計測を開始するには、次のサンプル アプリケーションとガイドをご覧ください。
マルチモーダル プロンプトとレスポンスを収集して表示するでは、ADK で構築された LangGraph ReAct エージェントまたは生成 AI エージェントを構成して、マルチモーダル プロンプトとレスポンスを収集する方法について説明します。また、次の操作を行う方法についても説明します。
- プロンプトとレスポンスを Cloud Storage バケットに保存する。
- [Trace エクスプローラ] ページでプロンプトとレスポンスを表示する。
- BigQuery でプロンプトとレスポンスを分析する。
- Vertex AI SDK for Python を使用してプロンプトとレスポンスを評価する。
OpenTelemetry を使用して LangGraph ReAct エージェントを計測するでは、OpenTelemetry を使用して、LangChain または LangGraph フレームワークを使用する生成 AI アプリケーションを計測する方法について説明します。また、ダウンロードして実行できるサンプル アプリケーションへのリンクも含まれています。サンプル アプリケーションは、テキスト プロンプトとレスポンスを収集します。
OpenTelemetry を使用して ADK アプリケーションを計測するでは、エージェントの主要なアクションからテレメトリーを収集する組み込みの計測を有効にする方法について説明します。テレメトリーには、テキスト プロンプトとエージェントのレスポンスが含まれます。また、ダウンロードして実行できるサンプル アプリケーションへのリンクも含まれています。サンプル アプリケーションは、テキスト プロンプトとレスポンスを収集します。
Trace を使用して MCP 呼び出しを調査するでは、トレース コンテキストをリモートの Google Cloud MCP サーバーに渡すようにアプリケーションを構成する方法について説明します。これにより、これらのサーバーはスパンをトレースにアタッチできます。