Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions contrib/python/market-research-agent/.dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Build context exclusions. Keeping .venv/ out is not optional: every recipe
# in this repo has one in-tree, and copying it into the image both bloats it
# and can shadow the container's own site-packages.
.venv/
venv/
__pycache__/
*.py[cod]
*.egg-info/
.pytest_cache/
.mypy_cache/
.ruff_cache/

# Never bake credentials into an image. .env.example is safe and stays.
.env

.git/
.gitignore
.DS_Store
32 changes: 32 additions & 0 deletions contrib/python/market-research-agent/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Google AI / Vertex AI — pick one mode:

# Option A: Google AI Studio (simpler, no GCP project needed)
GOOGLE_GENAI_USE_VERTEXAI=false
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY_HERE

# Option B: Vertex AI (production). Set GOOGLE_GENAI_USE_VERTEXAI=true and
# fill in the project and location below. Leave them empty for Option A.
GOOGLE_CLOUD_PROJECT=
GOOGLE_CLOUD_LOCATION=
# GOOGLE_CLOUD_STORAGE_BUCKET=your-bucket # Only for Agent Engine deployment

# Google Places API (required for location data)
GOOGLE_PLACES_API_KEY=YOUR_GOOGLE_PLACES_API_KEY_HERE

# Model used by the orchestrator and all sub-agents.
MODEL_NAME=gemini-3.5-flash

# Serving & container configuration (app/fast_api_app.py, app/app_utils/).
# All optional: leave empty to use in-memory sessions and artifacts.
AGENT_VERSION=0.1.0
APP_URL=http://0.0.0.0:8000
# Comma-separated list of allowed CORS origins.
ALLOW_ORIGINS=
# Persistent sessions: a database URI, or an Agent Engine ID and region.
SESSION_SERVICE_URI=
GOOGLE_CLOUD_AGENT_ENGINE_ID=
GOOGLE_CLOUD_AGENT_ENGINE_LOCATION=
# GCS bucket for artifacts.
LOGS_BUCKET_NAME=
# Set to any value to disable Cloud telemetry export during tests.
INTEGRATION_TEST=
41 changes: 41 additions & 0 deletions contrib/python/market-research-agent/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM python:3.11-slim

RUN pip install --no-cache-dir uv==0.8.13

# Run as an unprivileged user rather than root.
RUN useradd --create-home --uid 1000 appuser

WORKDIR /code
RUN chown appuser:appuser /code

COPY --chown=appuser:appuser ./pyproject.toml ./README.md ./uv.lock* ./

COPY --chown=appuser:appuser ./app ./app

USER appuser

RUN uv sync --frozen

ARG AGENT_VERSION=0.0.0
ENV AGENT_VERSION=${AGENT_VERSION}
# Base URL advertised in the A2A agent card; override with the public
# service URL when deploying.
ENV APP_URL=http://0.0.0.0:8080

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "app.fast_api_app:app", "--host", "0.0.0.0", "--port", "8080"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MAJOR] Can you please add a non-root USER before the container entrypoint? The container currently runs as root.

138 changes: 138 additions & 0 deletions contrib/python/market-research-agent/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# Market Research Agent

An AI-powered market research system that performs comprehensive competitive analysis for any location and business type. Given an address and business category, it runs four specialist agents in parallel — analyzing competitors, scoring location suitability, estimating foot traffic, and identifying market gaps — then synthesizes everything into a structured report.

## Agent Details

| Feature | Description |
| --- | --- |
| **Interaction Type** | Conversational |
| **Complexity** | Advanced |
| **Agent Type** | Multi Agent |
| **Components** | LlmAgent, AgentTool, FunctionTool, Google Places API |
| **Vertical** | Retail / Business Analytics |

### Architecture

```
market_research_orchestrator (LlmAgent)
├── geocode_address (FunctionTool)
├── competitor_agent (AgentTool → LlmAgent)
│ └── nearby_search, place_details, text_search
├── location_agent (AgentTool → LlmAgent)
│ └── nearby_search, text_search, geocode_address
├── traffic_agent (AgentTool → LlmAgent)
│ └── nearby_search, place_details
└── gap_agent (AgentTool → LlmAgent)
└── nearby_search, text_search, place_details
```

The orchestrator geocodes the input address, then calls all four specialist agents in parallel via `AgentTool`. Each specialist uses Google Places API tools to gather real-world data and returns structured JSON. The orchestrator synthesizes the results into a final market research report.

## Setup and Installation

