Agent 偵錯工具是一種診斷工具，可協助您載入已錄製的交談，並檢查 Agent 所做的每項決策。 針對每個交談回合，您可以檢閱執行路徑、步驟時間、權杖使用量、知識來源、步驟引數，以及協調器的推理過程。
Agent 偵錯工具支援兩種資料來源：
- 交談文字記錄 (Dataverse)：當交談在 Copilot Studio 中執行時，平台會以 Dataverse 中的交談文字記錄形式記錄活動記錄檔。 Agent 偵錯工具會直接查詢這些記錄，因此任何具有文字記錄資料的已發佈 Agent 都能立即取用。
- Copilot Studio 快照 (ZIP)：Copilot Studio 測試窗格包含下載快照選項，可將目前的測試交談匯出為 ZIP 檔案。 將該檔案上傳至 Agent 偵錯工具，即可在不需要 Dataverse 連線的情況下取得完整的分析檢視。 此方法適用於偵錯正式環境上線前的交談、離線重現問題，或與同事分享失敗的工作階段。
這兩種資料來源會提供給相同的分析介面。 無論資料如何載入，面板、步驟詳細資料和視覺化呈現都相同。
先決條件
若要使用 Agent 偵錯工具，請確認已符合下列先決條件：
- 此 Agent 已存在於 Agent 詳細目錄中，且至少已針對其記錄一筆交談文字記錄。 您可以開啟 Agent 詳細目錄清單檢視、選取該 Agent，然後選取顯示更多以展開其他欄位，藉此驗證此條件。 文字記錄是否可用欄位必須設為是。 當 Dataverse 中至少存在一筆該 Agent 的交談文字記錄時，Agent 詳細目錄同步作業就會自動設定此欄位。
- 已登入的使用者在套件環境中具有 CSK - Administrator 或系統管理員安全性角色。
- 已登入的使用者在目標環境的
conversationtranscripts、bot和botcomponents資料表上具有讀取存取權。
注意
如果您要偵錯的 Agent 位於安裝套件之環境以外的其他環境，您必須在遠端環境中，使用相同的讀取權限驗證 Dataverse 連線。
選取交談
開啟 Agent 偵錯工具時，篩選列會提供您找出要分析之交談所需的控制項。
| 篩選器 | Description |
|---|---|
| 環境 | 從 Agent 詳細目錄中找到的不重複環境名稱填入。 選取環境會將 Agent 下拉式清單縮小為在該環境中註冊的 Agent。 |
| Agent | 顯示所選環境中，文字記錄是否可用欄位設為是的 Agent。 選取 Agent 會將所選時間範圍內最近的 50 個交談，載入交談識別碼下拉式清單中。 |
| 交談識別碼 | 顯示所設定時間範圍內，所選 Agent 最近的 50 個不重複交談。 在方塊中輸入內容會觸發該 Agent 所有文字記錄的完整搜尋 (最多 100,000 筆記錄)，因此無論時間範圍為何，您都能找到較舊或特定的交談。 |
| 時間範圍 | 將交談識別碼清單縮小為特定的時間範圍。 從過去 30 分鐘、過去 1 小時、過去 4 小時、過去 24 小時、過去 7 天或自訂範圍中選擇。 選取自訂範圍時，會顯示日期和時間選擇器，供您設定開始與結束時間戳記。 |
| 僅限錯誤交談 | 將交談識別碼下拉式清單篩選為至少包含一個失敗步驟或系統錯誤的交談。 在分流事件或檢閱已知有可靠性問題的 Agent 時，請使用此選項。 |
選取交談識別碼後，分析就會變成可用。 選取後即可開啟分析檢視。
注意
直接輸入交談識別碼一律會搜尋所有文字記錄，無論目前使用中的時間範圍為何。 僅限錯誤交談篩選會在用戶端掃描文字記錄內容，所需時間比標準查詢長。 除非您特別需要依錯誤篩選，否則請將其保持關閉。
從 Copilot Studio 上傳快照
上傳快照索引標籤提供不需要 Dataverse 存取權的替代進入點。 您可以從 Copilot Studio 測試窗格下載快照 ZIP 檔案並上傳，而不是從下拉式清單中選取即時交談。
若要從 Copilot Studio 下載快照：
- 在 Copilot Studio 中開啟您的 Agent，然後前往測試您的 Agent 窗格。
- 執行或檢閱交談。
- 在測試窗格工具列中選取下載快照。
Copilot Studio 會下載一個 .zip 檔案，其中包含：
-
dialog.json：交談的所有 Bot Framework 活動 (必要)。 -
botContent.yml：Agent 完整的元件與流程定義，用於解析步驟名稱 (選用；若無此檔案，則會顯示原始結構描述名稱)。
若要將快照上傳至 Agent 偵錯工具：
- 在 Agent 偵錯工具標頭中，切換至上傳快照索引標籤。
- 將
.zip檔案拖放至拖放區，或選取以瀏覽尋找檔案。
Agent 偵錯工具會驗證 ZIP 檔案、解壓縮檔案，並開啟分析檢視。 不需要選取環境、Agent 或交談。 所有一般資訊指標都是從上傳的檔案衍生而來。
在您需要下列操作時，請使用上傳快照模式：
- 偵錯 Agent 發佈前在測試窗格中發生的交談。
- 分析來自您無法驗證之環境的交談。
- 離線重現問題，或在不授予 Dataverse 存取權的情況下，與同事分享失敗的工作階段。
- 在本機開發環境中驗證 Agent 行為。
分析交談
選取分析或上傳快照後，即會開啟分析檢視。 此檢視頂端包含一般資訊摘要列，接著是含四個面板的可摺疊分析區段 (執行路徑、效能時間表、Agent 詳細資料和建議)，以及以雙面板配置並列顯示交談預覽與偵錯資訊面板。
一般資訊
一般資訊列會顯示交談的摘要指標方塊。
| 欄位 | 描述 |
|---|---|
| 工作階段 | 交談工作階段的數目。 當使用者在閒置一段時間後返回相同交談時，就會產生多個工作階段。 |
| 回合 | 交談中使用者訊息的數目。 |
| 結果 | 平台回報的工作階段結果，例如已解決、已升級、已放棄或 SystemError。 |
| 持續時間 | 從第一個到最後一個活動的交談總時長。 |
| 開始時間 | 交談開始的時間 (當地時間)。 |
| 通道 | 使用的通訊通道，例如 webchat 或 msteams。 有資料時才會顯示。 |
| 模型 | 此交談中 Agent 協調器所使用的 AI 模型。 |
載入線上 Agent 時，一般資訊標頭中會顯示開啟 Agent 連結。 此連結會開啟 Copilot Studio 中該 Agent 的設定頁面。
執行路徑
執行路徑會以有向流程圖的方式，呈現所有交談回合的完整執行順序。 步驟會依執行順序由左至右呈現。 虛線垂直線會標示回合界線，每則使用者訊息都會開始新的區段。 回合標籤會顯示在每個區段的頂端。 選取回合標籤會將交談預覽捲動至該訊息。
每種步驟類型會使用不同的顏色，圖表底部的圖例會將顏色對應至步驟類別，例如主題、知識、工具、連接器、流程、程式碼、MCP 和已連接的 Agent。 每個節點都會顯示步驟名稱和執行持續時間。 失敗的步驟會以紅色反白顯示。 已連接的 Agent 會顯示為容器方塊，將其執行的子步驟分組在一起。
效能時間表
效能時間表會顯示依交談回合分組的步驟執行時間瀑布圖。 步驟長條會依該回合的總持續時間縮放比例，以呈現相對時間關係。 顏色配置與執行路徑圖例相符，失敗的步驟會以紅色顯示。
此面板包含下列功能：
- 全部展開/摺疊按鈕可一次切換所有回合區段。 每個回合區段也可個別摺疊。
- 各回合的統計資料會顯示步驟數目、最慢步驟的名稱與持續時間，以及失敗次數。
- 頂端的整體摘要會顯示總步驟數、總經過時間、整個交談中最慢的步驟，以及總失敗次數。
- 超過 10 秒的步驟會標示警告指示器。
Agent 詳細資料
Agent 詳細資料面板會顯示分析交談當時 Agent 的完整設定。 這些資訊會分成六個索引標籤呈現。
| 索引標籤 | Description |
|---|---|
| 概觀 | 主題、工具、知識、子 Agent、協調流程模式、語言、驗證模式、模型知識、語意搜尋和最新模型的 KPI 方塊。 每個方塊都包含說明該設定的工具提示。 |
| 指示 | 在 Copilot Studio 中設定的 Agent 完整系統提示。 |
| 主題 | 所有主題的名稱、描述、輸入/輸出變數，以及已啟用/已停用狀態。 |
| 工具 | 所有工具的名稱、描述、類型徽章 (MCP、流程、連接器、提示)，以及已啟用/已停用狀態。 |
| 知識 | 所有知識來源的名稱、類型徽章 (SharePoint、Web、Dataverse、File)、URL，以及已啟用/已停用狀態。 |
| Agents | 所有已連接子 Agent 的名稱、關聯類型，以及已啟用/已停用狀態。 |
建議
建議面板會自動偵測交談中的問題，並以含嚴重性評等的可採取行動卡片呈現。
| 嚴重性 | Description |
|---|---|
| 高 | 可能造成失敗或不正確的回應。 請立即調查。 |
| 中 | 體驗降級或可靠性風險。 請儘快檢閱。 |
| 低 | 輕微的效率問題或參考性說明。 |
系統會偵測下列問題類型：
| 問題 | 嚴重性 | Description |
|---|---|---|
| 步驟失敗或錯誤 | 高 | 步驟傳回錯誤或例外狀況。 |
| 負責任 AI 封鎖 | 高 | 內容已由負責任 AI 系統篩選。 |
| 交談升級 | 高 | 此交談已轉接給真人專員。 |
| 交談放棄 | 高 | 使用者在問題未獲解決前就離開了。 |
| 後援主題觸發 | 高 | Agent 未能將使用者的訊息路由至主題。 |
| 步驟過慢 (>10 秒) | 中 | 某個步驟的執行時間超過 10 秒。 |
| 知識搜尋失敗 | 中 | 已查詢知識來源，但未傳回任何結果。 |
| 接近權杖限制 | 中 | 權杖使用量已接近模型的內容視窗限制。 |
| 程式碼步驟錯誤 | 高 | Python 程式碼步驟已擲回例外狀況。 |
| MCP 初始化失敗 | 高 | MCP 伺服器在交談期間初始化失敗。 |
每張建議卡片都會顯示嚴重性圖示與顏色、類別徽章、偵測到之問題的標題與描述、如何調查或解決該問題的建議，以及前往回合按鈕，可將交談預覽捲動至相關的使用者訊息。 未偵測到任何問題時，面板會顯示空白狀態訊息。
交談預覽
交談預覽面板會顯示使用者所見的完整交談內容，包括 Bot 與使用者的訊息泡泡、內嵌轉譯的調適型卡片、建議動作標籤，以及意見反應提示。
選取使用者訊息泡泡，會將該回合的步驟載入偵錯資訊面板。 所選的訊息會反白顯示，方便您追蹤目前使用中的回合。 此面板可獨立捲動。 在交談預覽標頭中選取檢視 JSON，即會開啟完整文字記錄 JSON 對話方塊。
偵錯資訊
偵錯資訊面板會顯示所選使用者訊息回合的步驟層級詳細資料。 此面板左側包含步驟清單，選取步驟時會開啟步驟詳細資料檢視。
步驟清單會顯示所選回合執行的每個協調器步驟，包括表示步驟類型的步驟圖示與顏色、步驟名稱 (盡可能解析為易讀的顯示名稱)、執行持續時間，以及成功或失敗指示器。 屬於已連接 Agent 的步驟，會分組顯示在可摺疊的容器卡片中，並顯示 Agent 名稱和總執行時間。 容器上的載入已連接的 Agent 詳細資料按鈕，可視需要載入子 Agent 的完整文字記錄。
支援下列步驟類型：
| 類型 | Description |
|---|---|
| 主題 | Agent 主題清單中具名的主題。 |
| 系統主題 | 平台內建的主題，例如問候、後援或升級。 |
| 知識 | 知識來源搜尋步驟。 |
| 工具/動作 | Power Automate 流程或連接器動作。 |
| 代碼 | Python 程式碼執行步驟。 |
| 自訂提示 | 自訂生成式 AI 提示步驟。 |
| 推理器 | 協調器使用的內部推理步驟。 |
| MCP 伺服器 | Model Context Protocol 工具叫用。 |
| 已連接的 Agent | 委派給已連接的子 Agent。 |
選取步驟會開啟詳細資料面板，其中包含下列區段 (僅在文字記錄中有相應資料時顯示)：
- 思考過程：在叫用步驟之前記錄的協調器推理文字。 顯示模型如何決定呼叫此步驟，以及對此步驟的預期結果。
- 步驟類型：該步驟的分類標籤。
- 引數：傳遞給該步驟之輸入參數的可摺疊 JSON 樹狀檢視。 包含複製選項，可擷取 JSON 內容用於支援單。
- 觀察結果：該步驟的輸出或傳回值。 同樣以可摺疊的 JSON 樹狀結構顯示，並支援複製。
- 程式碼預覽：對於 Python 程式碼步驟，會以語法反白顯示原始碼。
- 權杖使用量：該步驟的提示權杖數、完成權杖數與總計，以及所使用的模型名稱。
- 知識來源：已搜尋的來源、傳回的結果 (輸出)，以及最終回應中實際引用的來源。 每個項目都會顯示來源名稱、類型、URL (如有)，以及開啟該來源的連結。
- MCP 伺服器資訊：對於 MCP 步驟，會顯示伺服器的通訊協定版本、宣告的功能，以及伺服器在初始化期間提供的工具清單。
- 錯誤資訊：當步驟失敗時，會顯示錯誤代碼、錯誤訊息，以及 (若為負責任 AI 封鎖) 觸發篩選的內容安全性類別。
- 調適型卡片：當步驟產生調適型卡片回應時，該卡片會以使用者實際看到的樣式，內嵌轉譯於詳細資料面板中。
文字記錄 JSON
在交談預覽標頭中選取檢視 JSON 時，會開啟一個對話方塊，其中會以語法反白顯示完整的原始文字記錄活動，並提供 JSON 樹狀結構內的全文搜尋，以及複製整個承載內容至剪貼簿的選項。
在下列情況中使用此檢視：
- 您需要檢查未顯示在偵錯資訊面板中的事件類型。
- 您想要複製特定欄位用於支援單。
- 您正在調查已剖析檢視中的非預期行為。
疑難排解
下列章節說明常見問題及其解決方式。
Agent 未顯示在環境或 Agent 下拉式清單中
此 Agent 尚未同步至 Agent 詳細目錄，或沒有任何交談文字記錄。
若要解決此問題：
- 針對該環境執行手動 Agent 詳細目錄同步作業。
- 確認該 Agent 的記錄存在於 Dataverse 的 Agent Details 資料表中。
- 確認該記錄的文字記錄是否可用資料行設為是。 當至少存在一筆文字記錄時，同步作業就會設定此欄位。
如需詳細資訊，請參閱使用 Copilot Agent 套件中的 Agent 詳細目錄監視 Agent。
下拉式清單中找不到交談識別碼
基於效能考量，下拉式清單僅會預先載入目前時間範圍內最近的 50 個交談。 較舊的文字記錄仍存在於 Dataverse 中，但預設不會顯示。 另外，如果交談剛結束，文字記錄可能尚未寫入。
若要解決此問題：
- 直接在交談識別碼欄位中輸入交談識別碼。 輸入內容會觸發該 Agent 所有文字記錄的完整搜尋，並忽略時間範圍。
- 如果時間範圍過窄 (例如過去 30 分鐘)，請放寬範圍，或切換為涵蓋該交談日期的自訂範圍。
- 如果交談剛結束，請等候 35-40 分鐘，讓文字記錄寫入 Dataverse，然後重新整理。
分析已載入，但偵錯資訊面板中未顯示任何步驟
文字記錄存在，但僅包含訊息類型的活動，沒有診斷追蹤事件。 此問題通常發生在交談來自不會發出追蹤資料的通道時，例如某些自訂通道或較舊的結構描述版本。
若要解決此問題：
- 在交談預覽標頭中選取檢視 JSON，確認活動是否存在。
- 尋找
type: "trace"或type: "event"項目。 如果找不到這些項目，可能表示該通道不會發出追蹤資料。
載入時發生存取遭拒或空白頁面
其中一個或兩個環境都缺少角色或權限。
若要解決此問題：
- 在套件環境中，請確認使用者具有 CSK - Administrator 或系統管理員角色。
- 在目標環境中，請確認已登入的使用者對
conversationtranscripts、bot和botcomponents資料表具有讀取權限。
文字記錄顯示不完整 (缺少較早的訊息)
較長的交談會分割成多筆 Dataverse 記錄 (每筆記錄限制為 1 MB)。 如果保留原則清除了部分記錄，合併後的文字記錄就會出現缺漏。
若要解決此問題：
- 根據預設，Dataverse 會清除超過 30 天的交談文字記錄。 如果原因是保留原則，請在 Power Apps>設定>進階設定>資料管理>大量刪除記錄中，更新大量刪除工作的排程。
- 如果原因不是保留原則，請確認該交談的所有文字記錄都存在於 Dataverse 的
conversationtranscripts資料表中。
步驟顯示原始結構描述名稱，而非可讀的主題名稱
botcomponents 資料表查閱失敗，或該元件記錄已遭刪除。
若要解決此問題：
- 確認已登入的使用者對目標環境中的
botcomponents資料表具有讀取權限。 - 如果該元件已從 Copilot Studio 中刪除，就不會有相符的記錄，Agent 偵錯工具會回復使用原始結構描述名稱，例如
cr123_mytopic。 對於已刪除的主題或動作，這是預期的行為。
Agent 詳細資料面板未顯示任何資料
擷取 Agent 設定失敗，或已登入使用者的連線對目標環境中的 bot 和 botcomponents 資料表沒有讀取權限。
若要解決此問題：
- 確認應用程式使用的連線參考對
bot和botcomponents資料表具有讀取權限。 - 如果 Agent 在交談記錄後遭到刪除或取消發佈，其設定記錄可能已不存在。 在此情況下，Agent 詳細資料面板會保持空白，但文字記錄和偵錯面板仍可正常運作。
建議面板未顯示任何問題，但交談卻失敗了
建議是根據文字記錄追蹤事件中的模式而產生。 如果文字記錄缺少追蹤資料，或失敗發生在交談之外 (例如文字記錄未記錄的無提示網路逾時)，系統就不會產生任何建議。
若要解決此問題：
- 開啟文字記錄 JSON，尋找未顯示為建議的原始錯誤承載內容。
- 檢查執行路徑中是否有任何以紅色顯示的步驟。 這些步驟代表未對應到已知建議模式的失敗。