Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 OpenTelemetry 檢測 ADK 應用程式

本文說明如何檢測使用 Agent Development Kit (ADK) 架構建構的 AI 代理。ADK 架構包含 OpenTelemetry 檢測，可從代理的重要動作收集遙測資料。啟用內建檢測功能後，該功能會將文字提示詞和代理回覆等資訊傳送至 Google Cloud 專案。本文將說明必要變更，並提供範例應用程式連結。

使用 ADK 的應用程式也可以收集多模態提示和回覆。本文說明如何收集文字提示詞和回覆。如要收集多模態資料，則須進行額外設定。詳情請參閱「收集及查看多模態提示和回覆」。

ADK 提供的預設觀測能力可能不足以滿足應用程式的用途。您可以使用 OpenTelemetry 新增其他檢測程式庫，從應用程式的其他部分擷取遙測資料，也可以使用自訂檢測功能擷取應用程式專屬資料，取得更精細的觀測能力。舉例來說，您可以在應用程式中編寫檢測程式碼，以便：

追蹤代理叫用工具的資源消耗量。
追蹤應用程式專屬的驗證失敗、違反業務規則或自訂錯誤復原機制。
根據特定領域的條件，追蹤代理回覆的品質分數。

檢測生成式 AI 應用程式，收集遙測資料

如要檢測 AI 代理，收集記錄、指標和追蹤記錄資料，請按照下列步驟操作：

安裝 OpenTelemetry 套件。
設定 ADK 環境。

本節其餘部分將說明上述步驟。

安裝 OpenTelemetry 套件

新增下列 OpenTelemetry 檢測和匯出工具套件：

uv add 'google-adk>=2.12.0' \
  'opentelemetry-instrumentation-google-genai>=0.7b1' \
  'opentelemetry-instrumentation-sqlite3>=0.63b1' \
  'opentelemetry-exporter-otlp-proto-grpc>=1.42.1' \
  'opentelemetry-exporter-otlp-proto-http>=1.42.1' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

記錄、指標和追蹤記錄資料會透過Telemetry (OTLP) API 傳送至 Google Cloud ，該 API 會實作 OpenTelemetry Protocol。opentelemetry-exporter-otlp-proto-grpc 程式庫會叫用 Telemetry (OTLP) API 端點。

追蹤記錄資料的儲存格式，通常與 OpenTelemetry 通訊協定定義的 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'
```
注意： 請勿將這個變數的值設為 true。如果使用最新的語意慣例，將這個變數的值設為 true 會導致設定無效。因此不會收集記錄和追蹤資料。
如要進一步瞭解允許的列舉值，請參閱 genai/types.py。
建議您一併將下列環境變數新增至 opentelemetry.env 檔案：
```
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
```
這個環境變數的作用如下：
- 防止 ADK 檢測附加超過屬性大小限制的 Span 屬性。
- 防止個人識別資訊 (PII) 做為屬性附加至 Span。
您可能需要設定其他環境變數。舉例來說，如果您部署至 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

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時不需要特定 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 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用 Vertex AI、Service Usage、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API (如有尚未啟用的 API)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時不需要特定 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 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用 Vertex AI、Service Usage、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API (如有尚未啟用的 API)：

啟用 API 所需的角色

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

如要取得讓範例應用程式寫入記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)
- 記錄檔寫入者 (roles/logging.logWriter)
- Monitoring 指標寫入者 (roles/monitoring.metricWriter)
- Vertex AI 使用者 (roles/aiplatform.user)
如果您在 Cloud Shell、 Google Cloud 資源或本機開發環境中執行範例，這些權限就足夠。

重要事項：正式版應用程式通常會依賴服務帳戶，提供寫入記錄、指標和追蹤資料所需的憑證。在這些情況下，請將先前的角色授予服務帳戶。
請務必指定配額專案。Vertex AI API (aiplatform.googleapis.com) 必須指定配額專案。詳情請參閱「設定配額專案」。例如，下列指令可設定配額專案。
```
gcloud config set billing/quota_project PROJECT_ID
```

啟動應用程式

如要啟動範例應用程式，請按照下列步驟操作：

在 Cloud Shell 複製存放區：

git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git

前往範例目錄：
```
cd opentelemetry-samples/python/adk-sql-agent
```
範例包含一個 .env 檔案，可設定兩個環境變數。其中一個變數控制 SDK 使用的端點。另一個變數則設定位置。

如要改用其他模型，請編輯 main.py。請確認所選模型支援 .env 檔案中指定的位置。如要瞭解模型，請參閱「Google 模型」。

建立虛擬環境並執行範例：

uv run --env-file opentelemetry.env adk web --otel_to_cloud

應用程式會顯示類似下列的訊息：

Application startup complete
Uvicorn running on http://127.0.0.1:8080

如要與代理互動，請選取上一個步驟輸出內容中顯示的網址。
展開「Select an app」(選取應用程式)，然後從代理清單中選取「sql_agent」。
注意：
這個應用程式需要跨源資源共享 (CORS)。如果輸入提示詞，但 CORS 遭到封鎖，應用程式會顯示 Failed to create session 訊息，指令列則會顯示指令遭拒，POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden。
如要啟用 CORS，請在執行範例的指令後方附加下列內容：
```
--allow_origins="regex:.*"
```

與代理互動

如要與代理互動，請提問或下達指令。例如，您可以提出以下問題：

What can you do for me ?

同樣地，由於 sql_agent 具備 SQL 專家的角色，您可以要求它為應用程式建立資料表，並編寫查詢來操作建立的資料表。代理程式只能建立由 .db 檔案支援的臨時資料庫，該檔案是在執行應用程式的機器上建立。

以下是 sql_agent 與使用者互動的範例：

顯示與 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 探索工具)

您也可以透過搜尋列找到這個頁面。
在工具列中，依序選取「Add filter」(新增篩選器)、「Span name」(Span 名稱) 和「call_llm」。

下圖顯示篩選資料後的「Trace Explorer」頁面：

如果您從未使用過 Cloud Trace，Google Cloud Observability 必須建立資料庫來儲存追蹤記錄資料。建立資料庫可能需要幾分鐘，這段期間無法查看追蹤記錄資料。
如要探索 Span 和記錄資料，請在「Spans」(Span) 表格中選取 Span。

「Details」(詳細資料) 頁面隨即開啟。這個頁面會顯示相關聯的追蹤記錄及其 span。頁面上的表格會顯示所選時距的詳細資訊。這類資訊包括：
- 「Inputs/Outputs」(輸入/輸出) 分頁會顯示生成式 AI 代理的事件。如要進一步瞭解這些事件，請參閱「查看生成式 AI 事件」。
  
  以下螢幕截圖顯示一項追蹤記錄，其中一個 span 的名稱為 call_llm。該 Span 會叫用這個代理使用的 LLM (大型語言模型)。在這個範例中，模型為 Gemini。Gemini 跨距包含生成式 AI 事件：
- 「Logs & Events」(記錄和事件) 分頁會列出與 Span 相關聯的記錄項目和事件。如要在 Logs Explorer 中查看記錄資料，請選取這個分頁工具列中的「View logs」(查看記錄)。
  
  記錄資料包含 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"
    }
  },
  ...
}
```

使用 OpenTelemetry 檢測 ADK 應用程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

檢測生成式 AI 應用程式，收集遙測資料

安裝 OpenTelemetry 套件

設定 ADK 環境

下載並執行範例應用程式

ADK 代理角色

事前準備

啟動應用程式

與代理互動

結束應用程式

查看追蹤記錄、指標和記錄

事前準備

查看遙測資料

使用 OpenTelemetry 檢測 ADK 應用程式