agent-platform-alert-configuration

エージェントプラットフォームのアラート設定

帰属表示

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、使用状況の帰属表示を必ずお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内では決して実行しない）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-alert-configuration)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:agent-platform-alert-configuration) を追加してください。

重要な手順

1. 安全性と確認の段階（重要）

ユーザーに代わってコマンドを実行したり設定を書き込んだりする前に、要求された操作に応じて、以下の安全性の段階を必ず守ってください。

1. 段階 R：読み取り専用（check_telemetry.py / gather_agent_info.py）
   • ルール：確認は不要です。これらのスクリプトを直ちに実行して、テレメトリの状態を調べたり、エージェントの設定情報を収集したりできます。
2. 段階 B：課金とリソースの作成（create_online_monitor.py / プロビジョニング）
   • ルール：ユーザーによる明示的な確認が必要です。これらの操作では追加料金が発生し、クラウドリソースが作成されます。エージェントは、オンラインモニター（特に LLM 評価）とテレメトリ（特に Cloud Trace/Cloud Logging へのエクスポート）の両方について、追加料金が発生する可能性があることを必ずユーザーに明示的に警告してください。プロビジョニングを進める前、または設定コマンドを提示する前に、必ず作業を中断して明示的な承認を求めてください。

2. 前提条件と依存関係

エージェントのテレメトリ

• 免責事項：信頼性、コスト、安全性、セキュリティに関するアラートを機能させるには、基盤となるエージェントに OpenTelemetry（OTel）メトリクスを出力するようインストルメンテーションを施す必要があります。エージェントがこれらのメトリクスを出力しない場合、アラートポリシーの評価に使用できるデータストリームはありません。

Python 環境

このスキルの Python スクリプトを実行する前に、必要な依存関係を環境にインストールする必要があります。まず、次のコマンドを実行してください。

pip install -r scripts/requirements.txt

3. 入力に関する前提

• 指定プロジェクトの厳守：ユーザーのプロンプトで明示的に指定された Google Cloud プロジェクトのみを対象に、アラートを設定し、テレメトリを照会し、または操作してください。ユーザーから明示的な指示がない限り、環境や履歴にある他のプロジェクトを想定したり、使用したりしないでください。
• ファイル変換の順序：ユーザーがファイルをコピーしてから変更するよう明示的に依頼した場合は、最終的な内容を直接書き込むのではなく、必ず順番どおりに（先にコピーし、その後に変更する）実行してください。

4. 実行手順

1. 必須の事前実行プロトコル（順次実行）：設定を生成または書き込む前に、必ず次の手順を順番に実行してください。

   1. ステップ 1：簡易調査（必須）：gather_agent_info.py を実行し、エージェントのランタイムを自動的に特定して、テレメトリー、メトリクスのスコープ、リンクされたデータセットなどを確認します。このスクリプトは、以降の手順で手動確認する項目の大部分を処理します。
      • コマンド：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} を実行します。スコーププロジェクトが返された場合は、必ずそのプロジェクトにポリシーをデプロイしてください。
      • アクション 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. 出力と形式

• 対象エージェントに対して、サポートされているアラートポリシーを必ず設定してください。

  • 信頼性モニタリングの場合：アラートポリシーを必ず5つだけ設定してください。
    1. レイテンシ（異常モニタリング）
    2. エラー率 - 高速バーン SLO（1時間ウィンドウ）
    3. エラー率 - 低速バーン SLO（3日間ウィンドウ）
    4. モデル呼び出しエラー率（SQL ベースのオブザーバビリティ分析アラート）
    5. ツール呼び出しエラー率（SQL ベースのオブザーバビリティ分析アラート）
  • 品質モニタリングの場合：アラートポリシーを必ず3つだけ設定してください（Vertex AI Online Monitors が必要です）。
    1. 最終応答の品質
    2. ツール使用の品質
    3. ハルシネーション
  • コストモニタリングの場合：コストアラートポリシーを必ず1つだけ設定してください。
    1. トークン消費率の急増（異常モニタリング）
  • 安全性モニタリングの場合：安全性アラートポリシーを必ず1つだけ設定してください。
    1. Model Armor の安全性ポリシーのトリガー率が高い（SQL ベースのオブザーバビリティ分析アラート）
  • セキュリティモニタリングの場合：セキュリティアラートポリシーを必ず1つだけ設定してください。
    1. IAM 権限拒否のトリガー率が高い（SQL ベースのオブザーバビリティ分析アラート）

• Terraform のみ：生成したオブザーバビリティ設定は、Terraform（.tf）ファイル（alerts.tf、variables.tf など）のみで記述してください。

  • アラートのデプロイを依頼されており、有効な Terraform のインストール環境がない場合に限り、Terraform をインストールする必要があります。condition_sql を使用する SQL ベースのアラートには、プロバイダーのバージョン >= 6.0.0（または、この機能をサポートする後期の 5.x バージョン）が必要です。
  • アラートのデプロイを依頼されていない場合は、terraform をインストールする必要はありません。

