Secure AI Shopping Assistant (ADK 2.0)

A secure, production-grade retail Shopping Assistant built with Google's Agent Development Kit (ADK) 2.0 and Gemini, developed inside Google Antigravity IDE using a security-first, Test-Driven Development (TDD) lifecycle.

This project showcases how to "shift security left" by integrating automated local code-level gates, role-based access controls, and threat-modeling skills into the agent's development workflow.

• LlmAgent & Workflows: Configured root_agent using ADK's modular LlmAgent and Workflow nodes to process customer queries and dispatch tool executions.
• Gemini Models: Powered by Gemini models through a custom APIKeyGemini client with built-in retry and API key handling.

• STRIDE Threat Modeling Skill: A custom, declarative skill registered in .agents/skills/stride-threat-model/SKILL.md that leverages the agent to perform threat assessments across the six STRIDE pillars (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) and outputs a detailed threat_model.md report.
• TDD Planning Gate (.agents/CONTEXT.md): A persistent project context file instructing the agent to include a dedicated Security Boundaries & Assertions section in every implementation plan before writing any code.

• Git Pre-Commit Hook (.pre-commit-config.yaml): Automatically intercepts git commit actions to execute local checks:
  • end-of-file-fixer and trailing-whitespace for code formatting.
  • semgrep for local static security scanning.
• Custom Semgrep Scan (.semgrep/rules.yaml): Enforces a custom regex pattern (AIzaSy[A-Za-z0-9_\-]*) to block any hardcoded Google API credentials from being committed to version control.
• Agent Execution Hook (.agents/hooks.json): An IDE-level PreToolUse event interceptor that passes command strings through .agents/scripts/validate_tool_call.py to block destructive shell commands (like rm -rf /).

• Role-Based Access Control (RBAC): RESTRICTS administrative commands (like update_discount_status) to verified admin identifiers (ADMIN_USERS).
• Input Schema Validation: Leverages strict Pydantic schemas (AwardLoyaltyPointsArgs, UpdateDiscountStatusArgs) for all tool entry points, preventing type injection and out-of-bounds parameters (e.g. awarding negative loyalty points).
• Outcome-Based Security Testing: A robust pytest suite (tests/test_agent.py) and assertion suite (.agents/scripts/test_assertions.py) verifying security state outcomes (single-use limits, registration checks, casing normalization, and inactive code blocks) without fragile mocking.

1. Shift Security Left: Caught and refactored a simulated credentials leak locally before pushing code, avoiding remote CI/CD failures and production leaks.
2. Autonomous Remediation Loops: Experienced how an agent can intercept pre-commit failures, read error logs, apply secure code-level refactors, run unit tests, and retry commits autonomously.
3. Threat Modeling AI Agents: Evaluated model architectures against specialized agent threats (e.g. prompt injection, unauthorized tool access, API spoofing, and state race conditions).
4. Enforcing the "Paved Road": Centralized approved coding standards inside CONTEXT.md to prevent context rot, reduce model reasoning latency, and keep tool implementations secure-by-default.

secure-agent-lab/ (Git Repository Root)
├── .agents/
│   ├── CONTEXT.md               # Secure coding standards & TDD planning gate instructions
│   ├── hooks.json               # PreToolUse hooks configuration
│   └── scripts/
│       ├── test_assertions.py   # State verification assertions script
│       └── validate_tool_call.py# Shell command security gating script
├── .semgrep/
│   └── rules.yaml               # Custom Semgrep rule for hardcoded Google API Keys
├── app/
│   ├── agent.py                 # Core agent workflow, RBAC rules, & tool logic
│   └── app_utils/               # Telemetry and typing helpers
├── tests/
│   ├── integration/             # Integration/e2e streaming tests
│   ├── unit/                    # Placeholder unit tests
│   └── test_agent.py            # Outcome-based security pytest suite
├── .pre-commit-config.yaml      # Git hook configuration for Semgrep & formatting
├── pyproject.toml               # Poetry/UV dependency configuration & Pytest options
└── README.md                    # This architecture and learning guide

Ensure you have uv and google-agents-cli installed. Run:

uvx google-agents-cli setup
agents-cli install

Run the pytest suite to verify all business rules and security boundaries:

uv run pytest tests/test_agent.py

You can test the formatting and static analysis checks against all project files:

uv run pre-commit run --all-files --config .pre-commit-config.yaml

Export your actual GEMINI_API_KEY and start the interactive chat UI:

export GEMINI_API_KEY="your-actual-api-key"
agents-cli playground

Open http://127.0.0.1:8080/dev-ui/?app=app in your browser.