Microsoft Foundry Toolkit 中的 Agent 檢查器除錯代理程式

Microsoft Foundry Toolkit for Visual Studio Code 中的 Agent Inspector 讓你能向本地代理發送請求、檢查模型與工具活動，並除錯你的程式碼。 在部署變更前，先用它調查非預期回應。

此工作流程對 託管代理很有用，這些代理會在 Foundry Agent Service 中執行您的自訂程式碼。 本地檢查能幫助你除錯該程式碼。 在正式使用前，也要測試已部署代理的執行時身份、設定及網路存取。

在本文中，你將連線到本機代理程式、調查要求，並儲存診斷事件。 主路徑使用 Responses 協定。 可用的視圖取決於你的代理伺服器所提供的協定與診斷。

Prerequisites

  • Visual Studio Code 搭配目前公開的 Foundry Toolkit 擴充功能。 請參閱 安裝 Foundry 工具包。
  • 已設定好其相依項、模型設定和憑證的本機代理專案。 要從範例開始，請依照 Hosted agent 快速入門，直到本機測試為止。
  • 你專案所需的除錯器。 Python 範例使用 Python 擴充功能 和 debugpy。 其他語言和範例有不同的要求。

對於現有專案，Foundry Toolkit 的 Copilot 工具可以幫助準備設定。 檢視產生的檔案並依照專案的 README.md。 不要用通用設定替換它的啟動檔。

Important

本地代理程式可以呼叫雲端模型和即時工具。 使用非敏感的測試輸入，檢查工具權限，並考慮配置服務的費用。 Inspector 不會以模擬物件取代工具。

連接與除錯

在連接 Inspector 之前，先啟動代理伺服器。 利用專案產生的啟動設定來使伺服器、工作目錄、直譯器和除錯器的設定一致。

  1. 啟動代理程式時，使用其文件中的除錯設定。 對於託管代理程式的 Python 範例，請選擇除錯本地代理 HTTP Server，並按 F5。
  2. 如果 Inspector 沒有開啟，請在活動列中選擇 Foundry Toolkit，然後選擇 開發者工具>建置>代理檢查器。
  3. 檢查 Inspector 標頭中的端點。 目前的 Python 骨架使用 http://localhost:8088。 若要使用不同的伺服器連接埠，請選擇端點旁的鉛筆按鈕，輸入連接埠，然後選擇 連線。
  4. 確認標頭顯示 已連接。 當端點可達時，Inspector 會自動偵測回應或呼叫協定。
  5. 在你的代理代碼中設定一個斷點，並在 Playground 發送訊息。 執行暫停時檢查變數，然後繼續並檢視回應。

本地代理除錯設定截圖，以及 Agent Inspector 連接到 localhost 的 8088 連接埠並成功回應。

單純開啟 Inspector 不會啟動伺服器或連接除錯器。 產生的 Python 設定中，除錯器使用埠 5679，埠 8088 用於代理 HTTP 請求。 這些埠口與 OTLP 追蹤埠是分開的。

連線至通用的 Responses 端點

Inspector 可以連接本地通用的 Responses 端點，無需完整的開發診斷介面。 你可以檢查伺服器傳送的回應事件，但工作流程圖及其輸入輸出視圖不可用。

成功連線並不代表伺服器提供來源位置、令牌使用情況或推理。

發送 HTTP 呼叫

當你的代理程式接受自訂請求體而非對話訊息時，請使用 HTTP 調用。 伺服器的請求格式與回應協定決定了 Inspector 如何傳送與顯示結果。

  1. 連接到你正在執行中的 HTTP invocations 伺服器。 Inspector 會自動偵測該協定。
  2. 請輸入您的代理程式所需的請求本文。 如果伺服器暴露相容的 OpenAPI 規範，Inspector 可以補充範例。 寄出前請先檢視，或若沒有範例，請依照範例中的請求格式進行。
  3. 選擇輸入旁的請求設定齒輪，以依伺服器要求設定 Content-Type 和 Accept。 例如，使用 application/json 來表示 JSON 主體，並在伺服器支援串流回應時使用 text/event-stream。
  4. 選擇 「發送」 並檢查回覆狀態與正文。
  5. 在 預覽（格式化輸出）和 原始回應之間切換。 詳細資料面板也包含 輸入輸出（I/O） 和 大型語言模型（LLM）呼叫。 模型、工具和令牌細節取決於識別到的伺服器事件，因此並非每個回應都填滿每個分頁。

Inspector 處理一般的 HTTP 回應、伺服器發送的事件串流，或非同步回應。 對於非同步 202 Accepted 回應，它會輪詢呼叫直到完成或失敗。 選擇回應格式不會為你的伺服器增加串流或非同步支援。

