agent-platform-alert-configuration

Agent Platform 告警配置

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不能在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-alert-configuration)" 并将 agent-skills/1.0 (skill:agent-platform-alert-configuration) 追加到 User-Agent 标头中。

关键步骤

1. 安全与确认级别（关键）

在代表用户执行任何命令或编写配置之前，必须遵守以下根据所请求操作设定的安全级别：

1. 级别 R：只读（check_telemetry.py / gather_agent_info.py）
   • 规则：无需确认。你可以立即执行这些脚本，以检查遥测状态或收集 Agent 配置详情。
2. 级别 B：计费与资源创建（create_online_monitor.py / 配置资源）
   • 规则：必须获得用户明确确认。这些操作会产生额外费用并创建云资源。Agent 必须始终明确提醒用户，Online Monitor（特别是 LLM 评估）和遥测（特别是 Cloud Trace/Cloud Logging 导出）都可能产生额外费用。配置资源或提供设置命令之前，必须停止并征求用户明确批准。

2. 前提条件与依赖项

Agent 遥测

• 免责声明：要使可靠性、成本、安全和防护告警正常工作，底层 Agent 必须经过检测，能够发出 OpenTelemetry（OTel）指标。如果 Agent 未发出这些指标，告警策略将没有可供评估的数据流。

Python 环境

在此技能中执行任何 Python 脚本之前，必须在环境中安装所需依赖项。请先运行以下命令：

pip install -r scripts/requirements.txt

3. 输入假设

• 明确遵循项目范围：只能配置告警、查询遥测或与用户在提示词中明确指定的 Google Cloud 项目交互。除非用户明确要求，否则不得假定或使用环境或历史记录中的其他项目。
• 按顺序转换文件：如果用户明确要求先复制文件再修改文件，必须按顺序执行这些操作（先复制，再修改），而不是直接写入最终内容。

4. 执行步骤

1. 强制前置执行流程（按顺序）：在生成或编写任何配置之前，必须按顺序执行以下步骤：

   1. 步骤 1：精简发现（强制）：运行 gather_agent_info.py，自动识别 Agent 运行时、验证遥测数据、 指标范围、关联的数据集等。此脚本涵盖了后续步骤中列出的大多数手动验证。
      • 命令：python3 scripts/gather_agent_info.py --project-id {project_id} --agent-name {agent_name}
      • 注意：如果此脚本失败、返回部分数据，或未提供所需的全部信息，则必须通过执行步骤 2 中列出的手动备用步骤来满足要求，然后执行下方的步骤 3。如果步骤 1 成功并提供了所有信息，则跳过步骤 2，直接执行步骤 3（验证现有策略）。
   2. 步骤 2：指标范围验证（备用）：仅当步骤 1 未能确定指标范围时才运行此步骤。
      • 操作 A（CLI）：运行 gcloud beta monitoring metrics-scopes list projects/{project_id}。如果返回了范围项目，则必须在该项目中部署策略。
      • 操作 B（代码扫描）：搜索 Terraform 配置中的 google_monitoring_monitored_project 资源，以提取范围项目。
      • 操作 C（备用）：如果无法确定，请询问用户：“您是否在使用多项目 Cloud Monitoring 指标范围？如果是，范围项目 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 配置受支持的告警策略：

  • 可靠性监控：必须配置且仅配置五项告警策略：
    1. 延迟（异常监控）
    2. 错误率 - SLO 快速消耗（1 小时窗口）
    3. 错误率 - SLO 缓慢消耗（3 天窗口）
    4. 模型调用错误率（基于 SQL 的可观测性分析告警）
    5. 工具调用错误率（基于 SQL 的可观测性分析告警）
  • 质量监控：必须配置且仅配置三项告警策略（需要 Vertex AI Online Monitors）：
    1. 最终响应质量
    2. 工具使用质量
    3. 幻觉
  • 成本监控：必须配置且仅配置一项成本告警策略：
    1. Token 消耗速率过快（异常监控）
  • 安全防护监控：必须配置且仅配置一项安全防护告警策略：
    1. Model Armor 安全策略触发率过高（基于 SQL 的可观测性分析告警）
  • 安全监控：必须配置且仅配置一项安全告警策略：
    1. IAM 权限拒绝触发率过高（基于 SQL 的可观测性分析告警）

• 仅使用 Terraform：生成的可观测性配置只能写入 Terraform（.tf）文件（例如 alerts.tf、variables.tf）。

  • 只有在用户要求部署告警且没有有效的 Terraform 安装时，才需要安装 Terraform。基于 SQL 的告警使用 condition_sql，要求提供程序版本 >= 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 分组）：

  sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_count{monitored_resource="generic_node"}[5m])) by (gen_ai_agent_name)
  

  反面示例（PromQL 硬编码过滤器）：

  sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_count{monitored_resource="generic_node", gen_ai_agent_name="support-bot"}[5m]))
  

  • 使用 PromQL 的可靠性指标：始终使用分组聚合。按 gen_ai_agent_name 分组（例如 by (gen_ai_agent_name)）。除非用户提出要求，否则避免过滤到单个 ID/名称。
  • 使用标准阈值过滤器的质量指标：完全省略 agent_resource_name 过滤器。配置条件过滤器，使其在整个项目范围内仅针对受监控的资源类型 （aiplatform.googleapis.com/OnlineEvaluator）和指标类型 （aiplatform.googleapis.com/online_evaluator/scores）。

  良好示例（SQL 分组）：

  SELECT
    JSON_VALUE(resource.attributes, '$."cloud.resource_id"') as agent_id,
    ...
  FROM ...
  GROUP BY agent_id
  

  反面示例（SQL 硬编码过滤器）：

  SELECT ...
  FROM ...
  WHERE JSON_VALUE(resource.attributes, '$."cloud.resource_id"') = 'support-bot'
  

  • 使用 SQL 进行下游调用：省略针对特定 Agent 名称的 ENDS_WITH 筛选条件。改为提取 Agent 标识符（例如，JSON_VALUE(resource.attributes, '$."cloud.resource_id"')），并将其与模型或工具名称一同添加到 GROUP BY 子句中。

