Repository navigation
feat(market-research-agent): restore recipe as a deployable contrib recipe #2831
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
nikhithajoy
wants to merge
5
commits into
google:main
Choose a base branch
from
nikhithajoy:feat/market-research-agent-deployable
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
fdbc5b8
feat(market-research-agent): restore recipe as a deployable contrib r…
nikhithajoy 8f433d2
fix(market-research-agent): declare serving env vars and patch depend…
nikhithajoy 9b45b26
Merge remote-tracking branch 'upstream/main' into feat/market-researc…
nikhithajoy a74103b
fix(market-research-agent): patch new dependency CVEs and drop osv-sc…
nikhithajoy 5d8879e
fix(market-research-agent): address review bot findings (non-root con…
nikhithajoy File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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= |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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"] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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
22
contrib/python/market-research-agent/agents-cli-manifest.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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() |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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") |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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
USERbefore the container entrypoint? The container currently runs as root.