トレース エージェント

エージェントの実行の背後にある理由を明らかにすることは、トラブルシューティングとデバッグのために重要です。 ただし、複雑なエージェントの場合、さまざまな理由でそれが難かしい場合があります。

• 応答の生成に多くのステップが関係し、それらのすべてを追跡するのが難しい場合があります。
• ステップのシーケンスが、ユーザー入力によって変わる場合があります。
• 各ステージでの入力と出力が長く、より詳細な検査が必要な場合があります。
• エージェントの実行時の各ステップに、入れ子が含まれる場合もあります。 たとえば、エージェントがツールを呼び出し、それが別のプロセスを使い、さらにそれが別のツールを呼び出しているような場合です。 最上位レベルのエージェントの実行からの出力が奇妙であったり正しくないことがわかった場合、実行で問題が発生した場所を正確に特定するのが難かしいことがあります。

トレースを使うと、特定のエージェント実行に関係する各プリミティブの入力と出力を、それが呼び出された順序で明確に確認できるようになり、これが解決されます。

Azure AI Foundry エージェント プレイグラウンドでのトレース

Azure AI Foundry ポータルの Agents プレイグラウンドを使用すると、エージェントが生成するスレッドと実行をトレースできます。 トレースを開くには、アクティブな スレッドの [スレッド情報 ] を選択します。 必要に応じて メトリック を選択して、 AI の品質 と リスクと安全性の複数のディメンションにわたってモデルのパフォーマンスの自動評価を有効にすることもできます。

[スレッド情報] を選択すると、表示される画面で、スレッド、実行、実行ステップ、および行われたツール呼び出しを表示できます。 エージェントとユーザーの間の入力と出力、および関連付けられているメタデータと選択した評価を表示できます。

OpenTelemetry と Application Insights リソースを使用してエージェントをトレースする

トレースでは、OpenTelemetry を使い、Application Insights リソースを Azure AI Foundry プロジェクトに追加して、エージェントのパフォーマンスと動作を分析できます。

Application Insights リソースを追加するには、Azure AI Foundry ポータルの左側のウィンドウから [Observability] を選択し、[トレース] を選択し、まだリソースがない場合は新しいリソースを作成します。

作成したら、Application Insights の接続文字列を取得し、エージェントを構成して、Azure Monitor によりエージェントの完全な実行パスを観察できます。 通常は、エージェントを作成する前にトレースを有効にします。

エージェントを観察する

最初に、pip install を使って、OpenTelemetry と Azure SDK トレース プラグインをインストールします。

pip install opentelemetry-sdk
pip install azure-core-tracing-opentelemetry

また、監視バックエンドに結果を送信するエクスポーターも必要です。 トレースをコンソールに出力したり、Aspire Dashboard などのローカル ビューアーを使用したりできます。 Aspire Dashboard または別の OpenTelemetry 互換バックエンドに接続するには、OpenTelemetry プロトコル (OTLP) エクスポーターをインストールします。

pip install opentelemetry-exporter-otlp

パッケージをインストールしたら、次の Python サンプルのいずれかを使って、エージェントにトレースを実装できます。 コンソール トレースを使用するサンプルでは、ローカル環境のコンソールに結果が表示されます。 Azure Monitor を使用するサンプルは、Azure AI Foundry ポータルのポータルの左側のウィンドウの [監視] タブで、Azure Monitor にトレースを送信します。

Azure Monitor の使用

• 基本的なエージェントの例
• ツールを使用したエージェントの例
• ストリーム イベント ハンドラーを含む例

コンソール トレースの使用

• 基本的なエージェントの例
• ツールを使用したエージェントの例
• ストリーム イベント ハンドラーを含む例