Agent Platform Alert Configuration Setup: A Complete Guide for Google Monitoring Policies

Agent Platform Alert Configuration is a Google‑provided skill that validates and generates Terraform‑based Google Monitoring alert policies for Gen AI agents through extraction, linting, and duration validation utilities.

This skill, located in the google/skills repository under skills/cloud/agent-platform-alert-configuration, gives platform engineers a programmatic way to build, lint, and enforce standards for alert policies. Rather than writing raw HCL by hand, you use Python utilities that guarantee consistent structure and valid PromQL semantics.

Core Validation Pipeline

The Agent Platform Alert Configuration workflow runs through three integrated stages. Each stage maps to a specific function in config_utils.py, letting you invoke them individually or chain them together in automation scripts.

Stage 1: Extract Alert Policies from HCL

The extract_alert_policies function parses Terraform files for google_monitoring_alert_policy resources. It returns structured dictionaries containing:

• Display name and resource name
• Alert duration
• Embedded PromQL query strings
• Label filters
• Inferred signal type (latency, SLO burn-rate, quality metric)

from config_utils import extract_alert_policies

hcl_content = Path("alerts/production.tf").read_text()
policies = extract_alert_policies(hcl_content)   # → list[dict]

for p in policies:
    print(f"{p['resource_name']}: {p['signal_type']} ({p['duration']})")

The signal type is inferred by inspecting resource naming conventions, display names, and filter expression patterns—no manual classification required.

Stage 2: Lint PromQL Queries

The lint_query function enforces syntax correctness and policy compliance on every query. It checks for balanced parentheses and braces, valid time-window syntax (e.g., [5m], [1h]), proper offset formats, and critically—presence of an agent identifier (namespace or gen_ai_agent_name). Alerts missing these labels cannot route to specific agents effectively.

from config_utils import lint_query

query = 'sum(rate(http_requests_total[5m])) by (gen_ai_agent_name)'
errors = lint_query(query)

if errors:
    print("Lint failures:", errors)
else:
    print("Query passes all lint checks.")

Stage 3: Validate Policy Duration

The validate_policy_duration function enforces Google's look-back window rules:

Look-back window	Required duration
≤ 25 hours	300s (mandatory)
> 25 hours	Duration must be empty
Quality-metric alerts	300s (forced)

from config_utils import validate_policy_duration

policy = {
    'lookback_hours': 24,
    'duration': '600s',  # Invalid: should be 300s

    'signal_type': 'latency'
}

errors = validate_policy_duration(policy)

# → ["Short-lookback alert must use duration='300s'"]

Helper Scripts for Common Workflows

Beyond the core utilities, the scripts/ directory contains executable automation that ties the pipeline together.

Script	Purpose
create_online_monitor.py	Generates new alert policy HCL with integrated validation
scan_duplicates.py	Detects duplicate alert definitions across all .tf files
list_log_scope_table_names.py	Extracts BigQuery table names for log-based alert scopes
list_trace_scope_table_names.py	Extracts BigQuery table names for trace-based alert scopes
lint_syntax.py	Batch-runs lint_query across the entire policy repository
gather_agent_info.py	Pulls agent identifiers from queries to aid policy generation
check_telemetry.py	Verifies required metrics and labels are present in each policy

Creating a New Alert Policy Programmatically

The create_online_monitor.py script encapsulates the full validation pipeline. It accepts parameters via CLI, builds the HCL block, runs linting and duration checks, and writes to disk only on success.

python -m skills.cloud.agent-platform-alert-configuration.scripts.create_online_monitor \
    --name "high_latency" \
    --display-name "High latency alert" \
    --query 'rate(http_latency_seconds_sum[1m]) / rate(http_latency_seconds_count[1m]) > 0.5' \
    --duration 300s

This executes:

1. HCL block construction from templates
2. lint_query validation on the PromQL expression
3. validate_policy_duration compliance check
4. Write to alerts/high_latency.tf if all checks pass

Complete Working Example

Here's a full workflow that extracts, validates, and reports on policies in a Terraform directory:

from pathlib import Path
from config_utils import extract_alert_policies, lint_query, validate_policy_duration

tf_dir = Path("terraform/alerts")
all_policies = []

# Extract all policies from .tf files

for tf_file in tf_dir.glob("*.tf"):
    all_policies.extend(extract_alert_policies(tf_file.read_text()))

# Validate each policy

for p in all_policies:
    print(f"\n--- {p['resource_name']} ---")
    
    # Check query syntax

    query_errors = lint_query(p['query'])
    if query_errors:
        print(f"  Query errors: {query_errors}")
    
    # Check duration compliance

    duration_errors = validate_policy_duration(p)
    if duration_errors:
        print(f"  Duration errors: {duration_errors}")
    
    if not query_errors and not duration_errors:
        print("  ✓ All validations passed")

Key Source Files in the Repository

All utilities are implemented in Python under skills/cloud/agent-platform-alert-configuration/scripts/:

• config_utils.py — Core validation library: extract_alert_policies, lint_query, validate_policy_duration (source)
• create_online_monitor.py — Policy generation with built-in validation (source)
• scan_duplicates.py — Duplicate detection across policy files (source)
• list_log_scope_table_names.py — Log-scope BigQuery table extraction (source)
• list_trace_scope_table_names.py — Trace-scope BigQuery table extraction (source)
• lint_syntax.py — Batch linting report generator (source)
• gather_agent_info.py — Agent identifier extraction helper (source)
• check_telemetry.py — Telemetry requirement verifier (source)

Summary

• Agent Platform Alert Configuration provides Python utilities and scripts for programmatic management of Google Monitoring alert policies.
• The three-stage pipeline—extraction (extract_alert_policies), linting (lint_query), and duration validation (validate_policy_duration)—ensures policy correctness before deployment.
• Helper scripts like create_online_monitor.py bundle validation into reusable workflows for generating new alerts.
• All code lives in google/skills under skills/cloud/agent-platform-alert-configuration/scripts/, with config_utils.py serving as the shared dependency.

Frequently Asked Questions

What is Agent Platform Alert Configuration used for?

Agent Platform Alert Configuration is a skill for validating and generating Terraform-based Google Monitoring alert policies specifically designed for Gen AI agents. It automates the extraction of policy definitions from HCL, enforces PromQL syntax standards, and validates duration settings against look-back window requirements.

How does the lint_query function validate PromQL queries?

The lint_query function in config_utils.py checks for balanced parentheses and braces, proper time-window syntax (like [5m] or [1h]), valid offset formatting, and mandatory agent identifiers. Queries must reference either namespace or gen_ai_agent_name to pass validation, ensuring alerts can be properly attributed to specific agents.

What are the duration requirements for alert policies?

Short-look-back alerts (≤ 25 hours) must use duration='300s'. Long-look-back alerts (> 25 hours) must have an empty duration field. Quality-metric alerts are always forced to 300s regardless of look-back window. The validate_policy_duration function enforces these rules automatically.

Can I create new alert policies without writing Terraform manually?

Yes. The create_online_monitor.py script generates complete HCL blocks from CLI parameters. It runs the full validation pipeline—including query linting and duration checks—before writing the policy to alerts/<name>.tf, eliminating manual HCL editing and catching errors early.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}