本文說明如何為使用 Agent Development Kit (ADK) 框架建構的 AI 代理進行檢測。ADK 架構包含 OpenTelemetry 檢測功能，可從代理程式的主要動作收集遙測資料。啟用內建檢測功能後，該功能會將文字提示和代理程式回覆等資訊傳送至您的 Google Cloud 專案。本文將說明必要變更，並提供範例應用程式的連結。
使用 ADK 的應用程式也可以收集多模態提示和回覆。本文說明如何收集文字提示詞和回覆。如要收集多模態資料，則必須進行額外設定。詳情請參閱「收集及查看多模態提示和回覆」。
ADK 提供的預設可觀測性可能不足以滿足應用程式的使用情境。您可以使用 OpenTelemetry 新增其他檢測程式庫，從應用程式的其他部分擷取遙測資料，也可以使用自訂檢測擷取應用程式專屬資料，以取得更精細的觀測能力。舉例來說，您可以在應用程式中編寫檢測程式碼，以執行下列操作：
- 追蹤代理程式叫用工具的資源用量。
- 追蹤應用程式專屬的驗證失敗、業務規則違規或自訂錯誤復原機制。
- 根據領域專屬條件追蹤專員回覆的品質分數。
檢測生成式 AI 應用程式，收集遙測資料
如要為 AI 代理程式進行檢測，以收集記錄、指標和追蹤記錄資料，請執行下列操作：
本節的其餘部分會說明上述步驟。
安裝 OpenTelemetry 套件
新增下列 OpenTelemetry 檢測和匯出工具套件：
pip install 'google-adk>=1.17.0' \
'opentelemetry-instrumentation-google-genai>=0.4b0' \
'opentelemetry-instrumentation-sqlite3' \
'opentelemetry-exporter-gcp-logging' \
'opentelemetry-exporter-gcp-monitoring' \
'opentelemetry-exporter-otlp-proto-grpc' \
'opentelemetry-instrumentation-vertexai>=2.0b0'
系統會使用 Cloud Logging API 或 Cloud Monitoring API，將記錄檔和指標資料傳送至您的 Google Cloud 專案。opentelemetry-exporter-gcp-logging 和 opentelemetry-exporter-gcp-monitoring 程式庫會叫用這些 API 中的端點。
追蹤記錄資料會使用 Telemetry (OTLP) API 傳送至 Google Cloud ，該 API 會實作 OpenTelemetry Line Protocol。opentelemetry-exporter-otlp-proto-grpc 程式庫會叫用遙測 (OTLP) API 端點。
您的追蹤記錄資料會以與 OpenTelemetry Line Protocol 定義的 .proto 檔案大致一致的格式儲存。不過，欄位可能會先從 OpenTelemetry 專屬資料類型轉換為 JSON 資料類型，再進行儲存。如要進一步瞭解儲存格式，請參閱「追蹤資料的結構定義」。
設定 ADK 環境
ADK 架構 1.17.0 以上版本內建支援 OpenTelemetry，並可將 OpenTelemetry 遙測資料傳送至Google Cloud Observability。如要啟用這項功能，請設定 ADK 環境：
如果使用
adk web指令執行應用程式，請加入--otel_to_cloud旗標。在
opentelemetry.env檔案中，設定下列環境變數：OTEL_SERVICE_NAME='adk-sql-agent' OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'設定 OpenTelemetry，使用生成式 AI 的最新語意慣例。
OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'設定 OpenTelemetry，將訊息附加為事件。
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'如要進一步瞭解允許的列舉值，請參閱
genai/types.py。建議您也在
opentelemetry.env檔案中加入下列環境變數：ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'這個環境變數具有以下功用：
- 防止 ADK 檢測功能附加超出屬性大小限制的範圍屬性。
- 防止個人識別資訊 (PII) 以屬性形式附加至跨度。
您可能需要設定其他環境變數。舉例來說，如果您要部署至 Gemini Enterprise Agent Platform，也請設定下列環境變數：
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
下載並執行範例應用程式
這個程式碼範例會實作使用 ADK 建構的生成式 AI 代理。代理程式會使用 OpenTelemetry 進行檢測，並設定為將指標、追蹤記錄和記錄檔傳送至您的 Google Cloud 專案。傳送至專案的遙測資料包括生成式 AI 提示和回覆。
ADK 代理程式角色
生成式 AI 代理程式定義為 SQL 專家，可完整存取暫時性 SQLite 資料庫。這個代理是使用 Agent Development Kit 建構而成，並透過 SQLDatabaseToolkit 存取資料庫。資料庫一開始是空的。
事前準備
- 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。
-
安裝 Google Cloud CLI。
-
若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
-
執行下列指令，初始化 gcloud CLI：
gcloud init -
選取或建立專案所需的角色
- 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
-
建立專案：如要建立專案，您需要「專案建立者」角色 (
roles/resourcemanager.projectCreator)，其中包含resourcemanager.projects.create權限。瞭解如何授予角色。
-
建立 Google Cloud 專案：
gcloud projects create PROJECT_ID
將
PROJECT_ID替換為您要建立的 Google Cloud 專案名稱。 -
選取您建立的 Google Cloud 專案：
gcloud config set project PROJECT_ID
將
PROJECT_ID替換為 Google Cloud 專案名稱。
啟用 Vertex AI、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API：
啟用 API 時所需的角色
如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，其中包含serviceusage.services.enable權限。瞭解如何授予角色。gcloud services enable aiplatform.googleapis.com
telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com -
安裝 Google Cloud CLI。
-
若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。
-
執行下列指令，初始化 gcloud CLI：
gcloud init -
選取或建立專案所需的角色
- 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
-
建立專案：如要建立專案，您需要「專案建立者」角色 (
roles/resourcemanager.projectCreator)，其中包含resourcemanager.projects.create權限。瞭解如何授予角色。
-
建立 Google Cloud 專案：
gcloud projects create PROJECT_ID
將
PROJECT_ID替換為您要建立的 Google Cloud 專案名稱。 -
選取您建立的 Google Cloud 專案：
gcloud config set project PROJECT_ID
將
PROJECT_ID替換為 Google Cloud 專案名稱。
啟用 Vertex AI、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API：
啟用 API 時所需的角色
如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，其中包含serviceusage.services.enable權限。瞭解如何授予角色。gcloud services enable aiplatform.googleapis.com
telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com 如果您在 Cloud Shell、 Google Cloud資源或本機開發環境中執行範例，則本節列出的權限就足夠。對於正式版應用程式，通常是服務帳戶提供寫入記錄、指標和追蹤資料的憑證。
如要取得範例應用程式寫入記錄、指標和追蹤資料所需的權限，請要求管理員授予您專案的下列 IAM 角色：
- Cloud 遙測資料追蹤記錄寫入者 (
roles/telemetry.tracesWriter) - 記錄寫入者 (
roles/logging.logWriter) - Monitoring 指標寫入者 (
roles/monitoring.metricWriter) - Vertex AI 使用者 (
roles/aiplatform.user)
- Cloud 遙測資料追蹤記錄寫入者 (
啟動應用程式
如要啟動範例應用程式，請按照下列步驟操作：
在 Cloud Shell 中發出下列指令：
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git前往範例目錄：
cd opentelemetry-operations-python/samples/adk-sql-agent建立虛擬環境並執行範例：
python -m venv venv/ source venv/bin/activate pip install -r requirements.txt env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud應用程式會顯示類似以下的訊息：
Appplication startup complete Uvicorn running on http://0.0.0.0:8080如要與代理程式互動，請選取上一個步驟輸出內容中顯示的網址。
展開「選取服務專員」，然後從服務專員清單中選取
sql_agent。
與代理互動
如要與代理互動，請向代理提問或下達指令。舉例來說，你可以問：
What can you do for me ?
同樣地，由於 sql_agent 的角色是 SQL 專家，您可以要求它為應用程式建立資料表，並編寫查詢來操作所建立的資料表。代理程式只能建立由 .db 檔案支援的暫時性資料庫，該檔案是在執行應用程式的機器上建立。
以下說明 sql_agent 與使用者之間的互動範例：
生成式 AI 代理執行的動作並非確定性，因此即使輸入相同的提示，回覆也可能有所不同。
結束應用程式
如要結束應用程式，請在用於啟動應用程式的殼層中輸入 Ctrl-C。
查看追蹤記錄、指標和記錄檔
本節說明如何查看生成式 AI 事件。
事前準備
如要取得查看記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- 記錄檢視器 (
roles/logging.viewer) - Monitoring 檢視者 (
roles/monitoring.viewer) - Cloud Trace 使用者 (
roles/cloudtrace.user)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
查看遙測資料
如要查看應用程式建立的生成式 AI 事件，請使用「Trace Explorer」頁面：
-
前往 Google Cloud 控制台的
「Trace Explorer」頁面：前往「Trace explorer」(Trace 探索工具)
您也可以透過搜尋列找到這個頁面。
在工具列中，依序選取 新增篩選器、範圍名稱，然後選取
call_llm。下圖顯示篩選資料後的「Trace Explorer」頁面：
如果您從未使用過 Cloud Trace，Google Cloud Observability 就需要建立資料庫來儲存追蹤記錄資料。建立資料庫可能需要幾分鐘，這段期間無法查看任何追蹤資料。
如要探索時距和記錄檔資料，請在「Spans」(時距) 表格中選取時距。
「詳細資料」頁面隨即開啟。這個頁面會顯示相關聯的追蹤記錄及其範圍。頁面上的表格會顯示所選時間範圍的詳細資訊。這類資訊包括：
「輸入/輸出」分頁會顯示生成式 AI 代理的事件。如要進一步瞭解這些事件，請參閱「查看生成式 AI 事件」一文。
下圖顯示追蹤記錄，其中一個時距的名稱為
call_llm。該範圍會叫用為這個代理提供支援的 LLM (大型語言模型)。在本範例中，這是指 Gemini。 Gemini 範圍包含生成式 AI 事件：
「記錄和事件」分頁會列出與時距相關聯的記錄項目和事件。如要在 Logs Explorer 中查看記錄資料，請在這個分頁的工具列中選取「查看記錄」。
記錄資料包括
sql_agent的回應。舉例來說，在範例執行中，JSON 酬載包含下列內容：{ "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp", "jsonPayload": { "content": { "parts": [ 0: { "text": "Now I can create the table." } 1: {1} ], "role": "model" } }, ... }
這個範例已完成儀表化，可將指標資料傳送至您的 Google Cloud 專案，但不會產生任何指標。