Application Insights を使用したトレース
エージェントの実行の背後にある理由を明らかにすることは、トラブルシューティングとデバッグのために重要です。 ただし、複雑なエージェントの場合、さまざまな理由でそれが難かしい場合があります。
- 応答の生成に多くのステップが関係し、それらのすべてを追跡するのが難しい場合があります。
- ステップのシーケンスが、ユーザー入力によって変わる場合があります。
- 各ステージでの入力と出力が長く、より詳細な検査が必要な場合があります。
- エージェントの実行時の各ステップに、入れ子が含まれる場合もあります。 たとえば、エージェントがツールを呼び出し、それが別のプロセスを使い、さらにそれが別のツールを呼び出しているような場合です。 最上位レベルのエージェントの実行からの出力が奇妙であったり正しくないことがわかった場合、実行で問題が発生した場所を正確に特定するのが難かしいことがあります。
トレースを使うと、特定のエージェント実行に関係する各プリミティブの入力と出力を、それが呼び出された順序で明確に確認できるようになり、これが解決されます。
Application Insights リソースの作成
トレースでは、OpenTelemetry を使い、Application Insights リソースを Azure AI Foundry プロジェクトに追加して、エージェントのパフォーマンスと動作を分析できます。
Application Insights リソースを追加するには、Azure AI Foundry ポータルの [トレース] タブに移動し、まだない場合は新しいリソースを作成します。
作成したら、Application Insights の接続文字列を取得し、エージェントを構成して、Azure Monitor によりエージェントの完全な実行パスを観察できます。 通常は、エージェントを作成する前にトレースを有効にします。
エージェントをトレースする
最初に、pip install を使って、OpenTelemetry と Azure SDK トレース プラグインをインストールします。
pip install opentelemetry
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 にトレースを送信します。
Note
エージェント トレース機能には既知のバグがあります。 このバグにより、コンテンツの記録が有効になっていない場合でも、エージェントの関数ツールの呼び出し関連情報 (機密情報を含む可能性がある関数名とパラメーター値) がトレースに含まれるようになります。
Azure Monitor の使用
コンソール トレースの使用