You'll need a Google AI Studio API Key.

Clone the repository and cd into the project directory.

git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/retail-ai-location-strategy

Create a .env file in the app folder with your API keys (see .env.example for reference):

echo "GOOGLE_GENAI_USE_VERTEXAI=FALSE" >> app/.env
echo "GOOGLE_API_KEY=YOUR_AI_STUDIO_API_KEY" >> app/.env
echo "MAPS_API_KEY=YOUR_MAPS_API_KEY" >> app/.env

From the retail-ai-location-strategy directory, install dependencies and start the server.

make install && make dev

1. Open http://localhost:8501 in your browser
2. Select "app" from the agent dropdown
3. Type a query like: "I want to open a coffee shop in Indiranagar, Bangalore"
4. Watch the 7-stage pipeline execute:
   • Intake → Extract location and business type
   • Market Research → Web search for demographics and trends
   • Competitor Mapping → Google Maps Places API for competitors
   • Gap Analysis → Python code execution for viability scores
   • Strategy Advisor → Extended reasoning for recommendations
   • Report Generator → HTML executive report
   • Infographic Generator → Visual summary image

Your agent is now running at http://localhost:8501.

Use the Agent Starter Pack to create a production-ready project with deployment scripts. This is ideal for cloud deployment scenarios.

You'll need: Google Cloud SDK and a Google Cloud Project with the Vertex AI API enabled.

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> app/.env
echo "GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID" >> app/.env
echo "GOOGLE_CLOUD_LOCATION=us-central1" >> app/.env
echo "MAPS_API_KEY=YOUR_MAPS_API_KEY" >> app/.env

gcloud auth application-default login

This command uses the Agent Starter Pack to create a new directory (my-retail-agent) with all the necessary code.

uvx agent-starter-pack create my-retail-agent -a adk@retail-ai-location-strategy

The starter pack will prompt you to select deployment options and provides additional production-ready features including automated CI/CD deployment scripts.

# Create and activate a virtual environment
python -m venv .venv && source .venv/bin/activate # On Windows: .venv\Scripts\activate

# Install the starter pack and create your project
pip install --upgrade agent-starter-pack
agent-starter-pack create my-retail-agent -a adk@retail-ai-location-strategy

Navigate into your newly created project folder, then install dependencies and start the server.

cd my-retail-agent && make install && make dev

Your agent is now running at http://localhost:8501.

Note: Cloud deployment applies only to projects created with agent-starter-pack (Option B).

Prerequisites:

gcloud components update
gcloud config set project YOUR_PROJECT_ID

Deploy with the built-in adk-web interface:

make deploy IAP=true

After deployment, grant users access to your IAP-protected service by following the Manage User Access documentation.

For production deployments with CI/CD, see the Agent Starter Pack Development Guide.

This agent supports multiple Gemini model families. Edit app/config.py to switch models based on your access and quota:

Gemini 3 Documentation:

• Vertex AI - Get started with Gemini 3
• Google AI - Gemini 3 API

To use Gemini 3 text models, uncomment Option 2 in app/config.py:

# app/config.py

# Comment out Option 1 (2.5 Pro)
# FAST_MODEL = "gemini-2.5-pro"
# ...

# Uncomment Option 2 (3 Pro Preview)
FAST_MODEL = "gemini-3-pro-preview"
PRO_MODEL = "gemini-3-pro-preview"
CODE_EXEC_MODEL = "gemini-3-pro-preview"
IMAGE_MODEL = "gemini-3-pro-image-preview"

Note: If you encounter 503 UNAVAILABLE - model overloaded errors with Gemini 3, switch back to Gemini 2.5 Pro for better reliability.

Want a richer experience beyond the default ADK web UI? This agent includes an optional AG-UI Protocol frontend built with CopilotKit that provides:

• Real-time Pipeline Timeline: Watch the 7-stage analysis unfold with collapsible steps
• Generative UI: Rich visualizations appear in the chat as the agent works
• Interactive Dashboard: Location scores, competitor stats, market characteristics
• Bidirectional State Sync: Frontend and ADK agent share state in real-time

# First time: Install frontend dependencies
make ag-ui-install

# Run both backend and frontend servers
make ag-ui

This starts:

• Backend at http://localhost:8000 (FastAPI + ADK agent)
• Frontend at http://localhost:3000 (Next.js + CopilotKit)

Open http://localhost:3000 to see the interactive dashboard.

# Terminal 1: Start the backend
cd app/frontend/backend
uv pip install -r requirements.txt
uv run main.py
# Runs at http://localhost:8000

# Terminal 2: Start the frontend
cd app/frontend
npm install
cp .env.local.example .env.local
npm run dev
# Runs at http://localhost:3000

See app/frontend/README.md for detailed frontend documentation.

The pipeline is built as a SequentialAgent that orchestrates 7 specialized sub-agents, each handling a specific phase of the analysis.

Each agent reads from and writes to a shared session state, enabling seamless data flow between stages:

retail-ai-location-strategy/
├── Makefile                          # Build and run commands
├── pyproject.toml                    # Dependencies and package config
├── .env.example                      # Environment template
├── README.md                         # This file
├── DEVELOPER_GUIDE.md                # Detailed developer documentation
│
├── notebook/                         # Original Gemini API notebook
│   └── retail_ai_location_strategy_gemini_3.ipynb
│
└── app/                              # Agent package (exported as root_agent)
    ├── __init__.py                   # Exports root_agent for ADK discovery
    ├── agent.py                      # SequentialAgent pipeline definition
    ├── config.py                     # Model selection and retry config
    ├── .env                          # Environment variables (from .env.example)
    │
    ├── sub_agents/                   # 7 specialized agents
    │   ├── competitor_mapping/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   ├── gap_analysis/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   ├── infographic_generator/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   ├── intake_agent/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   ├── market_research/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   ├── report_generator/
    │   │   ├── __init__.py
    │   │   └── agent.py
    │   └── strategy_advisor/
    │       ├── __init__.py
    │       └── agent.py
    │
    ├── tools/                        # Custom function tools
    │   ├── places_search.py          # Google Maps Places API
    │   ├── html_report_generator.py  # Executive report generation
    │   └── image_generator.py        # Infographic generation
    │
    ├── schemas/                      # Pydantic output schemas
    ├── callbacks/                    # Pipeline lifecycle callbacks
    └── frontend/                     # AG-UI interactive dashboard

For detailed documentation, see DEVELOPER_GUIDE.md:

• The Business Problem - Why this exists
• Architecture Deep Dive - State flow and agent communication
• Agents and Tools - Sub-agents, tools, callbacks, schemas
• Configuration - Model selection and retry options
• Troubleshooting - Common issues and fixes

If you encounter issues while setting up or running this agent, here are some resources to help you troubleshoot:

• ADK Documentation: Comprehensive documentation for the Agent Development Kit
• Vertex AI Authentication Guide: Detailed instructions for setting up authentication
• Agent Starter Pack Troubleshooting: Common issues

Based on the original Retail AI Location Strategy notebook by Lavi Nigam and Deepak Moonat.

This agent sample is provided for illustrative purposes only. It serves as a basic example of an agent and a foundational starting point for individuals or teams to develop their own agents.

Users are solely responsible for any further development, testing, security hardening, and deployment of agents based on this sample. We recommend thorough review, testing, and the implementation of appropriate safeguards before using any derived agent in a live or critical system.

Apache 2.0 - See LICENSE for details.