對於串流回應， 停止 會斷開用戶端串流。 對於輪詢呼叫， Cancel 會向伺服器發送取消請求。 這兩種動作都無法保證代理程序或外部工具操作已經停止。

這個視圖不是 WebSocket 用戶端。 Activity Protocol 範例使用不同的沙箱。 請參閱 選擇其他協定或範例 以取得適當的本地測試路徑。

使用檢查器

先提出一個能驗證你想了解的行為的請求。 例如，對於天氣工具，請要求需要該工具的資訊，而不是模型能在沒有該工具的情況下產生的通用答案。

  1. 在 Playground 發送請求並查看串流回應。
  2. 使用詳細分頁找出緩慢或失敗的操作。
  3. 檢查相關事件或工具呼叫，修改程式碼或設定，然後重新發送請求。

按 Enter 鍵傳送，或按 Shift+Enter 加入換行。 要叫回先前的請求，請將插入點放在輸入的開頭，然後按下 上箭頭。 在結尾處按 下箭頭 即可前往較新的請求，並返回未寄出的草稿。

你可以在重新傳送已召回的請求前編輯已召回的請求。 輸入歷史是 Inspector 的便利工具，而非已儲存提示的持久儲存空間。

View 用它來做
Overview 跟著延遲瀑布圖和依序執行時間軸走。 選擇所有運行或單次執行，以將模型與工具活動和執行之間的閒置時間區分開來。
代幣 檢視已回報的輸入與輸出權杖使用情況。 缺少使用資料並不是零代幣結果。
活動 檢查解析過的回應事件，包括錯誤、函式呼叫及結果。 依事件類型或 JSON 內容搜尋，並依類別篩選。
Tools 檢查依回應執行分組的工具呼叫，包括狀態、呼叫 ID、參數及結果。

回應頁腳顯示模型、持續時間、代幣使用情況及時間戳記資訊（如提供時）。 推理文本與推理摘要會在代理人輸出這些內容時，以可摺疊的獨立區塊形式呈現。 Inspector 不會產生缺失的推理或揭露模型提供者未回傳的資訊。

檢查工具與權限

使用 Tools 來檢查代理是否以預期的參數呼叫了預期工具，並收到結果。 成功的模型回應並不代表工具已經運行。 如果你的程式碼使用了 mock，顯示的結果仍然是 mock 結果。

工具分頁的截圖，裡面有依執行分組的呼叫，以及一個展開的工具呼叫，顯示其參數和結果。

當回應暫停等待模型上下文協定（MCP）核准或 OAuth 同意時，訊息輸入框上方會出現待處理請求。 只授予你打算允許的存取權限。

對於 MCP 工具呼叫，選擇 顯示參數，檢視輸入，然後選擇 核准 或 拒絕。 「全部批准」和「全部拒絕」都適用於待處理的請求，而不是永久性工具核准政策。

若要完成 OAuth 同意，請同時完成瀏覽器授權及檢查員確認：

  1. 選擇 「Open consent」 以針對待處理的請求。
  2. 在瀏覽器完成授權後，返回檢查器，選擇 「完成同意」。 若要拒絕授權，請選擇 取消 。
  3. 處理剩餘的同意要求。 在完成所有已開啟請求的授權後，使用 「All Done」功能（若有）。

僅僅開啟同意頁面並不會繼續該請求。 檢查員等待每項待處理的同意有了決定後，才再次檢查伺服器。 如果伺服器仍需授權，要求可能會再次出現。

檢查後續工具的結果，而非僅是核可狀態，以確認完成。 關於連線與認證設定，請參見 工具目錄。 不要為了讓診斷錯誤消失而更改工具的憑證或權限。

檢視工作流程與原始碼

對於支援的 Microsoft Agent Framework 工作流程，開發伺服器可提供工作流程診斷與來源位置。 Inspector 利用這些資訊顯示執行圖，並協助你導航到程式碼。

  1. 選擇一個工作流程節點來檢查可用的輸入與輸出。
  2. 雙擊該節點即可開啟其來源位置。
  3. 設定一個中斷點，並再次發出要求以在除錯器中檢查操作。

你可以在 Playground 測試 LangGraph 的工作流程，但不支援 LangGraph 工作流程的視覺化。 沒有工作流程元資料的伺服器仍能回傳有用的回應事件。

利用 Copilot 調查失敗問題

