如果您開發 AI 代理，可以使用 OpenTelemetry 檢測應用程式，觀察代理如何推論、呼叫工具及回應提示。本指南說明如何使用 LangGraph 和 Agent Development Kit (ADK) 等框架擷取代理遙測資料，以及如何在 Cloud Trace 分析多模態提示和回覆。
檢測代理以瞭解其行為
開發或管理生成式 AI 應用程式時，遙測資料會擷取自主代理的推論步驟、工具呼叫和外部互動。這項資料的用途如下：
- 瞭解非確定性行為：由於代理的推論過程不具確定性，因此遙測是唯一可靠的方法，可用來檢查代理做出的決策和選取的工具。
- 疑難排解及診斷錯誤：追蹤記錄可協助您找出失敗的 API 要求、無限執行迴圈，以及分散式 Agentic Workflows 中的延遲瓶頸。
- 支援管理及驗證流量：遙測功能可讓您以視覺化方式呈現通訊流程 (例如應用程式拓撲)，確認代理只會與授權代理、MCP 伺服器和外部端點通訊。
- 評估輸出內容品質和成本：收集提示、回覆和詞元用量，有助於評估模型準確度、偵測幻覺，以及最佳化資源消耗。
如何檢測生成式 AI 應用程式
檢測應用程式時，您需要產生遙測資料，並將其傳送至可儲存、查詢及分析資料的目的地。舉例來說，當檢測機制將遙測資料傳送至 Google Cloud 專案時，您可以使用 Google Cloud Observability 查看及分析資料。
如果生成式 AI 應用程式寫入的 Span 符合 Span 和事件的語意慣例，Cloud Trace 會自動從中擷取事件。如要瞭解這些慣例，請參閱下列文件：
Cloud Trace 也能顯示多模態提示和回覆。在這種情況下，提示和回覆不會附加到追蹤記錄資料。而是儲存在 Cloud Storage bucket。如要進一步瞭解這項設定，請參閱「收集及查看多模態提示和回覆」。
最佳做法
建議您使用 OpenTelemetry 檢測應用程式，這是一項開放原始碼專案，提供統一的應用程式檢測架構。本文列出的檢測範例使用 OpenTelemetry。
我們也建議您將提示和回覆儲存在 Cloud Storage bucket，而非記錄項目中：
您可以精細控管 Cloud Storage bucket 中的內容。例如，您可以刪除儲存在 bucket 中的個別對話。但無法刪除個別記錄項目。
Cloud Storage bucket 可儲存的物件大小，遠大於記錄項目的大小上限 (256 KiB)。如果收到的資料超過記錄項目大小上限，Cloud Logging 會傳回
INVALID_ARGUMENT錯誤並捨棄資料。如果指令順利完成，但個別欄位超過大小限制，Cloud Logging 會截斷該資料。
如要瞭解 OpenTelemetry，請參閱「什麼是 OpenTelemetry？」一文。
檢測範例
如要開始檢測代理程式，請參閱下列範例應用程式和指南：
收集及查看多模態提示和回覆 說明如何設定 LangGraph ReAct 代理或使用 ADK 建構的生成式 AI 代理，以收集多模態提示和回覆。此外，本文也會說明如何執行下列操作：
- 將提示和回覆儲存在 Cloud Storage bucket。
- 在「Trace Explorer」頁面查看提示詞和回覆。
- 使用 BigQuery 分析提示和回覆。
- 使用 Vertex AI SDK for Python 評估提示和回覆。
使用 OpenTelemetry 檢測 LangGraph ReAct 代理說明如何使用 OpenTelemetry 檢測採用 LangChain 或 LangGraph 框架的生成式 AI 應用程式。此外，您也可以透過連結下載及執行範例應用程式。範例應用程式會收集文字提示詞和回覆。
使用 OpenTelemetry 檢測 ADK 應用程式：說明如何啟用內建檢測功能，收集代理程式重要動作的遙測資料。遙測資料包括文字提示詞和代理回覆。此外，您也可以透過連結下載及執行範例應用程式。範例應用程式會收集文字提示詞和回覆。
使用 Trace 調查 MCP 呼叫：說明如何設定應用程式，將追蹤記錄相關資訊傳遞至遠端 Google Cloud MCP 伺服器，讓這些伺服器將 span 附加至追蹤記錄。