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

> Master Agent Platform Alert Configuration with this complete Google Monitoring setup guide. Learn to validate and generate Terraform alert policies for Gen AI agents efficiently.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/google/skills/blob/main/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)

```python
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.

```python
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) |

```python
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`](https://github.com/google/skills/blob/main/create_online_monitor.py) | Generates new alert policy HCL with integrated validation |
| [`scan_duplicates.py`](https://github.com/google/skills/blob/main/scan_duplicates.py) | Detects duplicate alert definitions across all `.tf` files |
| [`list_log_scope_table_names.py`](https://github.com/google/skills/blob/main/list_log_scope_table_names.py) | Extracts BigQuery table names for log-based alert scopes |
| [`list_trace_scope_table_names.py`](https://github.com/google/skills/blob/main/list_trace_scope_table_names.py) | Extracts BigQuery table names for trace-based alert scopes |
| [`lint_syntax.py`](https://github.com/google/skills/blob/main/lint_syntax.py) | Batch-runs `lint_query` across the entire policy repository |
| [`gather_agent_info.py`](https://github.com/google/skills/blob/main/gather_agent_info.py) | Pulls agent identifiers from queries to aid policy generation |
| [`check_telemetry.py`](https://github.com/google/skills/blob/main/check_telemetry.py) | Verifies required metrics and labels are present in each policy |

### Creating a New Alert Policy Programmatically

The [`create_online_monitor.py`](https://github.com/google/skills/blob/main/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.

```bash
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:

```python
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`](https://github.com/google/skills/blob/main/config_utils.py)** — Core validation library: `extract_alert_policies`, `lint_query`, `validate_policy_duration` ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py))
- **[`create_online_monitor.py`](https://github.com/google/skills/blob/main/create_online_monitor.py)** — Policy generation with built-in validation ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/create_online_monitor.py))
- **[`scan_duplicates.py`](https://github.com/google/skills/blob/main/scan_duplicates.py)** — Duplicate detection across policy files ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/scan_duplicates.py))
- **[`list_log_scope_table_names.py`](https://github.com/google/skills/blob/main/list_log_scope_table_names.py)** — Log-scope BigQuery table extraction ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/list_log_scope_table_names.py))
- **[`list_trace_scope_table_names.py`](https://github.com/google/skills/blob/main/list_trace_scope_table_names.py)** — Trace-scope BigQuery table extraction ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/list_trace_scope_table_names.py))
- **[`lint_syntax.py`](https://github.com/google/skills/blob/main/lint_syntax.py)** — Batch linting report generator ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/lint_syntax.py))
- **[`gather_agent_info.py`](https://github.com/google/skills/blob/main/gather_agent_info.py)** — Agent identifier extraction helper ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/gather_agent_info.py))
- **[`check_telemetry.py`](https://github.com/google/skills/blob/main/check_telemetry.py)** — Telemetry requirement verifier ([source](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/check_telemetry.py))

## 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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.