在 Events 中使用錯誤動作，準備一個聚焦的 GitHub Copilot 請求，而不是複製整個對話內容。

  1. 找出失敗事件，並在分享前檢查其詳細資料中是否含有敏感內容。
  2. 在失敗事件旁選擇修復，以為該失敗準備提示內容。 若有多個失敗，請用搜尋和分類篩選器縮小清單，然後選擇「用 Copilot 解決」。 此舉包含了明顯的失敗。
  3. 在發送前，請先在 GitHub Copilot Chat 中檢閱準備好的提示詞。 檢視任何建議的變更，然後重新執行原始代理程式請求以確認結果。

這些操作不需要 OTLP 收集程式。 準備診斷提示並不能修復代理或重跑失敗的操作。

事件分頁的截圖，包含失敗回應、搜尋與篩選控制、匯出操作，以及在 Copilot Chat 中準備的診斷細節。

儲存診斷事件

儲存事件快照，以便將失敗與後續執行進行比較，或分享針對性的重現。

  1. 在 活動中，透過搜尋欄和分類篩選器縮小列表範圍。
  2. 選擇 複製可見事件 以將篩選事件複製為 JSONL。 或者，選擇 下載可見事件，即可在 VS Code 中開啟匯出檔。
  3. 對於已開啟的匯出檔案，請使用 檔案>另存為，在你控制的位置儲存一份副本，然後再關閉文件。 開啟的匯出檔案是暫時檔案，不是永久下載檔案。

快照包含的是你選擇動作時可見的事件，而不是執行中的代理的未來事件。 它不會儲存代理版本、部署程式碼或建立雲端追蹤歷史。

Caution

事件可以包含提示、回應、工具參數、結果及錯誤細節。 在儲存或分享匯出前，請先審查並遮蔽敏感內容。

開始一場新的對話

選擇 「清除聊天」 以開始新對話，並清除聊天、活動和細節狀態。 先匯出你需要的診斷事件。 刷新同一個連接的代理會保留其檢查狀態，而更換代理則會清除過期狀態。

對於回應，清除聊天 在回應正在串流時會停用。 當回合暫停等待批准或同意時，其仍然可用。 這不是用來停止你的代理程式的一般指令。

不要依賴本機 Inspector 狀態作為持久保存的對話存檔。 伺服器負責對話持久化，這在本地開發與已部署的託管代理之間可能有所不同。 清除 Inspector 並不會刪除已在本機收集或儲存在 Application Insights 中的追蹤。

Inspector 與 tracing 有何不同

Inspector 透過 HTTP 與你的本地伺服器通訊，並串流回應事件。 相容的開發伺服器還提供獨立的診斷串流，用於工作流程細節與來源導覽。 除錯器會以獨立方式附加至你的執行中程序。

這些即時診斷不需要本機 OTLP 收集器。 檢查器的 追蹤 標籤會開啟獨立的追蹤檢視器。 它不會將協定事件轉換成儲存的 OpenTelemetry span。

若要收集 span 以便後續分析，請設定局部追蹤。 對於已部署的代理程式，請使用 代管代理程式追蹤記錄。

在本地測試後，部署代管代理程式。 要另外測試，因為它的身份、環境和網路存取都與你本地的程序不同。

Troubleshooting

Issue 要檢查的事項
Inspector 無法連線。 檢查代理終端機是否有啟動錯誤。 確認解譯器、相依關係和 HTTP 埠，然後重新連線到伺服器回報的埠口。 開啟 Inspector 並不會啟動此程序。
請求成功，但未命中中斷點。 確認除錯器是否連接到處理該要求的處理程序，且使用正確的來源目錄。 關於 Python，請參見除錯和疑難排解。
缺少圖形或來源導覽。 確認伺服器和工作流程是否提供開發診斷和來源位置。 通用回應檢查無法提供這些功能。 LangGraph 的工作流程在沒有工作流程視覺化的情況下，可以在 Playground 中運作。
工具結果缺失。 請檢查事件中是否有失敗紀錄和待核准項目。 確認該請求需要工具，且該工具已設定且可存取。
缺少代幣或推理細節。 檢查模型和伺服器發出什麼內容。 檢查器只能顯示其提供的資訊。
遠端影像被封鎖。 只有在你想讓 Inspector 從遠端主機擷取它們時，才選擇 載入遠端映像檔。 這個顯示許可不是工具的核准。 不支援的網址或內容仍可能無法載入。 缺少圖片不一定代表代理程式請求失敗。
回應串流被中斷。 檢視部分回應與失敗細節。 如果需要，請重新連線，並在重試前查看待核准項目。 重試可以重複即時工具動作。
Inspector 有事件，但追蹤視窗是空的。 協定事件與 OTLP 跨度不同。 設定插樁並啟動收集器。

相關內容

  • 上次更新時間：