agent-platform-alert-configuration

Agent Platform Alert Configuration

關鍵步驟

1. 安全與確認分級（關鍵）

在代表使用者執行任何命令或撰寫設定之前，你必須根據所請求的操作嚴格遵循以下安全分級：

1. Tier R：唯讀 (check_telemetry.py / gather_agent_info.py)
   • 規則：無需確認。你可以立即執行這些指令碼來檢查遙測狀態或收集 Agent 設定細節。
2. Tier B：計費與資源建立 (create_online_monitor.py / 資源預備)
   • 規則：需要使用者明確確認。這些操作會產生額外的計費費用並建立雲端資源。Agent 必須隨時明確警告使用者關於 Online Monitor（特別提及 LLM 評估）與遙測（Telemetry，特別提及 Cloud Trace/Logging 匯出）這兩者可能產生的額外費用。在繼續進行資源預備或提供設定命令之前，你必須停止並尋求明確授權。

2. 先決條件與相依性

Agent 遙測 (Agent Telemetry)

• 免責聲明：若要讓可靠性、成本、安全性與資安警報正常運作，底層 Agent 必須已完成檢測 (instrumentation) 並能發送 OpenTelemetry (OTel) 指標。如果 Agent 未發送這些指標，警報策略將沒有可供評估的資料串流。

Python 環境

在執行此 Skill 中的任何 Python 指令碼之前，你必須先在環境中安裝所需的相依套件。請先執行以下命令：

pip install -r scripts/requirements.txt

3. 輸入前提與假設

• 嚴格遵循指定的專案：你只能針對使用者在 Prompt 中明確提供的 Google Cloud 專案進行警報設定、查詢遙測或互動。除非使用者明確指示，否則切勿自行假設或使用環境及歷史紀錄中的其他專案。
• 按順序進行檔案轉換：若使用者明確要求先複製檔案再進行修改，你必須按順序執行這些操作（先複製，再修改），而不是直接寫入最終內容。

4. 執行步驟

1. 強制性的先決條件執行協定（按順序）：在產生或撰寫任何設定之前，你必須依序執行以下步驟：

   1. 步驟 1：自動化偵測（強制）：執行 gather_agent_info.py 以自動識別 Agent 執行階段、檢查遙測、指標範圍 (Metric Scopes)、連結的資料集等。此指令碼已涵蓋後續步驟中的大部分手動檢查項。
      • 命令：python3 scripts/gather_agent_info.py --project-id {project_id} --agent-name {agent_name}
      • 備註：若此指令碼失敗、僅傳回部分資料或未產出你所需的所有內容，你必須透過執行步驟 2 所列的手動後備步驟來滿足需求，接著再執行下方步驟 3。若步驟 1 成功並提供所有資訊，請直接跳至步驟 3（既有策略檢查）。
   2. 步驟 2：指標範圍檢查（後備機制）：僅在步驟 1 無法確定指標範圍時執行此步驟。
      • 操作 A（CLI）：執行 gcloud beta monitoring metrics-scopes list projects/{project_id}。若傳回範圍定界專案 (scoping project)，你必須將策略部署至該專案。
      • 操作 B（程式碼掃描）：在 Terraform 設定中搜尋 google_monitoring_monitored_project 資源，以提取範圍定界專案。
      • 操作 C（詢問）：若狀況不明，請詢問使用者：「您是否正在使用跨專案的 Cloud Monitoring Metric Scope？如果是，請問範圍定界專案 (Scoping Project ID) 是什麼？」
   3. 步驟 3：既有策略檢查：避免重複建立。
      • 操作：掃描目標目錄，檢查是否已存在針對相同指標的彙總策略（依 reasoning_engine_id 或 gen_ai_agent_name 分組）。使用 scan_duplicates.py 來驗證。

2. 警報策略類型參考檔案：你必須列出並閱讀 references/ 目錄下檔名以 _alert_policies.md 結尾的檔案，瞭解如何根據類型設定警報策略。除非使用者要求僅產生特定警報策略或類型，否則預設應設定以下所有警報類型。請參考其目錄導覽來尋求需閱讀的參考章節：

   警報類型	參考檔案
   Reliability（可靠性）	reliability_alert_policies.md
   Quality（品質）	quality_alert_policies.md
   Cost（成本）	cost_alert_policies.md
   Safety（安全性）	safety_alert_policies.md
   Security（資安）	security_alert_policies.md

5. 輸出與格式

• 務必為目標 Agent 設定支援的警報策略：
  • 可靠性監控 (Reliability Monitoring)：你必須設定剛好 5 個警報策略：
    1. Latency（延遲）（異常監控）
    2. Error Rate - Fast Burn SLO（錯誤率 - 快速消耗 SLO）（1 小時時間窗口）
    3. Error Rate - Slow Burn SLO（錯誤率 - 慢速消耗 SLO）（3 天時間窗口）
    4. Model Call Error Rate（模型呼叫錯誤率）（基於 SQL 的 Log Analytics 警報）
    5. Tool Call Error Rate（工具呼叫錯誤率）（基於 SQL 的 Log Analytics 警報）
  • 品質監控 (Quality Monitoring)：你必須設定剛好 3 個警報策略（需要 Vertex AI Online Monitors）：
    1. Final Response Quality（最終回應品質）
    2. Tool Use Quality（工具使用品質）
    3. Hallucination（幻覺）
  • 成本監控 (Cost Monitoring)：你必須設定剛好 1 個成本警報策略：
    1. Rapid Token Burn Rate（Token 快速消耗率）（異常監控）
  • 安全性監控 (Safety Monitoring)：你必須設定剛好 1 個安全性警報策略：
    1. High Model Armor Safety Policy Trigger Rate（Model Armor 安全策略高觸發率）（基於 SQL 的 Log Analytics 警報）
  • 資安監控 (Security Monitoring)：你必須設定剛好 1 個資安警報策略：
    1. High IAM Permission Denied Trigger Rate（IAM 權限拒絕高觸發率）（基於 SQL 的 Log Analytics 警報）
