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 必须已配置并能够输出 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 运行成功且提供了完整信息，可直接跳过步骤 2，进入步骤 3（已有策略检查）。
   2. 步骤 2：指标作用域检查（备选方案）：仅在步骤 1 未能确定指标作用域（Metric Scope）时运行。
      • 操作 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_alert_policies.md
   质量	quality_alert_policies.md
   成本	cost_alert_policies.md
   安全防护	safety_alert_policies.md
   系统安全	security_alert_policies.md

5. 输出规范与格式要求

• 始终为目标 Agent 配置受支持的告警策略：
  • 可靠性监控：必须配置且仅配置 5 条告警策略：
    1. 延迟（Latency）（异常检测监控）
    2. 错误率 - 快速消耗 SLO（Fast Burn SLO）（1 小时窗口）
    3. 错误率 - 慢速消耗 SLO（Slow Burn SLO）（3 天窗口）
    4. 模型调用错误率（Model Call Error Rate）（基于 SQL 的 Log Analytics 告警）
    5. 工具调用错误率（Tool Call Error Rate）（基于 SQL 的 Log Analytics 告警）
  • 质量监控：必须配置且仅配置 3 条告警策略（需使用 Vertex AI Online Monitors）：
    1. 最终响应质量（Final Response Quality）
    2. 工具使用质量（Tool Use Quality）
    3. 幻觉率（Hallucination）
  • 成本监控：必须配置且仅配置 1 条成本告警策略：
    1. Token 快速消耗率（Rapid Token Burn Rate）（异常检测监控）
  • 安全防护监控：必须配置且仅配置 1 条安全防护告警策略：
    1. Model Armor 安全策略高频触发率（High Model Armor Safety Policy Trigger Rate）（基于 SQL 的 Log Analytics 告警）
  • 系统安全监控：必须配置且仅配置 1 条系统安全告警策略：
    1. IAM 权限拒绝高频触发率（High IAM Permission Denied Trigger Rate）（基于 SQL 的 Log Analytics 告警）
• 仅限 Terraform：生成的可观测性配置必须且仅能输出为 Terraform（.tf）文件（例如 alerts.tf、variables.tf）。
  • 只有在被要求部署告警且本地缺少有效 Terraform 安装时，才需要安装 Terraform。基于 SQL 的告警（使用 condition_sql）需要 Provider 版本 >= 6.0.0（或支持该特性的后期 5.x 版本）。
  • 如果未被要求部署告警，则无需安装 Terraform。
• 动态多资源告警（禁止硬编码绑定单一资源）：除非用户有明确要求（例如“仅针对该 Agent”），否则切勿在告警条件中硬编码特定的 Agent ID 或资源名称筛选器（如 {gen_ai_agent_name="{agent_name}"} 或 metric.labels.agent_resource_name="{agent_name}"）。用户在 Prompt 中提及特定 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 指针的存放位置，切勿盲目写入根目录。
• 通知渠道（Notification Channels）：默认情况下，未经用户指示严禁自行配置任何通知渠道。如果用户在 Prompt 中明确提供了通知渠道，则将告警配置为使用该渠道；若未提供通知渠道，必须在最终回复中明确询问用户是否需要配置通知渠道。这是必回答复项，严禁漏提。 重要提示：切勿对通知渠道做主观推测。即使在代码库中查到了通知渠道，在使用前也必须与用户二次确认。
• 通俗易懂的文本说明：必须在回复中包含对这些告警作用的通俗解释。需用简明易懂的语言说明告警测量的是什么、算法机制如何运作，以及触发告警代表什么含义。

6. 输出校验与清理

• 后台任务清理：必须检查自己创建的所有后台任务的状态。在结束执行并返回最终回复前，必须终止或销毁所有处于活跃或挂起状态的后台任务（使用 manage_task 工具，动作选择 kill）。
• 配置校验：运行**配置 Syntax 检查（Config Linting）**工具，确保所有输出文件的语法和结构无误。详见下方 Tooling Scripts（工具脚本）章节。

工具脚本

使用以下脚本排查 Agent、收集配置详情、解决重复项并校验配置：

1. Agent 信息收集脚本：简化资源排查、环境审计（Metric Scope、BQ 数据集、通知渠道）、数据表推导（Log 与 Trace）以及 Online Evaluator 检查。
   • 命令：python3 scripts/gather_agent_info.py --project-id {project_id} --agent-name {agent_name}
2. 重复检查与合并脚本：检查目标文件夹中已有的告警，确保变更是在原文件上就地合并（Merge in-place）而不是直接追加（Append）：
   • 命令：python3 scripts/scan_duplicates.py {target_tf_dir} --engine-var '${var.gen_ai_agent_name}'
3. 配置 Syntax 检查脚本（Config Linting）：校验 PromQL 语法、匹配 Engine 标签以及 HCL 语法结构：
   • 命令：python3 scripts/lint_syntax.py {path_to_tf_file}
   • 自修复循环：如果校验失败（返回非 0 退出码或输出错误信息），必须读取命令输出，定位包含 Lint 错误的文件与行号，分析 PromQL 语法或 Terraform HCL 的问题并进行修正。