---
spec_name: "Gemini 3.5 Flash QA Agent"
version: 1.0
author: "Mike Kwal"
description: "An agent that performs a UX and functionality audit on a given URL using Gemini 3.5 Flash with the Computer Use tool."
---

## Overview

This spec configures an AI agent to act as a Quality Assurance (QA) tester. It will navigate to a web page, visually inspect it against a checklist, and return a structured JSON report of any issues found.

This is designed to be run from a local machine with Python and the Google Generative AI SDK installed.

## 1. System Prompt

This prompt establishes the agent's persona and core instructions. It tells the AI *what it is* and *how it should behave*.

```text
You are a meticulous Quality Assurance (QA) agent specializing in website user experience (UX) and functionality audits. Your task is to open a provided URL, visually inspect the page, and report on specific criteria. You must navigate the page as a human would, checking for visual consistency, clarity, and errors.

Your output must be a single, valid JSON object. The object should have a top-level key named "issues", which contains an array. Each item in the array represents a single issue found and must have the following keys:
- "issue_type": (String) e.g., "Broken Link", "CTA Clarity", "Visual Bug", "Content Gap".
- "severity": (String) "Low", "Medium", or "High".
- "description": (String) A clear, concise description of the problem.
- "suggested_fix": (String) An actionable suggestion for how to fix the issue.

Do not include any other text or explanation outside of the final JSON object.
```

## 2. User Prompt Template

This is the template for the specific task. You will replace `{{URL_TO_AUDIT}}` with the actual URL you want to test.

```text
Audit the landing page at the following URL: {{URL_TO_AUDIT}}

Use the Computer Use tool to open the page in a browser and perform the following checks:

1.  **Broken Links:** Click every navigation link (in the header and footer) and all primary call-to-action (CTA) buttons. Report any that lead to a 404 page, an error, or the wrong destination. Severity: High.
2.  **CTA Clarity:** Read the text on all primary buttons. Report if any are vague (e.g., 'Click Here', 'Submit', 'Learn More') instead of benefit-oriented (e.g., 'Get Your Free Trial', 'Download the Guide'). Severity: Medium.
3.  **Visual Regressions:** Scan the entire page for any obvious visual bugs. Look for overlapping text, broken images, misaligned elements, or horizontal scrollbars on the body. Severity: High for broken elements, Medium for alignment issues.
4.  **Content Gaps:** Read the main headline and the sub-headline. Report if they do not clearly state what the product/service is and who it is for within the first 5 seconds of reading. Severity: Medium.

Return your findings as a single JSON object based on the format defined in your system instructions.
```

## 3. Python Execution Script

This script uses the `google-generativeai` library to run the agent. Save it as a `.py` file.

```python
import os
import google.generativeai as genai

# --- CONFIGURATION ---
# It's recommended to set your API key as an environment variable
# For example: export GOOGLE_API_KEY='your-key-here'
API_KEY = os.getenv("GOOGLE_API_KEY")
URL_TO_AUDIT = "https://example.com" # <-- CHANGE THIS TO THE URL YOU WANT TO TEST

# --- PROMPTS ---
SYSTEM_PROMPT = """ ... PASTE SYSTEM PROMPT FROM SECTION 1 HERE ... """
USER_PROMPT = f"""Audit the landing page at the following URL: {URL_TO_AUDIT} ... PASTE THE REST OF THE USER PROMPT HERE ..."""

# --- EXECUTION ---
def run_qa_agent():
    if not API_KEY:
        print("Error: GOOGLE_API_KEY environment variable not set.")
        return

    try:
        genai.configure(api_key=API_KEY)

        model = genai.GenerativeModel(
            'gemini-3.5-flash',
            tools=[genai.tool.computer_use_tool.ComputerUseTool()],
        )

        print(f"Starting QA audit for: {URL_TO_AUDIT}\n...")
        chat = model.start_chat()
        chat.send_message(SYSTEM_PROMPT)

        response = chat.send_message(USER_PROMPT)

        print("\n--- AUDIT COMPLETE ---")
        print(response.text)
        print("----------------------")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    run_qa_agent()
```

### How to Run

1.  Install the library: `pip install -q google-generativeai`
2.  Set your API key as an environment variable.
3.  Replace the `URL_TO_AUDIT` in the script.
4.  Run the script from your terminal: `python your_script_name.py`
5.  The script will take control of your mouse and keyboard to perform the audit in a new browser window. Do not interfere with it while it's running.