• 僅使用 Terraform：將產生的可觀測性設定僅寫入為 Terraform (.tf) 檔案（例如 alerts.tf、variables.tf）。
  • 你只有在被要求部署警報且環境中沒有有效的 Terraform 安裝時，才需要安裝 Terraform。使用 condition_sql 的 SQL 警報需要 Provider 版本 >= 6.0.0（或支援該特性的 5.x 較新版本）。
  • 如果你未被要求部署警報，則無需安裝 Terraform。
• 動態多資源警報（禁止硬編碼單一資源綁定）：除非使用者明確要求（例如「僅限此 Agent」），否則你不得在警報條件中硬編碼特定 Agent ID 或資源名稱篩選器（例如 {gen_ai_agent_name="{agent_name}"} 或 metric.labels.agent_resource_name="{agent_name}"）。提示詞中僅提及特定 Agent 名稱或 ID 不等於明確要求進行綁定/篩選；你仍必須預設採用動態分組以涵蓋所有 Agent。若要動態涵蓋專案中所有運作中的 Agent：
  • 使用 PromQL 的可靠性指標：務必使用分組聚合 (grouping aggregations)。依 gen_ai_agent_name 分組（例如 by (gen_ai_agent_name)）。除非要求，否則避免篩選單一 ID/名稱。
  • 使用標準閾值篩選器的品質指標：完全省略 agent_resource_name 篩選器。將條件篩選器設定為僅全域針對專案的被監控資源類型 (aiplatform.googleapis.com/OnlineEvaluator) 和指標類型 (aiplatform.googleapis.com/online_evaluator/scores)。
  • 使用 SQL 的下游呼叫：省略針對特定 Agent 名稱的 ENDS_WITH 篩選器。改為擷取 Agent 識別碼（例如 JSON_VALUE(resource.attributes, '$."cloud.resource_id"')），並將其與模型或工具名稱一同加入 GROUP BY 子句中。
• 目錄推斷：優先使用使用者明確提供的路徑（若有）。否則，請將設定檔部署至目標 Terraform 或 SRE 資料夾（例如 monitoring/、ops/、sre/）。使用工具定位專案中警報策略或狀態指標 (state pointers) 所在位置，而不是盲目寫入根目錄。
• 通知管道 (Notification Channels)：預設情況下，未取得使用者輸入前切勿設定任何通知管道。若使用者在 Prompt 中明確提供通知管道，則設定警報使用該管道。若未提供通知管道，你必須在最終回應中明確詢問使用者是否需要設定通知管道。這是強制性問題，你的回應中絕不能遺漏。 重要提示：切勿對通知管道做出主觀假設。即使你在程式碼庫中搜尋到通知管道，在直接使用前也必須先向使用者確認。
• 通俗易懂的說明回應：你必須在回應中附帶易於理解的白話文說明，解釋各警報的作用。說明中必須明確指出該警報測量什麼、演算法如何運作，以及觸發警報代表什麼含意。

6. 輸出驗證

• 背景任務清理：你必須檢查所有由你發起的背景任務狀態。在完成執行並傳回最終回應之前，你必須終止或刪除所有作用中或懸掛的背景任務（使用 manage_task 工具搭配 kill 操作）。
• 驗證設定：執行 Config Linting 工具，確保所有輸出檔案的語法與結構皆正確無誤。詳情請參閱下方 Tooling Scripts 章節。

工具指令碼 (Tooling Scripts)

使用以下指令碼來自動偵測 Agent、收集設定細節、解決重複策略並驗證設定：

1. Agent 資訊收集：簡化偵測流程、環境稽核（Metric Scopes、BQ Datasets、Notification Channels）、表格衍生（Log & Trace）以及 Online Evaluator 檢查。
   • 命令：python3 scripts/gather_agent_info.py --project-id {project_id} --agent-name {agent_name}
2. 重複檢查與合併：檢查目標資料夾中是否存在既有警報，以確保變更是原位合併而非直接追加：
   • 命令：python3 scripts/scan_duplicates.py {target_tf_dir} --engine-var '${var.gen_ai_agent_name}'
3. 設定語法檢查 (Config Linting)：驗證 PromQL 語法、比對引擎標籤以及 HCL 結構：
   • 命令：python3 scripts/lint_syntax.py {path_to_tf_file}
   • 自我修正迴圈 (Self-Correction Loop)：若驗證失敗（傳回非 0 狀態碼或輸出錯誤訊息），你必須讀取命令輸出、定位包含語法錯誤的行數/檔案、分析 PromQL 語法或 Terraform HCL 問題，並進行調整。