• 目录推断：优先使用用户明确提供的路径（如有）。否则，将配置文件部署到目标 Terraform 或 SRE 文件夹（例如 monitoring/、ops/、sre/）。使用工具查找项目中告警策略或状态指针的位置，而不是盲目地写入根目录。

• 通知渠道：默认情况下，绝不在没有用户输入的情况下配置任何通知渠道。如果用户在提示词中明确提供了通知渠道，请将告警配置为使用该渠道。如果未提供通知渠道，你必须在最终回复中明确询问用户是否要配置通知渠道。**这是必须提出的问题，不得从回复中省略。**重要：不要对通知渠道作出假设。如果你在代码库中搜索到通知渠道，必须始终先向用户确认，然后才能使用。

• 通俗易懂的回复：你的回复必须包含对告警作用的通俗易懂的说明。必须用通俗易懂的语言说明告警衡量的内容、算法的工作方式，以及触发告警意味着什么。

6. 输出验证

• 清理后台任务：你必须验证所启动的所有后台任务的状态。在完成执行并返回最终回复之前，必须终止或结束任何仍在运行或挂起的后台任务（使用 manage_task 工具，并将操作设为 kill）。
• 验证配置：运行 配置检查 工具，确保所有输出文件的语法和结构正确。请参阅下文 工具脚本 一节中的工具详情。

工具脚本

使用以下脚本来发现 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. 配置检查：验证 PromQL 语法、引擎标签匹配情况以及 HCL 结构：
   • 命令：python3 scripts/lint_syntax.py {path_to_tf_file}
   • 自我修正循环：如果验证失败（退出状态非零或输出错误），你必须阅读命令输出，找到包含检查错误的行或文件，分析 PromQL 语法或 Terraform HCL 问题，在原处进行调整，然后重新运行 lint_syntax.py 验证。重复此循环，直到验证脚本成功通过。

注意事项与行为修正

• 原始错误边界：说明原始错误计数或绝对失败请求数边界无法适应不断变化的流量吞吐量。 建议改用基于比率的错误率告警。
• 安全阈值调整的端到端验证：端到端验证动态指标阈值策略时，切勿尝试强制触发真实平台错误。应先部署采用标准安全边界（Z-score 乘数 > 15）的告警策略，然后临时将标准差 Z-score 限制更新为负值（例如，> -3），以触发／验证“Firing”状态，再恢复原值。主动执行此操作前，务必先获得确认。
• 预期脚本失败：
  • scan_duplicates.py 以代码 1 退出：解析 JSON 输出，查找重复的资源目标。就地修改升级内容，然后重新检查，直到脚本以 0 退出。
  • 避免冗余发现调用：如果 gather_agent_info.py 成功返回 Trace 或 Log 表名（或将其写入变量文件），切勿再调用 list_trace_scope_table_names.py 或 list_log_scope_table_names.py。 这些脚本由 gather_agent_info.py 在内部运行，仅作为外部备用方案提供。
  • 脚本执行失败与自我修正：如果实用脚本（例如 gather_agent_info.py、check_telemetry.py、create_online_monitor.py、analyze_traffic.py、list_log_scope_table_names.py 或 list_trace_scope_table_names.py）意外执行失败，必须阅读并检查 stdout／stderr 日志或错误输出。分析错误消息，尝试动态修正参数并重试，然后再升级处理或改用手动方案。有关特定脚本的详细故障排除步骤，请查阅相关领域的参考文件。
• 分布指标对齐器限制：标准 ALIGN_MEAN 不能用于 online_evaluator/scores 等 DELTA 分布指标。必须使用基于百分位数的对齐器（如 ALIGN_PERCENTILE_50），将分数分布缩减为可比较的数值流。
• HCL Heredoc 插值：在 PromQL 或 SQL 查询（以字符串形式定义）中引用 Terraform 变量时，必须使用 ${var.variable_name} 语法。使用 var.variable_name 这类不带 $ 的引用会导致部署失败。
• 避免递归目录操作：如果仓库根目录包含大量文件，切勿在该目录下运行递归列出或搜索命令（例如 ls -R、find . 或原始递归 grep），否则会导致会话卡死。务必指定具体子目录。

相关链接

• 使用在线监控器进行持续评估
• Agent Platform 质量指标
• Google Cloud 告警策略指南
• Google Cloud Monitoring PromQL 文档