エージェント デバッガーは、記録された会話を読み込み、エージェントが行った各判断を確認するのに役立つ診断ツールです。 会話の各ターンについて、実行パス、ステップの処理時間、トークンの使用状況、サポート情報ソース、ステップの引数、オーケストレーターの推論内容をレビューできます。
エージェント デバッガーは、2 つのデータソースに対応しています:
- 会話トランスクリプト (Dataverse): Copilot Studio で会話が行われると、プラットフォームは活動ログを「会話のトランスクリプト」として Dataverse に記録します。 エージェント デバッガーはこれらのレコードを直接照会するため、トランスクリプト データを持つ公開済みのエージェントはすべて、即座に利用可能になります。
- Copilot Studio スナップショット (ZIP): Copilot Studio のテストパネルには、スナップショットをダウンロードのオプションがあり、現在のテスト会話を ZIP ファイルとしてエクスポートできます。 そのファイルを エージェント デバッガーにアップロードすると、Dataverse に接続していなくても、完全な分析ビューが表示されます。 この方法は、運用開始前の会話のデバッグ、オフラインでの問題の再現、あるいは正常に動作しないセッションを同僚と共有する際に使用されます。
両方のデータソースは、同じ分析インターフェイスにデータを提供しています。 データの読み込み方法にかかわらず、パネル、ステップの詳細、可視化はすべて同じです。
必要条件
エージェントデバッガーを使用するには、以下の前提条件が満たされていることを確認してください:
- のエージェントはエージェント インベントリに登録されており、そのエージェントに対して少なくとも 1 件のトランスクリプトが保存されています。 この条件を確認するには、「エージェント インベントリ」のリスト ビューを開き、対象のエージェントを選択して、詳細を表示を選択し、追加のフィールドを展開してください。 トランスクリプトの可用性のフィールドははいに設定する必要があります。 Dataverse にそのエージェントに関するトランスクリプトが 1 件以上存在する場合、エージェントのインベントリ同期によってこのフィールドが自動的に設定されます。
- ログイン中のユーザーは、キット環境において CSK - 管理者またはシステム管理者のロールを持っています。
- ログイン中のユーザーは、ターゲット環境内の
conversationtranscripts、bot、botcomponentsテーブルに対して読み取り権限を持っています。
注意
デバッグ対象のエージェントが、キットがインストールされている環境とは異なる環境にある場合は、リモート環境において、同じ読み取り権限で Dataverse 接続の認証を行う必要があります。
会話を選択する
エージェント デバッガーを開くと、フィルター バーに、分析対象の会話を見つけるために必要な操作機能が用意されています。
| フィルター | 内容 |
|---|---|
| Environment | エージェント インベントリ内に存在する固有の環境名から取り込まれます。 環境を選択すると、エージェント ドロップダウン メニューに、その環境に登録されているエージェントのみが表示されるようになります。 |
| エージェント | 選択した環境において、トランスクリプトの可用性フィールドがはいに設定されているエージェントを表示します。 エージェントを選択すると、選択した期間内の直近 50 件の会話が会話 ID ドロップダウンに読み込まれます。 |
| 会話 ID | 構成された期間内に、選択したエージェントに関する直近の 50 件のユニークな会話が表示されます。 ボックスに入力すると、そのエージェントに関するすべてのトランスクリプト (最大 10 万件) が対象となる全件検索がトリガーされるため、期間に関係なく、過去の会話や特定の会話を検索することができます。 |
| [時間の範囲] | 会話 ID のリストを特定のウィンドウに絞り込みます。 過去 30 分、過去 1 時間、過去 4 時間、過去 24 時間、過去 7 日間、またはカスタム期間から選択してください。 カスタム範囲を選択すると、開始および終了のタイム スタンプを設定するための日付および時刻ピッカーが表示されます。 |
| エラー会話のみ | 会話 ID のドロップダウン一覧を、少なくとも 1 つの失敗したステップまたはシステムエラーを含む会話にフィルターします。 インシデントの優先順位付けを行う際や、信頼性に問題があることが判明しているエージェントを確認する際は、このオプションを使用してください。 |
会話 ID を選択すると、分析機能が利用可能になります。 これを選択すると、分析ビューが開きます。
注意
会話 ID を直接入力すると、現在選択されている期間に関係なく、常にすべてのトランスクリプトが検索対象となります。 エラーの会話のみフィルターは、クライアント側でトランスクリプトの内容をスキャンするため、標準のクエリよりも処理に時間がかかります。 エラーでフィルターする必要が特にない限り、この設定は無効のままにしておいてください。
Copilot Studio からスナップショットをアップロードする
スナップショットのアップロード タブは、Dataverse へのアクセスを必要としない別のアクセス手段を提供します。 ドロップダウン メニューからライブ会話を選択する代わりに、Copilot Studio のテストペインからダウンロードしたスナップショットの ZIP ファイルをアップロードします。
Copilot Studio からスナップショットをダウンロードする方法:
- Copilot Studio でエージェントを開き、エージェントをテストするパネルに移動します。
- 会話を再生またはレビューします。
- テスト パネルのツール バーからスナップショットのダウンロードを選択します。
Copilot Studio は、以下の内容を含む .zip ファイルをダウンロードします:
-
dialog.json: その会話に関するすべての Bot Framework 活動 (必須)。 -
botContent.yml: ステップ名を解決するために使用される、エージェントの完全なコンポーネントおよびフローの定義 (任意: 指定がない場合は、生のスキーマ名が表示されます)。
スナップショットをエージェントデバッガーにアップロードする方法:
- エージェント デバッガーのヘッダーで、スナップショットのアップロード タブに切り替えます。
-
.zipファイルをドロップゾーンにドラッグ＆ドロップするか、選択してファイルを選択してください。
エージェント デバッガー は ZIP ファイルの整合性を確認し、ファイルを解凍して、分析ビューを開きます。 環境、エージェント、会話の選択は不要です。 一般的な情報の指標はすべて、アップロードされたファイルに基づいて算出されています。
以下の場合は、「スナップショットのアップロード」モードを使用します:
- エージェントが公開される前に、テスト ペインで行われた会話をデバッグします。
- 認証できない環境での会話を分析します。
- Dataverse へのアクセス権を付与することなく、オフラインで問題を再現したり、正常に動作しないセッションを同僚と共有したりできます。
- ローカル開発環境において、エージェントの挙動を検証します。
会話の分析
分析を選択するか、スナップショットをアップロードすると、分析ビューが開きます。 上部には一般情報の概要行があり、4 つのパネル (実行パス、パフォーマンスのタイムライン、エージェントの詳細、推奨事項) で構成される折りたたみ可能な分析セクション、そして会話のプレビューとデバッグ情報パネルを並べて表示する 2 パネル構成となっています。
一般情報
「一般情報」行には、その会話に関する概要メトリックのタイルが表示されます。
| フィールド | 内容 |
|---|---|
| セッション | 会話セッションの数。 ユーザーが一定時間操作を行わなかった後、同じ会話に戻った場合、複数のセッションが発生します。 |
| ターン | その会話に含まれるユーザー メッセージの数。 |
| 結果 | プラットフォームによって報告されるセッションの結果 (Resolved、Escalated、Abandoned、SystemError など)。 |
| 期間 | 最初の活動から最後の活動までの会話の合計時間。 |
| Start Time | 会話が始まったとき (現地時間) 。 |
| チャネル | 使用されるコミュニケーション チャネル (Web チャットや Microsoft Teams など)。 在庫がある場合に表示されます。 |
| モデル | この会話において、エージェントのオーケストレーターが使用した AI モデル。 |
ライブ チャット オペレーターが読み込まれると、一般情報のヘッダーにエージェントを開くリンクが表示されます。 このリンクをクリックすると、Copilot Studio でエージェントの設定ページが開きます。
実行経路
実行パスは、すべての会話のターンにわたる完全な実行順序を、方向付きフロー図として表現します。 各手順は、実行の順序に従って左から右へと進みます。 破線の縦線が改行の境界を示しており、各ユーザー メッセージの開始ごとに新しいセクションが始まります。 各セクションの上部にターン ラベルが表示されます。 ターン ラベルを選択すると、会話のプレビューがそのメッセージの位置までスクロールします。
各ステップの種類ではそれぞれ異なる色が使用されており、図の下部にある凡例では、色と「トピック」、「ナレッジ」、「ツール」、「コネクタ」、「フロー」、「コード」、「MCP」、「接続されたエージェント」などのステップのカテゴリとの対応関係が示されています。 各ノードには、ステップ名と実行時間が表示されます。 失敗した手順は赤で強調表示されます。 接続されたエージェントは、実行した子ステップをグループ化したコンテナ ボックスとして表示されます。
パフォーマンスのタイムライン
パフォーマンスのタイムラインには、会話のターンごとにグループ分けされたステップの実行時間を示すウォーター フォール チャートが表示されています。 ステップ バーは、ターン全体の持続時間に合わせて調整されており、相対的なタイミングが把握できるようになっています。 色分けは実行パスの凡例と一致しており、失敗したステップは赤色で表示されます。
このパネルには、以下の機能が備わっています:
- すべて展開/折りたたむボタンをクリックすると、すべてのターン セクションを一括で切り替えできます。 各ターン セクションは、個別に折りたたむこともできます。
- ターンごとの統計情報には、ステップ数、最も遅いステップの名称と所要時間、失敗回数が表示されます。
- 上部にある全体概要には、総ステップ数、総経過時間、会話全体を通じて最も遅かったステップ、および失敗の総数が表示されます。
- 10 秒より遅いステップ数には、警告インジケーターが表示されます。
エージェントの詳細
エージェント詳細パネルには、会話が分析された時点でのエージェントの構成内容がすべて表示されます。 情報は 6 つのタブに整理されています。
| Tab キー | 内容 |
|---|---|
| 概要 | トピック、ツール、ナレッジ、子エージェント、オーケストレーションモード、言語、認証モード、モデル ナレッジ、セマンティック検索、最新モデルに関する KPI タイル。 各タイルには、その設定を説明するヒントが表示されています。 |
| 方法 | Copilot Studio で構成された、エージェントのシステム プロンプトの全文。 |
| トピック | 名前、説明、入力/出力変数、有効/無効のステータスが記載されたすべてのトピック。 |
| ツール | すべてのツールについて、名称、説明、タイプバッジ (MCP、Flow、コネクタ、プロンプト)、有効/無効の状態が表示されます。 |
| 知識 | 名前、タイプバッジ (SharePoint、Web、Dataverse、ファイル)、URL、有効/無効の状態が記載されたすべてのサポート情報ソース。 |
| エージェント | 名前、関係タイプ、有効/無効ステータスを持つ、接続済みのすべての子エージェント。 |
レコメンデーション
レコメンデーション パネルは、会話内の問題を自動的に検出し、重大度評価付きのアクション可能なカードとして表示します。
| 重大度 | 内容 |
|---|---|
| 高 | 応答の失敗や誤った応答を引き起こしたと考えられます。 直ちに調査を行います。 |
| 中 | エクスペリエンスの低下、または信頼性のリスク。 レビューを近日中に実施します。 |
| 低 | 軽微な不備、あるいは参考情報です。 |
以下の問題タイプが検出されます:
| 問題 | 重大度 | 内容 |
|---|---|---|
| 失敗したステップまたはエラー | 高 | ステップでエラーまたは例外が発生しました。 |
| 責任ある AI のブロック | 高 | このコンテンツは、Responsible AI システムによってフィルターされました。 |
| 会話のエスカレーション | 高 | 会話が人間のエージェントに引き継がれました。 |
| 会話の放棄 | 高 | ユーザーが問題が解決しないまま去りました。 |
| フォールバック トピックのトリガー | 高 | エージェントは、ユーザーのメッセージをトピックにルーティングできませんでした。 |
| 遅いステップ (>10秒) | Medium | あるステップの実行に 10 秒以上かかりました。 |
| サポート情報検索の失敗 | Medium | サポート情報ソースにクエリを実行しましたが、結果は返されませんでした。 |
| トークンの限度に近づきました | Medium | トークンの使用量が、モデルのコンテキスト ウィンドウの上限に近づきました。 |
| コード ステップ エラー | 高 | Python のコード ステップで例外が発生しました。 |
| MCP の初期化に失敗しました | 高 | 通信中に MCP サーバーの初期化に失敗しました。 |
各レコメンデーション カードには、深刻度を示すアイコンと色、カテゴリバッジ、検出された問題のタイトルと説明、調査や解決方法の提案、ターンに移動するボタンが表示され、このボタンをクリックすると、会話のプレビューが該当するユーザーのメッセージまでスクロールします。 問題が検出されない場合、パネルには空の状態を示すメッセージが表示されます。
会話のプレビュー
会話プレビュー パネルには、ユーザーに表示された通りの会話のやり取りがすべて表示されます。これには、ボットとユーザーのメッセージ バブル、インラインでレンダリングされたアダプティブ カード、推奨アクションチップ、およびフィードバックのプロンプトが含まれます。
ユーザー メッセージの吹き出しを選択すると、そのターンの手順がデバッグ情報パネルに読み込まれます。 選択されたメッセージはハイライト表示されるため、現在どのターンがアクティブかを確認できます。 このパネルは個別にスクロールできます。 会話プレビューのヘッダーにある JSON を表示を選択すると、会話の完全なトランスクリプト JSON ダイアログが開きます。
デバッグ情報
デバッグ情報パネルには、選択したユーザー メッセージのターンに関するステップ単位の詳細が表示されます。 このパネルには、左側にステップ一覧が表示され、ステップを選択するとステップの詳細ビューが開きます。
ステップ一覧には、選択したターンで実行されたすべてのオーケストレーターのステップが表示されます。各ステップには、ステップの種類を示すアイコンと色、ステップ名 (可能な場合はわかりやすい表示名に変換されます)、実行時間、成功または失敗のインジケーターが表示されます。 関連付けられたエージェントに属するステップは、エージェント名と合計実行時間を表示する、折りたたみ可能なコンテナ カード内にグループ化されています。 コンテナ上のエージェントの詳細を読み込むボタンをクリックすると、子エージェントのトランスクリプト全体がオンデマンドで読み込まれます。
以下のステップ タイプがサポートされています:
| タイプ | 内容 |
|---|---|
| トピック | エージェントのトピック一覧にある、名前が付けられたトピックです。 |
| システム トピック | Greeting、Fallback、Escalate などの組み込みプラットフォーム トピック。 |
| 知識 | サポート情報ソースの検索手順です。 |
| ツール / アクション | Power Automate のフローまたはコネクター アクションです。 |
| "コード" | Python コードの実行ステップです。 |
| カスタム プロンプト | カスタム生成 AI のプロンプトのステップ。 |
| 推論機能 | オーケストレーターが使用する内部的な推論のステップです。 |
| MCP サーバー | モデル コンテキスト プロトコル ツールの呼び出し。 |
| 接続されたエージェント | 接続された子エージェントへの委任。 |
ステップを選択すると、トランスクリプトにデータが存在する場合、以下のセクションを含む詳細パネルが表示されます:
- 思考の過程: ステップが呼び出される前に記録された、オーケストレーターの推論テキストです。 モデルがこのステップをどのように呼び出すことを決定したか、またそのステップに何を期待していたかを示します。
- ステップの種類: ステップの分類ラベルです。
- 引数: ステップに渡された入力パラメーターの、折りたたみ可能な JSON ツリー ビューです。 サポート チケットの JSON データを取得するためのコピー機能が含まれています。
- 観察: ステップからの出力または戻り値です。 また、コピー機能付きの折りたたみ可能な JSON ツリーとしても表示されます。
- コード プレビュー: Python のコード手順については、ソース コードが構文強調表示されて表示されます。
- トークン使用: そのステップのプロンプトのトークン数、完成トークン数、合計数、使用されたモデル名です。
- サポート情報ソース: 検索対象とした情報源、得られた結果 (出力)、最終的な応答で実際に引用された情報源です。 各エントリには、ソース名、タイプ、利用可能な場合は URL、ソースを開くためのリンクが表示されています。
- MCP サーバー情報: MCP ステップについては、サーバーのプロトコル バージョン、宣言された機能、初期化時にサーバーが提供したツールのリストが表示されます。
- エラー情報: ステップが失敗した場合、エラーコード、エラーメッセージ、(責任ある AI のブロックの場合) フィルターが作動した原因となったコンテンツの安全性のカテゴリが表示されます。
- アダプティブ カード: ステップでアダプティブ カードの応答が生成された場合、そのカードは、ユーザーが実際に目にするのと同じ状態で、詳細パネル内にインラインで表示されます。
トランスクリプト JSON
会話プレビューのヘッダーで JSON を表示するを選択すると、ダイアログが開き、構文の強調表示が施された完全な生のトランスクリプトの活動、JSON ツリー内での全文検索、およびペイロード全体のクリップボードへのコピー オプションが表示されます。
次の場合にこのビューを使用します:
- デバッグ情報パネルに表示されていないイベント タイプを確認する必要があります。
- サポート チケットの特定のフィールドをコピーするとします。
- 解析済みのビューにおける予期せぬ動作について調査しています。
トラブルシューティング
以下のセクションでは、よくある問題とその解決方法について説明します。
「環境」または「エージェント」のドロップダウンにエージェントが表示されない
そのエージェントは「エージェント インベントリ」と同期されていないか、会話のトランスクリプトが一切ありません。
この問題を解決するには、次の手順を実行します。
- その環境に対して、エージェント インベントリの手動同期を実行してください。
- Dataverse の「エージェント詳細」テーブルに、そのエージェントのレコードが存在することを確認してください。
- レコードのトランスクリプトの可用性の列がはいに設定されていることを確認してください。 少なくとも 1 つのトランスクリプトが存在する場合、同期処理によりこのフィールドに値が設定されます。
詳細については、Copilot エージェント キットのエージェント インベントリを使用したエージェントの監視を参照してください。
ドロップダウンに会話 ID が見つかりません
パフォーマンス向上のため、ドロップダウンには、アクティブな時間の範囲内の直近 50 件の会話のみがプリロードされます。 古いトランスクリプトは Dataverse にまだ残っていますが、既定では表示されません。 あるいは、会話が終わったばかりの場合は、トランスクリプトがまだ作成されていない可能性もあります。
この問題を解決するには、次の手順を実行します。
- 会話 ID フィールドに、会話 ID を直接入力してください。 入力すると、時間の範囲を無視して、そのエージェントのすべてのトランスクリプトを対象に全検索がトリガーされます。
- 時間範囲が狭い場合 (過去 30 分間など)、範囲を広げるか、会話の日付を含むカスタム範囲に切り替えてください。
- 会話が終了したばかりの場合は、Dataverse にトランスクリプトが書き込まれるまで 35 ～ 40 分ほど待ってから、ページを更新してください。
負荷を分析したが、デバッグ情報パネルにステップが表示されない
トランスクリプトは存在しますが、メッセージ型の活動のみが含まれており、診断トレース イベントは含まれていません。 この問題は通常、特定のカスタム チャンネルや古いスキーマ バージョンなど、トレースデータを送信しないチャンネルからの会話が発生した場合に生じます。
この問題を解決するには、次の手順を実行します。
- 会話プレビューのヘッダーにある JSON を表示するを選択し、活動が存在することを確認します。
-
type: "trace"またはtype: "event"エントリを検索します。 それらが存在しない場合、そのチャネルにはトレース データを出力しない可能性があります。
読み込み時にアクセス拒否または空白のページが表示される
いずれか一方、あるいは両方の環境で、ロールまたはアクセス許可が不足しています。
この問題を解決するには、次の手順を実行します。
- キット環境では、ユーザーに CSK - 管理者またはシステム管理者のロールが割り当てられていることを確認してください。
- 対象の環境において、サインインしているユーザーが
conversationtranscripts、bot、botcomponentsの各テーブルに対する読み取り権限を持っていることを確認してください。
トランスクリプトが不完全 (初期メッセージが欠落している) のようです
長い会話は、複数の Dataverse レコードに分割されています ( 1 レコードあたり 1 MB の制限)。 アイテム保持ポリシーによって一部の記録が削除された場合、統合されたトランスクリプトには欠落が生じます。
この問題を解決するには、次の手順を実行します。
- Dataverse では、既定で 30 日以上経過した会話のトランスクリプトは削除されます。 保持が問題である場合は、Power Apps>設定>詳細設定>データ管理>レコードの一括削除 で、一括削除ジョブのスケジュールを更新してください。
- 保持が原因でない場合は、その会話に関するすべてのトランスクリプト記録が、Dataverse の
conversationtranscriptsテーブルに存在することを確認してください。
各ステップでは、読みやすいトピック名ではなく、生のスキーマ名が表示されます
botcomponents テーブルの検索に失敗したか、コンポーネント レコードが削除されました。
この問題を解決するには、次の手順を実行します。
- ログイン中のユーザーが、対象環境内の
botcomponentsテーブルに対する読み取り権限を持っていることを確認してください。 - Copilot Studio からコンポーネントが削除された場合、一致するレコードが存在しないため、エージェントデバッガーは
cr123_mytopicなどの生のスキーマ名を使用します。 削除されたトピックやアクションについては、この動作は想定内です。
エージェントの詳細パネルにデータが表示されない
エージェント構成の取得に失敗したか、またはログイン中のユーザーの接続が、ターゲット環境内の bot および botcomponents テーブルに対する読み取りアクセス権がありません。
この問題を解決するには、次の手順を実行します。
- アプリで使用されている接続参照について、
botとbotcomponentsテーブルへの読み取りアクセス権を確認してください。 - 会話が記録された後にエージェントが削除されたり、公開が解除されたりした場合、その構成レコードは存在しなくなる可能性があります。 この場合、エージェントの詳細パネルは空のままですが、トランスクリプト パネルとデバッグ パネルは引き続き正常に機能します。
レコメンデーション パネルには問題が表示されていないが、通信に失敗しました
レコメンデーションは、トランスクリプトのトレース イベントに見られるパターンに基づいて導き出されます。 トランスクリプトにトレース データが含まれていない場合、または会話の外でエラーが発生した場合 (トランスクリプトに記録されないサイレントなネットワーク タイムアウトなど)、システムはレコメンデーションを生成しません。
この問題を解決するには、次の手順を実行します。
- トランスクリプトの JSON ファイルを開き、推奨事項として表示されていない生のエラー ペイロードを探します。
- 実行パスに赤色で表示されているステップがないかを確認してください。 これらの手順は、既知の推奨パターンに該当しないエラーを示しています。