エージェント トレースの概要

重要

この記事でマークされている項目 (プレビュー) は、現在パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードにはお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「Microsoft Azure プレビューの使用条件を参照してください。

メモ

トレースは、プロンプト エージェントとホステッド エージェントで一般提供されています。 ワークフローエージェントと外部エージェントはプレビュー段階です。

Microsoft Foundry は、AI エージェントを監視およびトレースするための監視プラットフォームを提供します。 入力、出力、ツールの使用状況、再試行、待機時間、コストなど、エージェントの実行中に重要な詳細をキャプチャします。 エージェントの実行の背後にある理由を理解することは、トラブルシューティングとデバッグに重要です。 ただし、複雑なエージェントを理解すると、いくつかの理由で課題が発生します。

  • 応答の生成には多くの手順が必要な場合があり、それらのすべてを追跡するのが難しい場合があります。
  • 一連の手順は、ユーザー入力によって異なる場合があります。
  • 各段階の入力と出力は長く、より詳細な検査に値する可能性があります。
  • エージェントのランタイムの各ステップには、入れ子が含まれる場合もあります。 たとえば、エージェントによってツールが呼び出され、別のプロセスが使用され、別のツールが呼び出される場合があります。 最上位レベルのエージェントの実行から奇妙な出力や正しくない出力が表示された場合、問題が発生した実行の正確な場所を特定することが困難な場合があります。

トレースは、特定のエージェントの実行に関係する各プリミティブの入力と出力を、呼び出された順序で表示して、AI エージェントの動作を理解してデバッグできるようにすることで、これらの課題に対処します。

前提 条件

エンドツーエンドのトレースを使用するには、次のものが必要です。

  • トレースが有効になっている Foundry プロジェクト。 これを設定するには、Microsoft Foundry でトレースを設定する方法を参照してください。
  • プロジェクトに接続されている Application Insights リソースへのアクセス。 背景については、「Azure Monitor Application Insights」を参照してください。
  • Foundry でトレース、分析情報、視覚化を表示するための Log Analytics 閲覧者ロール。

メモ

トレースでは、テレメトリ データが Azure Monitor Application Insights に格納されます。この場合、データ量と保持の設定に基づいてコストが発生する可能性があります。 価格の詳細については、 Application Insights の価格に関するページを参照してください。

Foundry の OpenTelemetry

OpenTelemetry (OTel) は、テレメトリ データを収集してルーティングするための標準化されたプロトコルを提供します。 Foundry では OpenTelemetry セマンティック規則が使用されるため、サポートされているツールと統合全体でトレースが一貫しています。

主要な概念をトレースする

この記事では、次の主要な概念が適用されます。

主な概念 説明
トレース トレースは、イベントと状態の変更 (関数呼び出し、値、システム イベント) を記録することによって、アプリケーションを通じて要求またはワークフローの過程をキャプチャします。 「OpenTelemetry のトレース」を参照してください。
範囲 スパンはトレースの構成要素であり、トレース内の単一の操作を表します。 各スパンは、開始時刻と終了時刻、属性をキャプチャし、階層リレーションシップを示すために入れ子にできるため、完全な呼び出し履歴と操作のシーケンスを確認できます。
属性 属性は、トレースとスパンにアタッチされたキーと値のペアであり、関数パラメーター、戻り値、カスタム注釈などのコンテキスト メタデータを提供します。 これによりトレース データが強化され、分析に役立つ情報が得られます。
セマンティック規則 OpenTelemetry では、トレース データ属性の名前と形式を標準化するためのセマンティック規則が定義されているため、ツールやプラットフォーム間での解釈と分析が容易になります。 詳細については、 OpenTelemetry GenAI セマンティック規則を参照してください。
トレース エクスポーター トレース エクスポーターは、ストレージと分析のためにバックエンド システムにトレース データを送信します。 Foundry では、トレースは Azure Monitor Application Insights に格納されます。 トレースを有効にして表示する方法については、Microsoft Foundry でのトレースの設定方法を参照してください。

Foundry でのトレースのしくみ

トレースは、"この応答はどこから来たのか" や "エラーや待機時間の急増が発生したステップ" などの質問に答えるのに役立ちます。

大まかに言えば、トレースは次の内容をキャプチャします。

  • ユーザー入力とエージェント出力。
  • ツールの呼び出しと結果を含むツールの使用方法。
  • トークンの使用。
  • 期間や待機時間などの時間シグナル。

