feat(market-research-agent): add multi-agent market research sample

contrib/python/market-research-agent/.env.example

@@ -0,0 +1,17 @@
+# 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)
+# GOOGLE_GENAI_USE_VERTEXAI=true
+# GOOGLE_CLOUD_PROJECT=your-gcp-project-id
+# GOOGLE_CLOUD_LOCATION=us-central1
+# 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

contrib/python/market-research-agent/README.md

@@ -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.

contrib/python/market-research-agent/app/__init__.py

@@ -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()

contrib/python/market-research-agent/app/agent.py

@@ -0,0 +1,46 @@
+# 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.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),
+    ],
+)

contrib/python/market-research-agent/app/prompt.py

@@ -0,0 +1,47 @@
+# 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.
+
+"""System prompt for the market research orchestrator agent."""
+
+ORCHESTRATOR_PROMPT = """You are a market research pipeline orchestrator. You coordinate specialist agents to produce a comprehensive market research report for any location and business type.
+
+## Your workflow
+
+**Step 1 — Geocode**
+Call `geocode_address` with the user's address to get lat/lng coordinates.
+
+**Step 2 — Run all four analyses in parallel**
+In a SINGLE response, call ALL FOUR specialist agents at once using the coordinates from Step 1:
+- `competitor_agent`: finds and scores all nearby competitors
+- `location_agent`: scores location suitability (0-100)
+- `traffic_agent`: estimates foot traffic and busy hours
+- `gap_agent`: identifies underserved market opportunities
+
+Pass each agent a clear task description including the lat, lng, business_type, and radius_meters.
+
+**Step 3 — Synthesize**
+After receiving all four JSON results, synthesize them into a final report and present it clearly to the user.
+
+## Synthesis output format
+
+Present the report in clear, readable prose with structured sections:
+
+1. **Executive Summary** — 2-3 sentence overview of the market opportunity
+2. **Competitors** — table or list of top competitors with scores
+3. **Location Score** — overall score and breakdown of the three dimensions
+4. **Traffic Estimate** — peak hours, busiest day, footfall level, confidence
+5. **Market Gaps** — ranked opportunities with scores and evidence
+6. **Recommendations** — 2-3 actionable next steps
+
+Always ground your synthesis in the actual data returned by the specialist agents."""

contrib/python/market-research-agent/app/sub_agents/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+
+"""Specialist sub-agents for market research."""
+
+from .competitor.agent import competitor_agent
+from .gap.agent import gap_agent
+from .location.agent import location_agent
+from .traffic.agent import traffic_agent

contrib/python/market-research-agent/app/sub_agents/competitor/__init__.py

@@ -0,0 +1,17 @@
+# 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.
+
+"""Competitor analysis sub-agent."""
+
+from .agent import competitor_agent

contrib/python/market-research-agent/app/sub_agents/competitor/agent.py

@@ -0,0 +1,35 @@
+# 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.
+
+"""Competitor analysis sub-agent."""
+
+import os
+
+from google.adk.agents import LlmAgent
+
+from ...tools.places import nearby_search, place_details, text_search
+from .prompt import COMPETITOR_PROMPT
+
+competitor_agent = LlmAgent(
+    name="competitor_agent",
+    model=os.getenv("MODEL_NAME"),
+    description=(
+        "Finds and scores all nearby competitors for a given business type "
+        "at a target location. Input: task description with lat, lng, "
+        "business_type, and radius_meters. "
+        "Output: JSON array of competitor objects with competitive scores."
+    ),
+    instruction=COMPETITOR_PROMPT,
+    tools=[nearby_search, place_details, text_search],
+)