agent-platform-alert-configuration

Files (29)

• SKILL.md
• attribution.md · references/
• cost_alert_policies.md · references/
• has_historical_traffic_data.md · references/
• no_historical_traffic_data.md · references/
• quality_alert_policies.md · references/
• reliability_alert_policies.md · references/
• safety_alert_policies.md · references/
• security_alert_policies.md · references/
• telemetry_enablement.md · references/
• analyze_traffic.py · scripts/
• analyze_traffic_test.py · scripts/
• check_telemetry.py · scripts/
• check_telemetry_test.py · scripts/
• config_utils.py · scripts/
• config_utils_test.py · scripts/
• create_online_monitor.py · scripts/
• create_online_monitor_test.py · scripts/
• gather_agent_info.py · scripts/
• gather_agent_info_test.py · scripts/
• lint_syntax.py · scripts/
• list_log_scope_table_names.py · scripts/
• list_log_scope_table_names_test.py · scripts/
• list_trace_scope_table_names.py · scripts/
• list_trace_scope_table_names_test.py · scripts/
• mock_traffic_data.py · scripts/
• requirements.txt · scripts/
• scan_duplicates.py · scripts/
• scan_duplicates_test.py · scripts/

SKILL.md (first lines)

# Agent Platform Alert Configuration

## Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you
MUST read [Usage Attribution](references/attribution.md). For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix `gcloud` with
`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-alert-configuration)"`
and append
`agent-skills/1.0 (skill:agent-platform-alert-configuration)`
to `User-Agent` headers.

## Critical Steps

### 1. Safety & Confirmation Tiers (CRITICAL)

Before executing any commands or writing configurations on behalf of the user,
you MUST adhere to the following safety tiers based on the action requested:

1.  **Tier R: Read-only (`check_telemetry.py` / `gather_agent_info.py`)**
    *   **Rule**: No confirmation needed. You may execute these scripts
        immediately to inspect telemetry status or gather agent configuration
        details.
2.  **Tier B: Billing & Resource Creation (`create_online_monitor.py` /
    provisioning)**
    *   **Rule**: **Explicit User Confirmation Required**. These actions incur
        additional billing charges and create cloud resources. The agent MUST
        ALWAYS warn the user explicitly about the potential extra billing costs
        of BOTH the Online Monitor (specifically mentioning **LLM evaluations**)
        and Telemetry (specifically mentioning **Cloud Trace/Cloud Logging
        export**). You MUST STOP and ask for explicit approval before proceeding
        with provisioning or providing setup commands.

### 2. Prerequisites & Dependencies

#### Agent Telemetry

*   **Disclaimer**: For Reliability, Cost, Safety, and Security alerts to
    function, the underlying agent MUST be instrumented to emit OpenTelemetry
    (OTel) metrics. If the agent does not emit these metrics, the alerting
    policies will have no data stream to evaluate.

#### Python Environment

Before executing any python script in this skill you MUST install the required
dependencies in your environment. Run this command first:

```bash
pip install -r scripts/requirements.txt
```

### 3. Input Assumptions

*   **Explicit Project Adherence**: You must ONLY configure alerts, query
    telemetry, or interact with the Google Cloud Project(s) explicitly provided
    by the user in the prompt. Do NOT assume or use other projects from your
    environment or history unless the user explicitly directs you to do so.
*   **Sequential File Transformations**: If the user explicitly asks to copy a
    file and then modify it, you MUST perform these actions sequentially (copy
    first, then modify) rather than writing the final content directly.

### 4. Execution Steps

1.  **Mandatory Prerequisite Execution Protocol (SEQUENTIAL)**: Before
    generating or writing ANY configuration, you MUST execute these steps in
    order:
    1.  **Step 1: Streamlined Discovery (Mandatory)**: Run
        `gather_agent_info.py` to automatically identify agent runtime, verify
        telemetry, metric scopes, linked datasets, and more. This script covers
        most of the manual verifications listed in subsequent steps.
        *   Command: `python3 scripts/gather_agent_info.py --project-id
            {project_id} --agent-name {agent_name}`
        *   **Note**: If this script **fails**, returns **partial data**, or
            doesn't produce everything you need, you MUST satisfy requirements
            by running the manual fallback steps listed in Step 2 and then
            perform Step 3 below. If Step 1 succeeds and provides all info,
            **SKIP** to Step 3 (Pre-existing Policies Verification).
    2.  **Step 2: Metric Scope Verification (Fallback)**: Run this ONLY if Step
        1 failed to determine the metric scope.
        *   **Action A (CLI)**: Run `gcloud beta monitoring metrics-scopes list
            projects/{project_id}`. If a scoping project is returned, you MUST
            deploy policies there.
        *   **Action B (Code Scan)**: Search Terraform configurations for
            `google_monitoring_monitored_project` resources to extract the
            scoping project.
        *   **Action C (Fallback)**: If ambiguous, ASK the user: "Are you using
            a multi-project Cloud Monitoring Metric Scope? If so, what is the
            scoping project ID?"
    3.  **Step 3: Pre-existing Policies Verification**: Avoid duplicates.
        *   **Action**: Scan the target directory to see if aggregated policies
            already exist targeting the same metrics (grouped by
            `reasoning_engine_id` or `gen_ai_agent_name`). Use
            `scan_duplicates.py` to verify.
2.  **Alert Policy Type Resource Files**: You MUST list and read files under
    `references/` with names ending in `_alert_policies.md` to learn how to
    configure alert policies based on type. By default you MUST configure all of
    the following alert types UNLESS the user requests to generate explicit
    alert policies and/or types. Follow their tables of content to help you find
    the reference sections you need to read:

    Alert Type      | Reference File
    :-------------- | :-------------
    **Reliability** | [reliability_alert_policies.md](references/reliability_alert_policies.md)
    **Quality**     | [quality_alert_policies.md](references/quality_alert_policies.md)
    **Cost**        | [cost_alert_policies.md](references/cost_alert_policies.md)
    **Safety**      | [safety_alert_policies.md](references/safety_alert_policies.md)
    **Security**    | [security_alert_policies.md](references/security_alert_policies.md)

### 5. Outputs & Formats

*   **Always configure the supported alerting policies** for the target agent:
    *   **For Reliability Monitoring**: You MUST configure exactly five alerting
        policies:
        1.  **Latency** (anomaly monitoring)
        2.  **Error Rate - Fast Burn SLO** (1-Hour Window)
        3.  **Error Rate - Slow Burn SLO** (3-Day Window)
        4.  **Model Call Error Rate** (SQL-based Observability Analytics
            Alerting)

From google/skills, Apache-2.0.

More from google/skills