• 動的な複数リソースのアラート（単一リソースへの固定は禁止）：明示的に依頼されない限り（たとえば、「このエージェントのみ」）、アラート条件に特定のエージェント ID やリソース名フィルター（例：{gen_ai_agent_name="{agent_name}"} や metric.labels.agent_resource_name="{agent_name}"）をハードコードしてはいけません。依頼の中で特定のエージェント名や ID に言及されているだけでは、固定またはフィルタリングの明示的な依頼にはなりません。すべてのエージェントを対象とする動的なグループ化を、引き続き既定で使用してください。プロジェクト内のすべてのアクティブなエージェントを動的に対象とするには、次のようにします。

  適切な例（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 を使用するダウンストリーム呼び出しの場合: 特定のエージェント名を対象とした ENDS_WITH フィルターは省略します。代わりに、エージェント識別子（たとえば JSON_VALUE(resource.attributes, '$."cloud.resource_id"')）を抽出し、モデル名またはツール名と並べて GROUP BY 句に追加します。

• ディレクトリの推測: ユーザーが明示的に指定したパス（ある場合）を優先します。それ以外の場合は、対象となる Terraform または SRE フォルダ（monitoring/、ops/、sre/ など）に設定ファイルを配置します。ルートに無闇に書き込むのではなく、ツールを使用してプロジェクト内でアラートポリシーやステートポインタが存在する場所を特定してください。

• 通知チャネル: デフォルトでは、ユーザーの入力なしに通知チャネルを設定しないでください。ユーザーがプロンプトで通知チャネルを明示的に指定した場合は、それを用いるようにアラートを設定します。通知チャネルが指定されていない場合は、最終応答で通知チャネルを設定するかどうかを必ずユーザーに明示的に尋ねなければなりません。これは必須の質問であり、応答から省略してはなりません。 重要 通知チャネルについて推測しないでください。通知チャネルをコードベースで検索した場合、それを使用する前に必ずユーザーに確認してください。

• 平易な英語での応答: アラートが何を行うかについて、平易な英語での説明を応答に含めなければなりません。これは、アラートが何を測定するのか、アルゴリズムがどのように動作するのか、トリガーが何を示すのかを平易な英語で説明するものでなければなりません。

6. 出力の検証

• バックグラウンドタスクのクリーンアップ: 生成したすべてのバックグラウンドタスクのステータスを必ず確認しなければなりません。実行を完了して最終応答を返す前に、アクティブなまたはハングしているバックグラウンドタスクを終了または強制終了しなければなりません（manage_task ツールをアクション kill で使用）。
• 設定の検証: Config Linting ツールを実行して、すべての出力ファイルが正しい文法と構造で書き込まれていることを確認します。ツールの詳細については、以下の Tooling Scripts セクションを参照してください。

Tooling Scripts

以下のスクリプトを使用して、エージェントの検出、設定の詳細の収集、重複の解決、および設定の検証を行います。

1. エージェント情報の収集: 検出、環境の監査（メトリックスコープ、BQ データセット、通知チャネル）、テーブルの導出（ログとトレース）、およびオンラインエバリュエーターの検証を効率化します。
   • コマンド: 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}
   • 自己修正ループ: 検証が失敗した場合（非ゼロで終了するかエラーを出力する場合）、コマンドの出力を読み、lint エラーを含む行またはファイルを特定し、PromQL 構文または Terraform HCL の問題を分析し、インプレースで調整を適用し、lint_syntax.py 検証を再実行しなければなりません。検証スクリプトが正常にパスするまで、このループを繰り返します。

注意点と動作の修正

• 生のエラー境界：生のエラー件数や絶対値の失敗リクエスト数に基づく境界は、トラフィック量が変化すると適切にスケールしないことを説明してください。代わりに、比率に基づくエラー率アラートを推奨してください。
• 安全なしきい値調整の E2E 検証：動的なメトリクスしきい値ポリシーをエンドツーエンドで検証する際は、実際のプラットフォームエラーを意図的に発生させないでください。代わりに、標準の安全な範囲（Z スコアの乗数 > 15）でアラートポリシーをデプロイし、その後、一時的に標準偏差の Z スコア制限を負の値（例：> -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 など）の実行が予期せず失敗した場合、標準出力／標準エラーのログまたはエラー出力を必ず読み、確認してください。エラーメッセージを分析し、エスカレーションする前、または手動での計画に切り替える前に、パラメーターを動的に修正して再実行してください。特定のスクリプトの詳細なトラブルシューティング手順については、関連するドメイン固有のリファレンスファイルを参照してください。
• 分布メトリクスのアライナーに関する制約：標準の ALIGN_MEAN は、online_evaluator/scores などの DELTA 分布メトリクスには適用できません。スコア分布を比較可能な数値ストリームに変換するには、パーセンタイルベースのアライナー（ALIGN_PERCENTILE_50 など）を必ず使用してください。
• HCL ヒアドキュメントの補間：文字列として定義された PromQL または SQL クエリ内で Terraform 変数を参照する場合は、必ず ${var.variable_name} 構文を使用してください。var.variable_name のようにそのまま記述すると、デプロイ時に失敗します。
• 再帰的なディレクトリ操作を避ける：ファイル数が非常に多いリポジトリのルートから、再帰的な一覧表示や検索コマンド（ls -R、find .、または再帰的な grep の直接実行など）を実行してはいけません。セッションがフリーズします。必ず対象を特定のサブディレクトリに絞ってください。

参考リンク

• オンラインモニターによる継続的な評価
• Agent Platform の品質メトリクス
• Google Cloud アラートポリシーガイド
• Google Cloud Monitoring PromQL ドキュメント