Secure Agent Lab: Shopping Assistant

A secure shopping assistant agent built using the Agent Development Kit (ADK) and the Google GenAI SDK. This project showcases structured ReAct agent logic, security/business boundaries, and outcome-based unit/integration testing.

Project Structure

secure-agent-lab/
├── shopping-assistant/       # Core shopping assistant project
│   ├── app/                  # Main agent logic and tools
│   │   ├── agent.py          # Agent initialization and Custom Gemini client
│   │   └── tools.py          # Store state, Pydantic validation, and tools
│   ├── tests/                # Testing suite
│   │   ├── test_agent.py     # Outcome-based security & logic tests
│   │   └── conftest.py       # Pytest fixtures and configs
│   ├── pyproject.toml        # uv dependencies and tool configurations
│   └── README.md             # Subproject readme
├── threat_model.md           # STRIDE Threat Modeling assessment
└── README.md                 # Root project readme (this file)

---

Features & Security Boundaries

1. Role-Based Authorization Policies:

   • Only pre-registered administrators (admin-123, admin-456) are authorized to change discount code statuses via the update_discount_status tool. Regular users are blocked.

2. Idempotency Guardrails:

   • Loyalty points cannot be awarded more than once for the same purchase_id to prevent double-claiming exploits.

3. Data & Registration Integrity Checks:

   • The agent requires a registered user_id to redeem discount codes.
   • Points awarded via award_loyalty_points must be strictly positive integers.

4. Multi-Model API Compatibility:

   • Dynamically supports both Google Cloud Vertex AI (default) and Google AI Studio (GEMINI_API_KEY) to bypass project billing restrictions.

---

Getting Started

Prerequisites

• uv: Python package manager - Install uv
• agents-cli: Google Agents CLI - Install with uv tool install google-agents-cli

Running the Playground

You can run the interactive agent playground locally using either Google Cloud credentials or a Google AI Studio API key.

Option A: Google AI Studio API Key (Recommended if billing is not enabled on GCP)

Get a free API key from Google AI Studio and run:

cd shopping-assistant
export GEMINI_API_KEY="your_ai_studio_api_key"
agents-cli playground

Option B: Google Cloud Vertex AI (Default)

Ensure your gcloud project has billing enabled and run:

cd shopping-assistant
gcloud auth application-default login
agents-cli playground

Once running, navigate to http://127.0.0.1:8080/dev-ui/?app=app to interact with the agent.

---

Running Tests

To verify that the agent's security guardrails are functioning and correctly handling simulated LLM turns, run the test suite:

cd shopping-assistant
uv run pytest tests/test_agent.py