为 AI Agent 配置 OpenTelemetry…

当需要为已接入 OpenTelemetry 的 AI Agent 生成可靠性、质量、成本、安全、安全性告警策略的 Terraform 配置时使用。

适用场景

解决思路

1. 按安全分级执行操作：Tier R 只读脚本（check_telemetry.py / gather_agent_info.py）无需确认可直接运行；Tier B 涉及计费与资源创建（create_online_monitor.py / 资源开通）必须先明确告知用户 Online Monitor（尤其 LLM evaluations）和 Telemetry（尤其 Cloud Trace/Cloud Logging 导出）可能产生的额外费用，并停下等待用户显式批准后才能继续。
2. 执行任何 Python 脚本前先安装依赖：运行 `pip install -r scripts/requirements.txt`。
3. 只操作用户在提示中显式提供的 Google Cloud 项目，不要假设或使用环境/历史中的其他项目。
4. 若用户要求先复制文件再修改，必须严格按顺序执行（先复制，再修改），不要直接写出最终内容。
5. 生成任何配置前，按顺序执行强制前置流程：第一步运行 `python3 scripts/gather_agent_info.py --project-id {project_id} --agent-name {agent_name}` 自动识别 Agent 运行时、验证遥测、指标范围、关联数据集等；若该脚本失败、返回部分数据或信息不全，则执行第二步手动回退，再执行第三步。
6. 第二步（仅当第一步无法确定指标范围时）：运行 `gcloud beta monitoring metrics-scopes list projects/{project_id}`，若返回 scoping project 则必须在该项目部署策略；或在 Terraform 配置中搜索 `google_monitoring_monitored_project` 资源提取 scoping project；若仍不明确，直接询问用户是否使用多项目 Cloud Monitoring Metric Scope 及其 scoping project ID。
7. 第三步：检查已有策略避免重复，扫描目标目录中是否已存在针对相同指标（按 `reasoning_engine_id` 或 `gen_ai_agent_name` 分组）的聚合策略，使用 `scan_duplicates.py` 验证。
8. 必须列出并阅读 `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。
9. 可靠性监控必须配置恰好 5 条策略：Latency（异常监控）、Error Rate - Fast Burn SLO（1 小时窗口）、Error Rate - Slow Burn SLO（3 天窗口）、Model Call Error Rate（基于 SQL 的 Observability Analytics 告警）、Tool Call Error Rate（基于 SQL 的 Observability Analytics 告警）。
10. 质量监控必须配置恰好 3 条策略（依赖 Vertex AI Online Monitors）：Final Response Quality、Tool Use Quality、Hallucination。
11. 成本监控必须配置恰好 1 条策略：Rapid Token Burn Rate（异常监控）。
12. 安全监控必须配置恰好 1 条策略：High Model Armor Safety Policy Trigger Rate（基于 SQL 的 Observability Analytics 告警）。
13. 安全性监控必须配置恰好 1 条策略：High IAM Permission Denied Trigger Rate（基于 SQL 的 Observability Analytics 告警）。
14. 只以 Terraform（.tf）文件形式输出配置（如 alerts.tf、variables.tf）；仅在用户要求部署且无有效 Terraform 安装时才安装 Terraform；基于 `condition_sql` 的 SQL 告警要求 provider 版本 >= 6.0.0（或支持该特性的 5.x 后期版本）；若用户未要求部署则无需安装 Terraform。
15. 不要硬编码特定 Agent ID 或资源名过滤器（如 `{gen_ai_agent_name="{agent_name}"}` 或 `metric.labels.agent_resource_name="{agent_name}"`），除非用户明确要求（如“仅针对此 Agent”）；仅在请求中提及 Agent 名称/ID 不构成显式过滤要求，仍须默认动态分组覆盖所有 Agent。
16. 可靠性指标使用 PromQL 时必须使用分组聚合，按 `gen_ai_agent_name` 分组（如 `by (gen_ai_agent_name)`），避免过滤到单个 ID/名称，除非用户要求。
17. 质量指标使用标准阈值过滤器时，完全省略 `agent_resource_name` 过滤，条件过滤器仅针对监控资源类型（`aiplatform.googleapis.com/OnlineEvaluator`）和指标类型（`aiplatform.googleapis.com/online_evaluator/scores`）在项目级别全局配置。
18. 下游调用使用 SQL 时，省略针对特定 Agent 名称的 `ENDS_WITH` 过滤，改为提取 Agent 标识（如 `JSON_VALUE(resource.attributes, '$."cloud.resource_id"')`）并将其与模型或工具名一起加入 `GROUP BY` 子句。
19. 目录推断：优先使用用户显式提供的路径；否则部署到目标 Terraform 或 SRE 目录（如 `monitoring/`、`ops/`、`sre/`），用工具定位项目中告警策略或状态指针所在位置，不要盲目写到根目录。
20. 通知渠道：默认不配置任何通知渠道；若用户显式提供则使用；若未提供，必须在最终回复中明确询问用户是否需要配置通知渠道（此问题为强制项，不得省略）；不要对通知渠道做假设，若在代码库中搜索到通知渠道，使用前必须与用户确认。
21. 在回复中必须包含对告警作用的通俗英文解释，说明告警测量什么、算法如何工作、触发意味着什么。
22. 完成前必须检查所有后台任务状态，用 `manage_task` 工具的 `kill` 动作终止任何活跃或挂起的后台任务。
23. 运行 Config Linting 工具验证输出文件语法与结构：`python3 scripts/lint_syntax.py {path_to_tf_file}`；若验证失败（非零退出或输出错误），必须读取输出、定位错误行/文件、分析 PromQL 语法或 Terraform HCL 问题、就地修改并重新运行，循环直到通过。
24. 使用 `python3 scripts/scan_duplicates.py {target_tf_dir} --engine-var '${var.gen_ai_agent_name}'` 验证目标文件夹中已有告警，确保就地合并而非追加。
25. 处理脚本预期失败：`scan_duplicates.py` 退出码 1 时解析 JSON 输出中的重复资源目标，就地升级编辑后重新检查直到返回 0。
26. 避免冗余发现调用：若 `gather_agent_info.py` 成功返回 Trace 或 Log 表名（或写入变量文件），不要再调用 `list_trace_scope_table_names.py` 或 `list_log_scope_table_names.py`，这些脚本由 `gather_agent_info.py` 内部运行，仅作为外部回退。
27. 脚本执行失败时自我纠正：若工具脚本（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 日志或错误输出，分析错误信息并尝试动态修正参数后重试，再升级或回退到手动方案；查阅相关领域参考文件获取特定脚本的详细排错步骤。
28. 分布指标对齐器约束：标准 `ALIGN_MEAN` 不能应用于 `DELTA` 分布指标（如 `online_evaluator/scores`），必须使用基于百分位的对齐器（如 `ALIGN_PERCENTILE_50`）将分数分布归约为可比较的数值流。
29. HCL Heredoc 插值：在 PromQL 或 SQL 查询（定义为字符串）中引用 Terraform 变量时，必须使用 `${var.variable_name}` 语法，裸引用如 `var.variable_name` 会在部署时失败。
30. 避免递归目录操作：若仓库根目录包含大量文件，禁止从根目录运行递归列出或搜索命令（如 `ls -R`、`find .`、原始递归 `grep`），否则会冻结会话；始终针对特定子目录操作。
31. 解释原始错误计数或绝对失败请求数边界在流量变化下不可扩展，推荐使用基于比率的错误率告警。
32. 端到端验证动态指标阈值策略时，不要尝试制造真实平台错误；改为以标准安全边界（Z-score 乘数 > 15）部署告警策略，然后临时将标准差 Z-score 限制更新为负值（如 > -3）触发/验证 Firing 状态，之后恢复；主动执行此操作前必须获得确认。

适用边界 · 注意事项

• 不适用于与 AI Agent 无关的标准基础设施监控。
• 当 Agent 未接入 OpenTelemetry 时，无法用于可靠性、成本、安全、安全性告警（这些依赖通用 OTel 指标）。
• 质量告警依赖 Vertex AI Online Monitors，严格绑定 Vertex AI 部署，非 Vertex AI 部署无法使用。