代理追蹤概述

重要

本文中標示為預覽的項目目前仍在預覽中。 此預覽版未簽訂服務等級協議,Microsoft 不建議用於生產工作負載。 某些功能可能不被支援或功能受限。 欲了解更多資訊,請參閱Microsoft Azure預覽補充使用條款。

註

追蹤通常適用於提示和裝載的 Agent。 工作流程和外部代理目前為預覽版。

Microsoft Foundry 提供一個可觀察性平台,用於監控與追蹤 AI 代理。 它能捕捉代理執行過程中的關鍵細節,如輸入、輸出、工具使用、重試、延遲及成本。 了解代理執行背後的原因對於故障排除和除錯非常重要。 然而,理解複雜代理人存在多項挑戰:

  • 生成回應可能需要大量步驟,難以全部掌握。
  • 步驟順序可能會因使用者輸入而有所不同。
  • 每個階段的輸入與輸出可能較長,值得更詳細的檢視。
  • Agent 執行階段的每個步驟也可能涉及巢狀結構。 例如,代理可能會呼叫一個工具,該工具使用另一個程序,進而又呼叫另一個工具。 如果你發現頂層代理執行輸出異常或錯誤,可能很難確定問題是在執行的哪個階段被引入的。

追蹤記錄可讓你查看特定代理程式執行過程中所涉及各個基元的輸入與輸出,並依其被呼叫的順序顯示,因此能協助你輕鬆理解並除錯 AI 代理程式的行為。

先決條件

要使用端對端追蹤,你需要:

註

追蹤功能會將遙測資料儲存在 Azure 監視器 Application Insights 中,並可能依據資料量和保留設定產生費用。 價格詳情請參見 Application Insights 定價。

Foundry 中的 OpenTelemetry

OpenTelemetry(OTel)提供標準化的協定來收集與路由遙測資料。 Foundry 使用 OpenTelemetry 語義慣例,以確保在支援的工具和整合中,追蹤保持一致。

追蹤關鍵概念

以下關鍵概念貫穿本文:

關鍵概念 描述
痕跡 追蹤透過記錄事件與狀態變更(函式呼叫、值、系統事件)來捕捉請求或工作流程在應用程式中的歷程。 參見 OpenTelemetry Traces。
跨度 跨度是跡線的構成單元,代表跡線內的單一操作。 每個區間都捕捉開始與結束時間、屬性,並可巢狀顯示階層關係,讓您能看到完整的呼叫堆疊與操作序列。
屬性 屬性是附加於痕跡與範圍的鍵值對,提供上下文元資料,如函數參數、回傳值或自訂註解。 這些資料豐富了痕跡資料,使其更具資訊性且有助於分析。
語意慣例 OpenTelemetry 定義語意慣例,標準化追蹤資料屬性的名稱與格式,使跨工具與平台的解讀與分析更為簡便。 欲了解更多,請參閱 OpenTelemetry GenAI 語意慣例。
追蹤匯出工具 追蹤匯出器會將追蹤資料傳送至後端系統進行儲存與分析。 在 Foundry 中,traces 會儲存在 Azure 監視器 Application Insights。 欲了解如何啟用及查看追蹤,請參閱 如何在 Microsoft Foundry 設定追蹤。

Foundry 中追蹤的運作方式

追蹤幫助你回答像是「這個回應從哪裡來的?」以及「哪一步引發錯誤或延遲尖峰?」這類問題。

在高層次而言,追蹤系統能夠記錄:

  • 使用者輸入與代理輸出。
  • 工具使用,包括工具呼叫與結果。
  • 代幣消費。
  • 時間訊號,例如持續時間和延遲。

啟用追蹤功能後,可以在 Foundry 入口網站和 Azure 監視器 應用程式洞察中檢查追蹤。 關於逐步設定與檢視選項,請參閱 如何在 Microsoft Foundry 設定追蹤。

透過多代理可觀測性擴充 OpenTelemetry

Microsoft 與 Cisco Outshift 合作,為多代理系統貢獻語意慣例。 這些慣例建立在 OpenTelemetry GenAI 代理與框架範圍 ,以及 W3C 追蹤上下文之上。 它們標準化多代理工作流程的遙測,包括代理調用、工作流程編排、規劃、模型呼叫及工具執行。

重要

OpenTelemetry GenAI 語意慣例目前處於開發階段,未來版本可能會有所變動。

這些增強整合於:

  • 鑄造廠
  • Microsoft 代理框架
  • LangChain
  • LangGraph
  • OpenAI 代理程式 SDK

欲了解更多資訊,請參閱追蹤整合。

下表說明了多代理可觀察性的常見 OpenTelemetry GenAI 慣例。 範圍 (Span) 用於擷取作業,子範圍顯示巢狀工作,屬性則提供中繼資料。 圖中所示的父範圍為常見範例;實際的巢狀結構取決於所分析的 Agent 或框架。

類型 背景/父級範圍 名稱/屬性/事件 目的
跨度 — invoke_agent 透過遠端服務或同一程序呼叫代理。
子範圍 invoke_agent invoke_agent 透過父子範圍的關係,追蹤對另一個 Agent 的呼叫。
子範圍 invoke_agent plan 記錄代理的規劃或任務分解階段。
跨度 — invoke_workflow 呼叫包含代理或其他生成式 AI 操作的協調工作流程。
子範圍 invoke_agent 或 invoke_workflow execute_tool 記錄工具的執行作業。
子範圍 invoke_agent 或 invoke_workflow create_memory、search_memory、update_memory、upsert_memory 或 delete_memory 記錄記憶體操作。
屬性 invoke_agent gen_ai.tool.definitions 記錄代理人或模型可用工具的定義。
屬性 execute_tool gen_ai.tool.call.arguments 記錄傳遞給工具呼叫的參數。
屬性 execute_tool gen_ai.tool.call.result 記錄成功呼叫工具後返回的結果。

最佳實務

  • 使用一致的跨度屬性:在所有代理與工具中套用相同的屬性名稱與格式,以簡化查詢與分析。
  • 關聯評估執行識別碼:將追蹤資料與評估執行連結,以統一視圖分析品質與效能。
  • 遮蔽敏感內容:在提示詞、工具引數和 Span 屬性觸達遙測之前,請移除或遮罩其中的個人資料、機密和認證。

安全與隱私

追蹤可以捕捉敏感資訊,例如使用者輸入、模型輸出,以及工具的參數與結果。 運用以下做法來降低風險:

  • 不要在提示、工具參數或屬性間儲存秘密、憑證或令牌。
  • 在個人資料及其他敏感內容出現在遙測數據中之前,先遮蔽或減少它們。
  • 將追蹤資料視為生產遙測,並套用與日誌和指標相同的存取控制與保留政策。

欲了解如何將敏感內容導向專用資料表並限制存取,請參閱「 限制敏感內容存取」。

故障排除

如果在 Foundry 入口網站或 Application Insights 中沒有出現追蹤:

  • 確認你的 Foundry 專案是否連結到 Application Insights 資源。
  • 檢查你的帳號是否有查詢遙測資料所需的權限。
  • 確保您的代理人代碼包含必要的儀器設備。 關於框架特定的設定,請參見 追蹤整合。

提示

所有支援 Foundry 的地區皆可追蹤。 追蹤資料的保留和抽樣會根據您的 Application Insights 設定。 詳情請參閱 Azure 監視器 日誌中的 資料保留與封存。