### Prerequisites

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/) for dependency management
- A Google AI Studio API key **or** a Google Cloud project with Vertex AI enabled
- A [Google Places API key](https://developers.google.com/maps/documentation/places/web-service/get-api-key)

### Installation

```bash
# Clone the repo
git clone https://github.com/google/adk-samples.git
cd adk-samples/contrib/python/market-research-agent

# Install dependencies
uv sync
```

### Configuration

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

**Option A — Google AI Studio (simplest):**
```bash
GOOGLE_GENAI_USE_VERTEXAI=false
GOOGLE_API_KEY=your_google_api_key
GOOGLE_PLACES_API_KEY=your_places_api_key
```

**Option B — Vertex AI:**
```bash
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_PLACES_API_KEY=your_places_api_key
```

If using Vertex AI, authenticate your GCloud account:
```bash
gcloud auth application-default login
gcloud auth application-default set-quota-project $GOOGLE_CLOUD_PROJECT
```

Both options also require `MODEL_NAME` (defaults to `gemini-3.5-flash` in `.env.example`), which is used by the orchestrator and every sub-agent.

## Running the Agent

**With the ADK web UI:**
```bash
uv run adk web
```

**With the ADK CLI:**
```bash
uv run adk run app
```

### Example Interaction

```
You: Analyze the market for opening a specialty coffee shop at 15 Shoreditch High Street, London

Agent: I'll research the market at that location. Let me geocode the address and run
the full analysis...

[Runs competitor, location, traffic, and gap analysis in parallel]

Here is the market research report:

**Executive Summary**
Shoreditch High Street is a high-footfall urban corridor with 8 direct competitors
within 500m. Location scores 71/100 overall. Strong morning commuter traffic
detected. Key opportunity: zero third-wave specialty roasters in the area despite
high review volumes at existing cafes.

**Competitors (8 found)**
...

**Location Score: 71/100**
- Competition density: 52/100 (saturated)
- Accessibility: 89/100 (2 tube stations within 400m)
- Demand signal: 72/100

**Traffic Estimate**
Peak hours: 7:30–9:30am and 12–2pm weekdays
Estimated daily footfall: High | Confidence: Medium

**Market Gaps**
1. Specialty/third-wave coffee (score: 85) — 0 roasters found in 1km radius
2. Evening study cafe (score: 67) — competitors close by 6pm
```

## Running Tests

```bash
uv run pytest tests/ -v
```

## Disclaimer

This agent is provided as a sample for demonstration purposes. Market research outputs are estimates based on publicly available Google Places data and should not be used as the sole basis for business decisions.
22 changes: 22 additions & 0 deletions contrib/python/market-research-agent/agents-cli-manifest.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# agents-cli project manifest (agents-cli 1.x reads this file).
#
# Written by the make-python-recipe-deployable repo skill — NOT by an
# agents-cli scaffold. `acli_version`, `generated_at` and `base_template` are
# deliberately omitted rather than invented: no scaffold produced this recipe,
# and a fabricated version makes agents-cli offer a `scaffold upgrade` that
# cannot work. agents-cli treats an absent version as "unknown" and falls back
# to generic guidance, which is the accurate outcome here.
#
# `agents-cli deploy` uses this file as the project-root marker and reads
# `deployment_target` to choose how to deploy.
name: "market-research-agent"
agent_directory: "app"
language: "python"
region: "us-central1"
create_params:
deployment_target: "cloud_run"
session_type: "in_memory"
is_a2a: true
cicd_runner: "skip"
agent_gateway: false
agent_guidance_filename: "AGENTS.md"
24 changes: 24 additions & 0 deletions contrib/python/market-research-agent/app/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Market Research Agent — multi-agent market analysis using Google Places API."""

from dotenv import load_dotenv

# Load variables from .env if present. In production the environment is
# already populated by the platform (Cloud Run, GKE, etc.), so a missing
# .env is expected and not an error.
load_dotenv()

from . import agent # noqa: E402 -- must come after load_dotenv()
49 changes: 49 additions & 0 deletions contrib/python/market-research-agent/app/agent.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Market Research Agent — orchestrator and root agent definition."""

import os

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.agent_tool import AgentTool

from .prompt import ORCHESTRATOR_PROMPT
from .sub_agents.competitor.agent import competitor_agent
from .sub_agents.gap.agent import gap_agent
from .sub_agents.location.agent import location_agent
from .sub_agents.traffic.agent import traffic_agent
from .tools.places import geocode_address

root_agent = LlmAgent(
name="market_research_orchestrator",
model=os.getenv("MODEL_NAME"),
description=(
"Performs comprehensive market research for any location and business "
"type. Geocodes the address, runs competitor analysis, location "
"scoring, traffic estimation, and gap analysis in parallel, then "
"synthesizes the results into an actionable report."
),
instruction=ORCHESTRATOR_PROMPT,
tools=[
geocode_address,
AgentTool(agent=competitor_agent),
AgentTool(agent=location_agent),
AgentTool(agent=traffic_agent),
AgentTool(agent=gap_agent),
],
)

app = App(root_agent=root_agent, name="app")
Loading
Loading