プロジェクトのトレースを有効にすると、Foundry ポータルと Azure Monitor Application Insights でトレースを検査できます。 詳細な設定および表示オプションについては、Microsoft Foundry でトレースを設定する方法をご覧ください。

マルチエージェントの可観測性を使用して OpenTelemetry を拡張する

Microsoft、Cisco Outshift と共同で、マルチエージェント システムのセマンティック規則を提供します。 これらの規則は、 OpenTelemetry GenAI エージェントとフレームワーク スパンとW3C トレース コンテキストに基づいて構築されます。 エージェントの呼び出し、ワークフロー オーケストレーション、計画、モデル呼び出し、ツールの実行など、マルチエージェント ワークフローのテレメトリを標準化します。

重要

OpenTelemetry GenAI セマンティック規則には開発状態があり、今後のリリースで変更される可能性があります。

これらの拡張機能は、次の機能に統合されています。

  • 鋳造
  • Microsoft Agent Framework
  • LangChain
  • LangGraph
  • OpenAI エージェント SDK

詳細については、 トレース統合を参照してください。

次の表では、マルチエージェントの可観測性に関する一般的な OpenTelemetry GenAI 規則について説明します。 スパンは操作を記録し、子スパンはネストされた処理を示し、属性はメタデータを提供します。 ここに示している親スパンは、よくある例です。実際のネスト構造は、計装済みのエージェントまたはフレームワークによって異なります。

タイプ コンテキスト/親スパン 名前/属性/イベント 目的
スパン — invoke_agent リモート サービスを介して、または同じプロセス内でエージェントを呼び出します。
子スパン invoke_agent invoke_agent 親子スパンリレーションシップを介して別のエージェントの呼び出しをトレースします。
子スパン invoke_agent plan エージェント計画またはタスク分解フェーズを記録します。
スパン — invoke_workflow エージェントまたはその他の生成 AI 操作を含む調整されたワークフローを呼び出します。
子スパン invoke_agent または invoke_workflow execute_tool ツールの実行を記録します。
子スパン invoke_agent または invoke_workflow create_memory、search_memory、update_memory、upsert_memory、または delete_memory メモリ操作を記録します。
属性 invoke_agent gen_ai.tool.definitions エージェントまたはモデルで使用できるツールの定義を記録します。
属性 execute_tool gen_ai.tool.call.arguments ツール呼び出しに渡された引数を記録します。
属性 execute_tool gen_ai.tool.call.result 正常なツール呼び出しによって返された結果を記録します。

ベスト プラクティス

  • 一貫性のあるスパン属性を使用する: すべてのエージェントとツールに同じ属性名と形式を適用して、クエリと分析を簡略化します。
  • 評価実行 ID を関連付ける: トレース データを評価実行とリンクして、統合ビューで品質とパフォーマンスの両方を分析します。
  • 機密コンテンツの編集: テレメトリに到達する前に、プロンプト、ツール引数、スパン属性から個人データ、シークレット、資格情報を削除またはマスクします。

セキュリティとプライバシー

トレースでは、ユーザー入力、モデル出力、ツールの引数や結果などの機密情報をキャプチャできます。 リスクを軽減するには、次のプラクティスを使用します。

  • シークレット、資格情報、またはトークンは、プロンプト、ツール引数、またはスパン属性に格納しないでください。
  • テレメトリに表示される前に、個人データやその他の機密コンテンツを編集または最小化します。
  • トレース データを運用テレメトリとして扱い、ログとメトリックに使用するのと同じアクセス制御と保持ポリシーを適用します。

機密性の高いコンテンツを専用テーブルにルーティングしてアクセスを制限する手順については、「 機密性の高いコンテンツへのアクセスを制限する」を参照してください。

トラブルシューティング

Foundry ポータルまたは Application Insights にトレースが表示されない場合:

  • Foundry プロジェクトが Application Insights リソースに接続されていることを確認します。
  • テレメトリのクエリに必要なアクセス許可がアカウントにあることを確認します。
  • エージェント コードに必要なインストルメンテーションが含まれていることを確認します。 フレームワーク固有のセットアップについては、「 トレース統合」を参照してください。

ヒント

トレースは、Foundry がサポートされているすべてのリージョンで使用できます。 トレース データの保持とサンプリングは、Application Insights の構成に従います。 詳細については、「Azure Monitor ログでのデータの保持とアーカイブを参照してください。

関連コンテンツ

  • Last updated on