docs(deep-search): fix cloud deployment instructions and scaffold path (#2575) by Anurag-M1 · Pull Request #2629 · google/adk-recipes

Anurag-M1 · 2026-09-12T14:56:33Z

What

Fixes #2575. Updates core/python/deep-search/README.md to resolve broken scaffolding and cloud deployment instructions, clarifies backend container vs custom React UI serving architecture, and removes unused imports in documentation code snippets.

Why

agents-cli create -a adk@deep-search fails with FileNotFoundError because the shorthand points to the legacy path python/agents/deep-search, which was removed in Delete old recipes which already have been copied to core or contrib #2618 when recipes moved to core/.
The local clone instructions referenced the stale path adk-samples/python/agents/deep-search.
The Cloud Deployment section instructed users to run non-existent Makefile commands (make deploy IAP=true and make deploy IAP=true PORT=5173).
Option 2 linked to the bare repo root of google/agents-cli for a non-existent "Deploy UI Guide", leaving users confused about how the React frontend communicates with the agent backend.
As confirmed by maintainers in [BUG]: python/agents/deep-search README Cloud Deployment section is broken #2575, the default generated container is backend-only. Users wishing to deploy the React frontend need a multi-stage Dockerfile and static file mount in FastAPI.

How it works

Scaffold & Clone Commands (core/python/deep-search/README.md):
- Replaced adk@deep-search with the full URL: https://github.com/google/adk-samples/tree/main/core/python/deep-search.
- Updated the local clone path from adk-samples/python/agents/deep-search to adk-samples/core/python/deep-search.
Cloud Deployment (core/python/deep-search/README.md):
- Replaced non-existent make deploy targets with agents-cli deploy --iap and agents-cli deploy.
- Clarified the frontend-backend communication pattern (local Vite dev proxy vs production static files).
- Inlined a clean, production-ready multi-stage Dockerfile showing how to build the Vite/React frontend and bundle it with the FastAPI backend.
- Provided the clean code snippet to mount static files in app/fast_api_app.py.

Testing

Verified locally with full test and validation suites:

$ uv run python tools/validate_readme.py core/python/deep-search
[PASS] All 1 recipe README(s) are present and valid.

$ uv run python tools/validate_structure.py core/python/deep-search
[PASS] All 1 recipe(s) passed structural checks.

$ uv run python3 .github/scripts/check_env_vars.py core/python/deep-search
[PASS] core/python/deep-search/.env.example: every environment variable read in Python source is declared (3 detected, 0 in the OS allowlist, 3 declared).

$ uv run --no-project --with pyyaml --with packaging python3 .github/scripts/check_recipe_pyproject.py core/python/deep-search
[PASS] core/python/deep-search/pyproject.toml: name, requires-python, description and default index all satisfy the repo rules.

$ git diff --name-only origin/main...HEAD | uv run python tools/check_frozen_paths.py
[PASS] No changes inside retired recipe folders.

$ uv run python tools/validate_placement.py
[PASS] Every recipe under skills/ is correctly placed.

google#2575)

github-actions

Automated Maintainability review — 1 finding(s).

github-actions · 2026-09-12T14:57:36Z


-    critic_model: str = os.getenv("MODEL_NAME")
-    worker_model: str = os.getenv("MODEL_NAME")
+    critic_model: str = os.getenv("MODEL_NAME", "gemini-3.5-flash")


Avoid using hardcoded defaults on environment variable reads. There are two instances in this file; default values should be documented in .env.example instead.

github-actions

Automated Correctness review — 2 finding(s).

github-actions · 2026-09-12T14:57:37Z


-    critic_model: str = os.getenv("MODEL_NAME")
-    worker_model: str = os.getenv("MODEL_NAME")
+    critic_model: str = os.getenv("MODEL_NAME", "gemini-3.5-flash")


Avoid hardcoding a default model name in the environment read. The model name should be loaded from the environment variable, and the default belongs in .env.example.

github-actions · 2026-09-12T14:57:37Z

-    critic_model: str = os.getenv("MODEL_NAME")
-    worker_model: str = os.getenv("MODEL_NAME")
+    critic_model: str = os.getenv("MODEL_NAME", "gemini-3.5-flash")
+    worker_model: str = os.getenv("MODEL_NAME", "gemini-3.5-flash")


Avoid hardcoding a default model name in the environment read. The model name should be loaded from the environment variable, and the default belongs in .env.example.

github-actions

Automated Security review — 1 finding(s).

github-actions · 2026-09-12T14:57:46Z


-    critic_model: str = os.getenv("MODEL_NAME")
-    worker_model: str = os.getenv("MODEL_NAME")
+    critic_model: str = os.getenv("MODEL_NAME", "gemini-3.5-flash")


Avoid using hardcoded defaults for environment reads in source files. Document the default values in .env.example instead (there are 2 instances in this file).

github-actions

Automated Hygiene review — 1 finding(s).

github-actions · 2026-09-12T14:58:18Z

+```python
+from pathlib import Path
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse


The import of FileResponse is unused in this code snippet. It should be removed to keep the example clean.

…oogle#2575)

github-actions

Automated Security review — 1 finding(s).

github-actions · 2026-09-12T15:02:44Z

+RUN npm run build
+
+# Stage 2: Backend + bundled frontend
+FROM python:3.11-slim


The Dockerfile example for the final stage lacks a USER directive, meaning the container runs as root by default. Add a USER instruction to run the container as a non-privileged user.

github-actions · 2026-09-12T15:03:24Z

There is a problem with the Antigravity CLI Maintainability PR review. Please check the action logs for details.

…#2575)

github-actions

Automated Correctness review — 2 finding(s).

github-actions · 2026-09-12T15:14:46Z

+WORKDIR /app
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev


Running uv sync before copying the source code will fail because uv expects the package source to be present to install the project by default. Add the --no-install-project flag to only sync dependencies first, or copy the source code before running the sync.

github-actions · 2026-09-12T15:14:46Z

+
+frontend_dist = Path("frontend/dist")
+if frontend_dist.exists():
+    app.mount("/app", StaticFiles(directory=str(frontend_dist), html=True), name="frontend")


Mounting the frontend at /app will cause asset loading failures (404 errors for /assets/...) unless the Vite build is specifically configured with base: "/app/". Mount the static files at the root / to serve the frontend as the main interface while keeping /api/* routed to ADK.

…tatic mount (google#2575)

github-actions

Automated House Rules review — 0 finding(s).

Also, on lines this PR does not change:

core/python/deep-search/frontend/vite.config.ts:1 — [MINOR] no .ts file in this recipe carries the standard Apache header (0 have a shorter notice, 3 have none) (core/python/deep-search/frontend/vite.config.ts; core/python/deep-search/frontend/src/vite-env.d.ts; core/python/deep-search/frontend/src/utils.ts)

github-actions

Automated Security review — 0 finding(s).

⚠️ This PR's diff was too large to review in full, so 33 file(s) were not looked at by this lane:

.agents/skills/github-pr-review/scripts/existing_comments.py
.agents/skills/github-pr-review/scripts/plan_review.py
.agents/skills/github-pr-review/scripts/post_comments.py
.agents/skills/github-pr-review/scripts/rejections.py
.agents/skills/github-pr-review/scripts/verify_findings.py
.agents/skills/github-pr-review/tests/conftest.py
.agents/skills/github-pr-review/tests/fixtures/pr2373_outcomes.json
.agents/skills/github-pr-review/tests/test_build_report.py
.agents/skills/github-pr-review/tests/test_check_house_rules.py
.agents/skills/github-pr-review/tests/test_house_rules_drift.py
.agents/skills/github-pr-review/tests/test_plan_review.py
.agents/skills/github-pr-review/tests/test_post_comments.py
.agents/skills/github-pr-review/tests/test_regression_pr2373.py
.agents/skills/github-pr-review/tests/test_rejections.py
.agents/skills/github-pr-review/tests/test_verify_findings.py
…and 18 more

Splitting the PR up would get them reviewed.

Round 4 · 8 of this PR's 25 automated comments used · this round is capped at 1 across all reviewers · only Security and Correctness still run.

happyhuman

Please take a look at a few comments left by the bots, and address he failed workflow (all should be minor things).

…inting (google#2575)

docs(deep-search): fix cloud deployment instructions and scaffold path (

f0d0d39

google#2575)

Anurag-M1 requested a review from eliasecchig as a code owner September 12, 2026 14:56

github-actions Bot reviewed Sep 12, 2026

View reviewed changes

docs(deep-search): remove unused import and keep PR scoped to README (g…

d0f5f17

…oogle#2575)

github-actions Bot reviewed Sep 12, 2026

View reviewed changes

Anurag-M1 mentioned this pull request Sep 12, 2026

[BUG]: python/agents/deep-search README Cloud Deployment section is broken #2575

Open

docs(deep-search): run multi-stage container as non-root user (google…

5d5b4d7

…#2575)

github-actions Bot reviewed Sep 12, 2026

View reviewed changes

Anurag-M1 and others added 2 commits September 12, 2026 20:59

docs(deep-search): address review comments on uv sync flag and root s…

b9cca4c

…tatic mount (google#2575)

Merge branch 'main' into fix/deep-search-cloud-deployment-docs-2575

3eb2676

github-actions Bot reviewed Sep 14, 2026

View reviewed changes

happyhuman self-requested a review September 14, 2026 16:04

happyhuman reviewed Sep 14, 2026

View reviewed changes

Anurag-M1 and others added 2 commits September 15, 2026 22:24

docs(deep-search): add license headers and fix biome formatting and l…

25dff97

…inting (google#2575)

Merge branch 'main' into fix/deep-search-cloud-deployment-docs-2575

4347727

happyhuman approved these changes Sep 16, 2026

View reviewed changes

Conversation

Anurag-M1 commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How it works

Testing

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 12, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Sep 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

happyhuman left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Anurag-M1 commented Sep 12, 2026 •

edited

Loading