在 Microsoft Foundry 中設定追蹤功能

使用追蹤來除錯你的 AI 代理程式，並在生產環境中監控其運作情況。 追蹤能捕捉詳細的遙測數據——包括延遲、例外、提示內容及檢索操作——讓你能更快識別並修復問題。

建議的起點是 伺服器端追蹤。 當你將 Application Insights 資源連接到專案後，Foundry 會自動啟用它。 無需更改程式碼，啟用後幾分鐘內即可取得追蹤。 伺服器端追蹤適用於任何託管在 Foundry 中的代理程式。 當您需要檢視自己的應用程式程式碼時 (例如，追蹤圍繞代理人呼叫的自訂邏輯)，您可以將用戶端檢測新增為第二個步驟。

Microsoft Foundry 技能能協助選擇伺服器端或用戶端追蹤，並排解缺少的遙測資料。

先決條件

• Foundry 專案。
• 一個 Azure 監視器 Application Insights 資源用來儲存追蹤（建立新追蹤或連接現有追蹤）。
• 存取與您的專案相關的應用程式洞察資源。
• 連線的 Application Insights 資源上的 Log Analytics Reader 角色 (查詢遙測所需)。 如果底層的 Log Analytics 資料表受到保護，也要指派特殊權限監控資料讀取者角色。

將應用洞察連結到您的 Foundry 專案

Foundry 透過使用 OpenTelemetry 語意慣例，將痕跡儲存在 Application Insights。

1. 登入 Microsoft Foundry。 確定 新鑄造廠 的開關是開啟的。 以下步驟適用於 Foundry（新）。

   

2. 打開你的 Foundry 專案。

3. 在左側導覽中，選擇 「代理人」。

4. 在最上方選擇 「Traces」。

5. 在右側選擇 「連接 」以建立或連接應用程式洞察資源。

   

• 要連接現有資源，先選擇該資源，然後選擇 連接。
• 要建立新資源，選擇 「建立新」，然後完成精靈。

連線成功時會顯示確認訊息。

請使用專案詳細的連線路徑

如果你看不到訊息列或連接按鈕，請用這個替代方式啟用 Azure 監視器 Application Insights。

1. 在右上角的導覽中選擇「管理」，然後選擇「Project details」。
2. 選擇 「已連接資源 」標籤，然後選擇 「新增連線」。
3. 在 選擇連接中，選擇 「應用程式洞察」。

關於 Entra 認證的追蹤擷取，請參見「配置 Microsoft Entra 認證以進行 Foundry Agent 追蹤擷取（預覽）」。

連結資源後，專案即可使用追蹤。

配置 AI 智能代理

選擇與你建立及經營經紀人方式相符的方法。

Foundry 入口網站中的伺服器端追蹤

先從伺服器端的追蹤開始。 Foundry 會記錄常見代理和工作流程的痕跡，且不會更改你的程式碼。

• Foundry 會自動在 Foundry 入口網站中記錄提示詞 Agent、主機 Agent 和工作流程的伺服器端追蹤。 在您的 Foundry 專案啟用追蹤功能後，您可以直接取得過去 90 天的現成追蹤資料。
• Foundry 也支援與頂尖代理框架 的輕鬆整合 。

使用 Microsoft Foundry SDK 進行用戶端追蹤

請依照以下步驟安裝 OpenTelemetry 和 Azure SDK 追蹤外掛：

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

using Azure.AI.Projects;
using Azure.Identity;

AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

var projectEndpoint = Environment.GetEnvironmentVariable(
   "FOUNDRY_PROJECT_ENDPOINT");
AIProjectClient projectClient = new(
   endpoint: new Uri(projectEndpoint!),
   tokenProvider: new DefaultAzureCredential());

執行代理後，你可以在 Foundry 入口網站查看並分析追蹤。

關於端對端的 Python 和 .NET 範例，能將追蹤匯出到 Azure 監視器 或主控台，請參見「配置客戶端追蹤」。

使用 Microsoft Foundry Toolkit for Visual Studio Code 擴充功能進行本機追蹤

Microsoft Foundry Visual Studio Code 擴充套件允許你在 VS Code 中使用本地相容的 OTLP 收集器進行追蹤。 這種方法非常適合開發與除錯。

該工具包接收來自支援的 SDK 與框架檢測的 span，包括 Foundry Projects、OpenAI、Anthropic 及 LangChain。 本地收集不需要 Application Insights，但模型與工具呼叫仍可使用雲端服務並產生費用。

關於收集器設定、SDK 專屬範例及託管代理追蹤查詢，請參見 Foundry 工具包中的追蹤。 對於即時的本地請求、工具事件及中斷點，而非已儲存的 spans，請使用 Agent Inspector。

查看與分析痕跡

在 Foundry 平台查看追蹤記錄

在您的 Foundry 專案中，移至您的代理程式或工作流程中的 [追蹤] 索引標籤。 你可以搜尋、篩選或排序過去 90 天內已輸入的痕跡。

選擇一條路徑來逐步穿越每個區間，找出問題，並觀察你的應用程式如何回應。 這個過程有助於你除錯並找出應用程式中的問題。

在 Azure 監視器 中查看追蹤

你的追蹤會傳送到 Azure 監視器 Application Insights，你可以在那裡查看。

欲了解更多如何傳送追蹤至Azure 監視器及建立Azure 監視器資源的資訊，請參閱 Azure 監視器 OpenTelemetry documentation。

查看對話結果

對話是使用者與代理之間端到端對話歷史的持續上下文。 在 Foundry 入口網站中，您可以在 [追蹤] 頁面上檢視現成可用代理程式的 [交談] 結果和追蹤。

可依回應 ID 或對應此對話的追蹤 ID 搜尋。 然後選取一個 對話 ID 以檢視：

• 對話紀錄詳情
• 執行中的回應資訊與標記
• 有序動作、執行步驟與工具呼叫
• 使用者與代理人之間的輸入與輸出

驗證追蹤有效

1. 確認你的專案是否與 Application Insights 有關聯。 如有需要，請依照將 Application Insights 連接到您的 Foundry 專案中的步驟進行操作。

2. 至少執行一次你的代理或工作流程（例如使用入口網站或應用程式）。

3. 在你的 Foundry 專案中，打開 Traces 檢視並確認有新的 trace 出現。

   當追蹤正常運作時，你會看到最近追蹤的清單，並附有時間戳記、持續時間和狀態指示器。 選取追蹤以檢視其範圍詳細資料。

如果沒有看到新的痕跡，請等幾分鐘重新整理，然後再進入 故障排除。

安全與隱私

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

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

更多指引請參閱 安全與隱私。

資料保留與成本

Foundry 會將追蹤資料儲存在與您的專案相關的應用程式洞察資源中。 資料保留與計費則跟隨您的 Application Insights 與 Log Analytics 設定。

故障排除

相關內容

既然你已經設定好追蹤，請探索這些資源，深化你的理解並擴展你的可觀察能力：

• 代理追蹤概述
• 追蹤整合
• 使用 Agent Monitoring Dashboard 監控 AI 客服人員
• 生成式人工智慧中的可觀察性