agent-starter-pack 0.12.1__py3-none-any.whl → 0.13.0__py3-none-any.whl

{agent_starter_pack-0.12.1.dist-info → agent_starter_pack-0.13.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.12.1
+Version: 0.13.0
 Summary: CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates.
 Author-email: Google LLC <agent-starter-pack@google.com>
 License: Apache-2.0

{agent_starter_pack-0.12.1.dist-info → agent_starter_pack-0.13.0.dist-info}/RECORD

@@ -38,8 +38,8 @@ agents/live_api/tests/unit/test_server.py,sha256=_tf9nHkb7aOe3lZRlyp7cVklOTOYTuX
 llm.txt,sha256=onvCAhaPcye3YWfCkQeX4Y-LWF1TsAsZ09cO_iO-i3Y,14607
 src/base_template/.gitignore,sha256=Fq0w34x4sfbwP4RqDqh6hdHNYRUEsFNI-9XONzLWBIs,2580
 src/base_template/GEMINI.md,sha256=WzscHWlQeYkKORZ-453P8KM9IHuj1kAxW-69c7Ytuwk,133
-src/base_template/Makefile,sha256=tUPxvZI-XyAs2cXa3L3aTh3DFkwUBYkF5BOGs0DtvIk,6267
-src/base_template/README.md,sha256=KkHKYpnkU7gzfvzyULlTyt7gUxkf1IcK7Y4ydceLVzc,11458
+src/base_template/Makefile,sha256=8LRvbHvuj92oFr9dB3E92O39WqMKxM_kPO5t2lewOC4,6818
+src/base_template/README.md,sha256=ywTmrlWmivgHAtzXQCZqNu_Hfxp51QTnX4USNgGk6kU,10040
 src/base_template/pyproject.toml,sha256=dTyxaWetB-XCKQEDV3lXxAUxtBEpustNdlAEcT8ZZpo,2932
 src/base_template/deployment/README.md,sha256=gZJvSWdQh_Mi-bZ3dmuPv7fMezIw04fgN5tq7KgglPw,692
 src/base_template/deployment/terraform/apis.tf,sha256=KX8Oe2gjT-gh9Bkntz9yIAyRjPc1gZvwOhroJ6NZVp4,1513
@@ -72,17 +72,17 @@ src/base_template/{{cookiecutter.agent_directory}}/utils/gcs.py,sha256=jKblaWOGQ
 src/base_template/{{cookiecutter.agent_directory}}/utils/tracing.py,sha256=2rv1Ukh2jTBENDwoghCItJ28l-Sjz9gMlzdojlVgJa4,6052
 src/base_template/{{cookiecutter.agent_directory}}/utils/typing.py,sha256=DP5OZC3IGvqA1XbvWt8kI3gyAK3ZjzUSL5Ca17wNeLI,4249
 src/cli/main.py,sha256=Dya7Sw3ozMTaGDcwMh_-W7udkGZHGzgAj8aBdSZaZxI,1832
-src/cli/commands/create.py,sha256=wo72wjnHOaC5IVrDKtXzWa0YlHsXGCAyTpGlq-DUVq8,44892
+src/cli/commands/create.py,sha256=qVcK3E5DzQ66QACrwDA2q-6LvCApipIcht9HCi-LT28,45331
 src/cli/commands/enhance.py,sha256=4QMfU2hGHw1tZLrTYtBvpc3n6__mdSSekKMqy4OQAyE,15137
-src/cli/commands/list.py,sha256=Z2QCUMTG8Bwi5suSOkX4aJO6EReTaghiYMJtjj6PtNA,5584
+src/cli/commands/list.py,sha256=ZGol9eYB9Yon7JysMUCtpEOwdXzrApdTHzErx6KvT04,6856
 src/cli/commands/setup_cicd.py,sha256=nSgMUD4_ncYGwLWU1Fl7Ypw3GTJc8qVfjPxwZMLn4xo,32113
 src/cli/utils/__init__.py,sha256=_cTmsXGPqOtK0q8UW5164QTltbJRJFR_Efxq_BRL1-o,1311
 src/cli/utils/cicd.py,sha256=9s_OcusQznT_pSjFP60BfDBoZ5V6bwPE0QWbWdMaVlY,26515
 src/cli/utils/datastores.py,sha256=gv1V6eDcOEKx4MRNG5C3Y-VfixYq1AzQuaYMLp8QRNo,1058
-src/cli/utils/gcp.py,sha256=cnuCyN144eiyYc9aJNEK9JnyWN66rdevugoMdDYC1UU,4032
+src/cli/utils/gcp.py,sha256=XDtQVsqnYiZl4OGhrDjRwn5vq4GpFGu9v1CRwdu39Rs,8245
 src/cli/utils/logging.py,sha256=MYPxQYXXaKCqBVOfrhEMe8lFKzpzZWjOVP2Km81X5Mk,3007
-src/cli/utils/remote_template.py,sha256=d_kRMWhZkuKGCiQPWuMQDgRsoHTZXgep-dAhxfbV9Is,12246
-src/cli/utils/template.py,sha256=2CnxXTvQVM_ZnY8NlBNXuyhmIsflDe1eTUrHPFR7Qqk,46175
+src/cli/utils/remote_template.py,sha256=BYdV9Bgj54UUgOTnxlkOr8xA9ZgqKSEE-lWnmpJ05UY,18529
+src/cli/utils/template.py,sha256=j-f1FyvG9BuE7KTZglQ9BCYiPMbvW5z2xnr5JQLOhkg,50034
 src/cli/utils/version.py,sha256=F4udQmzniPStqWZFIgnv3Qg3l9non4mfy2An-Oveqmc,2916
 src/data_ingestion/README.md,sha256=LNxSQoJW9JozK-TbyGQLj5L_MGWNwrfLk6V6RmQ2oBQ,4032
 src/data_ingestion/pyproject.toml,sha256=-1Mf2QB8K70ICQV5UPZDpf-fN3UwEQLVzQyxfakCSTY,445
@@ -98,14 +98,14 @@ src/deployment_targets/agent_engine/tests/load_test/README.md,sha256=aQP7nDAqd2j
 src/deployment_targets/agent_engine/tests/load_test/load_test.py,sha256=USzS89bQ4qHVoQynDRSRShKzeXf1MJ0MBV4FpV40vrI,4249
 src/deployment_targets/agent_engine/tests/load_test/.results/.placeholder,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 src/deployment_targets/agent_engine/{{cookiecutter.agent_directory}}/agent_engine_app.py,sha256=91idmH-p7B7Gk8iMZoUeutndUqBhXt3apxUrTE64VlM,12797
-src/deployment_targets/cloud_run/Dockerfile,sha256=LdVMFTcYtO7b0L3jBXbVMUlHknL41ELp3RmzIGmxOH8,978
+src/deployment_targets/cloud_run/Dockerfile,sha256=rSpmFK7uJhZYwYMtxH8W7mywcCPvaoFn7gL_mXRYuF8,1449
 src/deployment_targets/cloud_run/deployment/terraform/service.tf,sha256=w3iEnyScbO0sjLPQEYfs3GmPpHTUMGeG1ghi09wSY24,10322
 src/deployment_targets/cloud_run/deployment/terraform/dev/service.tf,sha256=VegAzMcl2ohxMvtq6bcSXfCHYzQW68usyA839oULpgk,6581
 src/deployment_targets/cloud_run/tests/integration/test_server_e2e.py,sha256=85tA1gtbu_Z2CJqzOHgvDS-lvQFbYUMW8_mfqEc1_8I,9325
 src/deployment_targets/cloud_run/tests/load_test/README.md,sha256=clrCwgwUDr_AsivG0oLeNImTK4uke9EAWkrpS2nhIX0,2769
 src/deployment_targets/cloud_run/tests/load_test/load_test.py,sha256=kK3KaCdBFHKlni3ZVY2u4h_ugNla4o6pbhGRZlQ-haI,4270
 src/deployment_targets/cloud_run/tests/load_test/.results/.placeholder,sha256=ZbWpSgDo8bT33PstD_73aQSeN_0oo0F104NMUGuZ8lE,14903
-src/deployment_targets/cloud_run/{{cookiecutter.agent_directory}}/server.py,sha256=kKmjr8opUz2Z1nFw9-yKCu8T0tCBZQgWm3R9ab_l1fM,13752
+src/deployment_targets/cloud_run/{{cookiecutter.agent_directory}}/server.py,sha256=TKUFGNVxBlWh61owDIemiE734ENWKtWHXSAZ5Oix2t0,15463
 src/frontends/live_api_react/frontend/package-lock.json,sha256=h6yK6e_GR6CeZn_C9gGJoMpLjuBExjiDFIEaC28b6lU,734344
 src/frontends/live_api_react/frontend/package.json,sha256=OBOzzDiDiESPzmbLDlZ6KM1Trit71vXdP692dI-g9Uo,1381
 src/frontends/live_api_react/frontend/tsconfig.json,sha256=cyqEhf7-Yydz-PX8_cuF8JpsyC363NDTNkrmCk0sKAo,595
@@ -114,7 +114,7 @@ src/frontends/live_api_react/frontend/public/index.html,sha256=tOhOQOx5kMi9WhxT-
 src/frontends/live_api_react/frontend/public/robots.txt,sha256=kNJLw79pisHhc3OVAimMzKcq3x9WT6sF9IS4xI0crdI,67
 src/frontends/live_api_react/frontend/src/App.scss,sha256=477MjERLsjhhzSS5WvROHfgdLi41F0PeW7zFTIROlH4,3472
 src/frontends/live_api_react/frontend/src/App.test.tsx,sha256=l4bj_dLHDggvlcxZZgbhXdR9oIpdCwrGglRWtSqNqUU,869
-src/frontends/live_api_react/frontend/src/App.tsx,sha256=5PhZTXo4gwWRvkF5dJTwu4YpWKs43bsLSl1IGXx1edY,7261
+src/frontends/live_api_react/frontend/src/App.tsx,sha256=ZPGBW_hieBDLmGO4_d3DWPAin8SU1QNy4G-YkZhY6sw,7388
 src/frontends/live_api_react/frontend/src/index.css,sha256=THy1DxvcOTW4WypzWvYEL_SVAVzda1iPEQ0M6pvgNUo,950
 src/frontends/live_api_react/frontend/src/index.tsx,sha256=c3VCNMXzTZInNqpHaQUMPPwZsicO468Ujc5u3jLGLZ8,1150
 src/frontends/live_api_react/frontend/src/multimodal-live-types.ts,sha256=J52j9vfza9EyODprh9w29psdBSEygTnXZF8yJIsfsDs,6037
@@ -138,7 +138,7 @@ src/frontends/live_api_react/frontend/src/hooks/use-webcam.ts,sha256=NuTM7meIwaS
 src/frontends/live_api_react/frontend/src/utils/audio-recorder.ts,sha256=JcO69YeM7boSf1gM5VVX6cbLvGRT-dYYJjWUVBJFWbM,3699
 src/frontends/live_api_react/frontend/src/utils/audio-streamer.ts,sha256=xgtnrm_jbmKzwUkeCQiv3C7jmU7DfdaJU2su6NLpXCk,8301
 src/frontends/live_api_react/frontend/src/utils/audioworklet-registry.ts,sha256=2I1va0WszQ3-SHfSmgp5-ToOSof5H6q-rgFnlf8mGUI,1258
-src/frontends/live_api_react/frontend/src/utils/multimodal-live-client.ts,sha256=afOZaVZdPrTFTvZj3m1I463pBqfyd9CI6wvctieoG90,9771
+src/frontends/live_api_react/frontend/src/utils/multimodal-live-client.ts,sha256=u9gVQCXtSlylnDEd9GsQ1CkCTc_1kLeZD1WdgzcGzqc,9946
 src/frontends/live_api_react/frontend/src/utils/store-logger.ts,sha256=YxS0TjiGntFPIrHVVU14WplpITzzxP2faTeAVOMvbQA,1761
 src/frontends/live_api_react/frontend/src/utils/utils.ts,sha256=qQIhLzfyCBLecU0ksQCKIbD3cIflb0hxt0SPZGdYFEo,2457
 src/frontends/live_api_react/frontend/src/utils/worklets/audio-processing.ts,sha256=ULgnXphZUfbHkRhGoPT_670WHjzaXJwWgYU0ISQRSXI,1979
@@ -170,8 +170,8 @@ src/resources/locks/uv-live_api-cloud_run.lock,sha256=AMgJt_aeoXU3LDvZv4iph9XCVs
 src/utils/generate_locks.py,sha256=6V1B8V2BEuevWnXUsxZVTrLjXwFRII8UfsIGrQqZxVs,4320
 src/utils/lock_utils.py,sha256=IFOMUWtb-ypm2Y8w8J5y2oI_-MaPuwPF_JOAAlnNudA,2275
 src/utils/watch_and_rebuild.py,sha256=vP4yIiA7E_lj5sfQdJUl8TXas6V7msDg8XWUutAC05Q,6679
-agent_starter_pack-0.12.1.dist-info/METADATA,sha256=srgIqHc7W8LUvdtlBVcLEg4PN03Z7KwBhW0oIYy8sY0,11155
-agent_starter_pack-0.12.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-agent_starter_pack-0.12.1.dist-info/entry_points.txt,sha256=U7uCxR7YulIhZ0L8R8Hui0Bsy6J7oyESBeDYJYMrQjA,56
-agent_starter_pack-0.12.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-agent_starter_pack-0.12.1.dist-info/RECORD,,
+agent_starter_pack-0.13.0.dist-info/METADATA,sha256=ppWiEr8G2BZkql1PwhCJ3KAmfeI256SngwrYlpyGySg,11155
+agent_starter_pack-0.13.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agent_starter_pack-0.13.0.dist-info/entry_points.txt,sha256=U7uCxR7YulIhZ0L8R8Hui0Bsy6J7oyESBeDYJYMrQjA,56
+agent_starter_pack-0.13.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+agent_starter_pack-0.13.0.dist-info/RECORD,,

src/base_template/Makefile

@@ -4,7 +4,7 @@ install:
 {%- if cookiecutter.settings.get("commands", {}).get("override", {}).get("install") %} 
 	{{cookiecutter.settings.get("commands", {}).get("override", {}).get("install")}}
 {%- else %}
-	uv sync --dev{% if cookiecutter.agent_name != 'live_api' and "adk" not in cookiecutter.tags %} --extra streamlit{%- endif %} --extra jupyter{% if cookiecutter.agent_name == 'live_api' %} && (cd frontend && npm install){%- endif %}
+	uv sync --dev{% if cookiecutter.agent_name != 'live_api' and "adk" not in cookiecutter.tags %} --extra streamlit{%- endif %}{% if cookiecutter.agent_name == 'live_api' %} && (cd frontend && npm install){%- endif %}
 {%- endif %}
 
 {%- if cookiecutter.settings.get("commands", {}).get("extra", {}) %}
@@ -23,14 +23,23 @@ install:
 {%- endif %}
 {%- endfor %}{%- endif %}
 
+{%- if cookiecutter.agent_name == 'live_api' %}
+# Build the frontend for production
+build-frontend:
+	(cd frontend && npm run build)
+
+{%- endif %}
 # Launch local dev playground
-playground:
+playground:{%- if cookiecutter.agent_name == 'live_api' %} build-frontend{%- endif %}
 {%- if cookiecutter.settings.get("commands", {}).get("override", {}).get("playground") %}
 	{{cookiecutter.settings.get("commands", {}).get("override", {}).get("playground")}}
 {%- else %}
 	@echo "==============================================================================="
 	@echo "| 🚀 Starting your agent playground...                                        |"
 	@echo "|                                                                             |"
+{%- if cookiecutter.agent_name == 'live_api' %}
+	@echo "| 🌐 Access your app at: http://localhost:8000                               |"
+{%- endif %}
 	@echo "| 💡 Try asking: {{cookiecutter.example_question}}|"
 {%- if "adk" in cookiecutter.tags %}
 	@echo "|                                                                             |"
@@ -41,11 +50,13 @@ playground:
 	uv run adk web . --port 8501
 {%- else %}
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
-	uv run uvicorn {{cookiecutter.agent_directory}}.server:app --host 0.0.0.0 --port 8000 --reload &
-{%- endif %}
 {%- if cookiecutter.agent_name == 'live_api' %}
-	(cd frontend && PORT=8501 npm start)
+	uv run uvicorn {{cookiecutter.agent_directory}}.server:app --host 0.0.0.0 --port 8000 --reload
 {%- else %}
+	uv run uvicorn {{cookiecutter.agent_directory}}.server:app --host 0.0.0.0 --port 8000 --reload &
+{%- endif %}
+{%- endif %}
+{%- if cookiecutter.agent_name != 'live_api' %}
 	{% if cookiecutter.deployment_target == 'agent_engine' %}PYTHONPATH=. {% endif %}uv run streamlit run frontend/streamlit_app.py --browser.serverAddress=localhost --server.enableCORS=false --server.enableXsrfProtection=false
 {%- endif %}
 {%- endif %}
@@ -84,7 +95,7 @@ local-backend:
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
 {%- if cookiecutter.agent_name == 'live_api' %}
 
-# Start the frontend UI for development
+# Start the frontend UI separately for development (requires backend running separately)
 ui:
 	(cd frontend && PORT=8501 npm start)
 {%- endif %}
@@ -122,6 +133,7 @@ test:
 
 # Run code quality checks (codespell, ruff, mypy)
 lint:
+	uv sync --dev --extra lint
 	uv run codespell
 	uv run ruff check . --diff
 	uv run ruff format . --check --diff

src/base_template/README.md

@@ -92,12 +92,12 @@ Here’s the recommended workflow for local development:
     make install
     ```
 
-2.  **Start the Backend Server:**
-    Open a terminal and run:
+2.  **Start the Full Stack Server:**
+    The FastAPI server now serves both the backend API and frontend interface:
     ```bash
     make local-backend
     ```
-    The backend is ready when you see `INFO:     Application startup complete.` Wait for this message before starting the frontend.
+    The server is ready when you see `INFO:     Application startup complete.` The frontend will be available at `http://localhost:8000`.
 
     <details>
     <summary><b>Optional: Use AI Studio / API Key instead of Vertex AI</b></summary>
@@ -113,47 +113,23 @@ Here’s the recommended workflow for local development:
     </details>
     <br>
 
-3.  **Start the Frontend UI:**
-    Open *another* terminal and run:
+    <details>
+    <summary><b>Alternative: Run Frontend Separately</b></summary>
+
+    If you prefer to run the frontend separately (useful for frontend development), you can still use:
     ```bash
     make ui
     ```
-    This launches the Streamlit application, which connects to the backend server (by default at `http://localhost:8000`).
+    This launches the Streamlit application, which connects to the backend server at `http://localhost:8000`.
+    </details>
+    <br>
 
-4.  **Interact and Iterate:**
-    *   Open the Streamlit UI in your browser (usually `http://localhost:8501` or `http://localhost:3001`).
+3.  **Interact and Iterate:**
+    *   Open your browser and navigate to `http://localhost:8000` to access the integrated frontend.
     *   Click the play button in the UI to connect to the backend.
     *   Interact with the agent! Try prompts like: *"Using the tool you have, define Governance in the context MLOPs"*
     *   Modify the agent logic in `{{cookiecutter.agent_directory}}/agent.py`. The backend server (FastAPI with `uvicorn --reload`) should automatically restart when you save changes. Refresh the frontend if needed to see behavioral changes.
 
-<details>
-<summary><b>Cloud Shell Usage</b></summary>
-
-To run the agent using Google Cloud Shell:
-
-1.  **Start the Frontend:**
-    In a Cloud Shell tab, run:
-    ```bash
-    make ui
-    ```
-    Accept prompts to use a different port if 3000 is busy. Click the `localhost:PORT` link for the web preview.
-
-2.  **Start the Backend:**
-    Open a *new* Cloud Shell tab. Set your project: `gcloud config set project [PROJECT_ID]`. Then run:
-    ```bash
-    make local-backend
-    ```
-
-3.  **Configure Backend Web Preview:**
-    Use the Cloud Shell Web Preview feature to expose port 8000. Change the default port from 8080 to 8000. See [Cloud Shell Web Preview documentation](https://cloud.google.com/shell/docs/using-web-preview#preview_the_application).
-
-4.  **Connect Frontend to Backend:**
-    *   Copy the URL generated by the backend web preview (e.g., `https://8000-cs-....cloudshell.dev/`).
-    *   Paste this URL into the "Server URL" field in the frontend UI settings (in the first tab).
-    *   Click the "Play button" to connect.
-
-*   **Note:** The feedback feature in the frontend might not work reliably in Cloud Shell due to cross-origin issues between the preview URLs.
-</details>
 
 </details>
 {%- else %}
@@ -183,18 +159,7 @@ gcloud config set project <your-dev-project-id>
 make backend
 ```
 {% if cookiecutter.agent_name == 'live_api' %}
-**Accessing the Deployed Backend Locally:**
-
-To connect your local frontend (`make ui`) to the backend deployed on Cloud Run, use the `gcloud` proxy:
-
-1.  **Start the proxy:**
-    ```bash
-    # Replace with your actual service name, project, and region
-    gcloud run services proxy gemini-agent-service --port 8000 --project $PROJECT_ID --region $REGION
-    ```
-    Keep this terminal running.
-
-2.  **Connect Frontend:** Your deployed backend is now accessible locally at `http://localhost:8000`. Point your Streamlit UI to this address.
+**Note:** For secure access to your deployed backend, consider using Identity-Aware Proxy (IAP) by running `make backend IAP=true`.
 {%- endif %}
 
 The repository includes a Terraform configuration for the setup of the Dev Google Cloud project.

src/cli/commands/create.py

@@ -18,17 +18,11 @@ import os
 import pathlib
 import shutil
 import subprocess
-import sys
 import tempfile
 from collections.abc import Callable
 
 import click
 from click.core import ParameterSource
-
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
 from rich.console import Console
 from rich.prompt import IntPrompt, Prompt
 
@@ -249,6 +243,8 @@ def create(
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
     try:
+        console = Console()
+
         # Display welcome banner (unless skipped)
         if not skip_welcome:
             display_welcome_banner(agent)
@@ -312,6 +308,7 @@ def create(
         selected_agent = None
         template_source_path = None
         temp_dir_to_clean = None
+        remote_spec = None
 
         if agent:
             if agent.startswith("local@"):
@@ -353,6 +350,20 @@ def create(
                     )
                     temp_dir_to_clean = str(temp_dir_path)
                     selected_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
+
+                    # Show informational message for ADK samples with smart defaults
+                    if remote_spec.is_adk_samples:
+                        config = load_remote_template_config(
+                            template_source_path, is_adk_sample=True
+                        )
+                        if not config.get("has_explicit_config", True):
+                            console = Console()
+                            console.print(
+                                "\n[blue]ℹ️  Note: The starter pack uses heuristics to template this ADK sample agent.[/]"
+                            )
+                            console.print(
+                                "[dim]   The starter pack attempts to create a working codebase, but you'll need to follow the generated README for complete setup.[/]"
+                            )
                 else:
                     # Handle local agent selection
                     agents = get_available_agents()
@@ -402,6 +413,20 @@ def create(
                     temp_dir_to_clean = str(temp_dir_path)
                     final_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
 
+                    # Show informational message for ADK samples with smart defaults
+                    if remote_spec.is_adk_samples:
+                        config = load_remote_template_config(
+                            template_source_path, is_adk_sample=True
+                        )
+                        if not config.get("has_explicit_config", True):
+                            console = Console()
+                            console.print(
+                                "\n[blue]ℹ️  Note: The starter pack uses heuristics to template this ADK sample agent.[/]"
+                            )
+                            console.print(
+                                "[dim]   The starter pack attempts to create a working codebase, but you'll need to follow the generated README for complete setup.[/]"
+                            )
+
         if debug:
             logging.debug(f"Selected agent: {final_agent}")
 
@@ -414,7 +439,9 @@ def create(
 
             # Load remote template config
             source_config = load_remote_template_config(
-                template_source_path, cli_overrides
+                template_source_path,
+                cli_overrides,
+                is_adk_sample=remote_spec.is_adk_samples if remote_spec else False,
             )
 
             # Remote templates now work even without pyproject.toml thanks to defaults
@@ -779,56 +806,10 @@ def display_adk_samples_selection() -> str:
         # Fetch the repository
         repo_path, _ = fetch_remote_template(spec)
 
-        # Scan for agents in the repository
-        adk_agents = {}
-        agent_count = 1
-
-        # Search for pyproject.toml files to identify agents
-        for config_path in sorted(repo_path.glob("**/pyproject.toml")):
-            try:
-                with open(config_path, "rb") as f:
-                    pyproject_data = tomllib.load(f)
-
-                config = pyproject_data.get("tool", {}).get("agent-starter-pack", {})
-
-                # Skip pyproject.toml files that don't have agent-starter-pack config
-                if not config:
-                    continue
-
-                template_root = config_path.parent
-
-                # Use fallbacks to [project] section if needed
-                project_info = pyproject_data.get("project", {})
-                agent_name = (
-                    config.get("name") or project_info.get("name") or template_root.name
-                )
-                description = (
-                    config.get("description") or project_info.get("description") or ""
-                )
+        # Use shared ADK discovery function
+        from ..utils.remote_template import discover_adk_agents
 
-                # Get the relative path from repo root
-                relative_path = template_root.relative_to(repo_path)
-
-                # For adk-samples, use just the agent name for the spec
-                # This handles cases like python/agents/gemini-fullstack -> gemini-fullstack
-                agent_spec_name = (
-                    relative_path.name
-                    if relative_path != relative_path.parent
-                    else str(relative_path)
-                )
-
-                adk_agents[agent_count] = {
-                    "name": agent_name,
-                    "description": description,
-                    "path": str(relative_path),
-                    "spec": f"adk@{agent_spec_name}",
-                }
-                agent_count += 1
-
-            except Exception as e:
-                logging.warning(
-                    f"Could not load agent from {config_path.parent.parent}: {e}"
-                )
+        adk_agents = discover_adk_agents(repo_path)
 
         if not adk_agents:
             console.print("No agents found in adk-samples repository", style="yellow")
@@ -836,9 +817,19 @@ def display_adk_samples_selection() -> str:
             return display_agent_selection()
 
         console.print("\n> Available agents from [bold blue]google/adk-samples[/]:")
+
+        # Show explanation for inferred agents at the top
+        from ..utils.remote_template import display_adk_caveat_if_needed
+
+        display_adk_caveat_if_needed(adk_agents)
+
         for num, agent in adk_agents.items():
+            name_with_indicator = agent["name"]
+            if not agent.get("has_explicit_config", True):
+                name_with_indicator += " *"
+
             console.print(
-                f"{num}. [bold]{agent['name']}[/] - [dim]{agent['description']}[/]"
+                f"{num}. [bold]{name_with_indicator}[/] - [dim]{agent['description']}[/]"
             )
 
         # Add option to go back to local agents
@@ -1035,18 +1026,22 @@ def _handle_credential_verification(creds_info: dict) -> dict:
     return creds_info
 
 
-def _test_vertex_ai_connection(project_id: str, region: str) -> None:
+def _test_vertex_ai_connection(
+    project_id: str, region: str, auto_approve: bool = False
+) -> None:
     """Test connection to Vertex AI.
 
     Args:
         project_id: GCP project ID
         region: GCP region for deployment
+        auto_approve: Whether to auto-approve API enablement
     """
     console.print("> Testing GCP and Vertex AI Connection...")
     try:
         verify_vertex_connection(
             project_id=project_id,
             location=region,
+            auto_approve=auto_approve,
         )
         console.print(
             f"> ✓ Successfully verified connection to Vertex AI in project {project_id}"
@@ -1058,6 +1053,7 @@ def _test_vertex_ai_connection(project_id: str, region: str) -> None:
             f"Visit https://cloud.google.com/vertex-ai/docs/authentication for help.",
             style="bold red",
         )
+        raise
 
 
 def replace_region_in_files(

src/cli/commands/list.py

@@ -31,7 +31,9 @@ from ..utils.template import get_available_agents
 console = Console()
 
 
-def display_agents_from_path(base_path: pathlib.Path, source_name: str) -> None:
+def display_agents_from_path(
+    base_path: pathlib.Path, source_name: str, is_adk_samples: bool = False
+) -> None:
     """Scans a directory and displays available agents."""
     table = Table(
         title=f"Available agents in [bold blue]{source_name}[/]",
@@ -47,41 +49,66 @@ def display_agents_from_path(base_path: pathlib.Path, source_name: str) -> None:
         return
 
     found_agents = False
-    # Search for pyproject.toml files to identify agents (explicit opt-in)
-    for config_path in sorted(base_path.glob("**/pyproject.toml")):
-        try:
-            with open(config_path, "rb") as f:
-                pyproject_data = tomllib.load(f)
+    adk_agents = {}
 
-            config = pyproject_data.get("tool", {}).get("agent-starter-pack", {})
+    if is_adk_samples:
+        # For ADK samples, use the shared discovery function
+        from ..utils.remote_template import discover_adk_agents
 
-            # Skip pyproject.toml files that don't have agent-starter-pack config
-            if not config:
-                continue
+        adk_agents = discover_adk_agents(base_path)
 
-            template_root = config_path.parent
+        for agent_info in adk_agents.values():
+            # Add indicator for inferred agents
+            name_with_indicator = agent_info["name"]
+            if not agent_info.get("has_explicit_config", True):
+                name_with_indicator += " *"
 
-            # Use fallbacks to [project] section if needed
-            project_info = pyproject_data.get("project", {})
-            agent_name = (
-                config.get("name") or project_info.get("name") or template_root.name
-            )
-            description = (
-                config.get("description") or project_info.get("description") or ""
+            table.add_row(
+                name_with_indicator, f"/{agent_info['path']}", agent_info["description"]
             )
+            found_agents = True
+    else:
+        # Original logic for non-ADK sources: Search for pyproject.toml files with explicit config
+        for config_path in sorted(base_path.glob("**/pyproject.toml")):
+            try:
+                with open(config_path, "rb") as f:
+                    pyproject_data = tomllib.load(f)
 
-            # Display the agent's path relative to the scanned directory
-            relative_path = template_root.relative_to(base_path)
+                config = pyproject_data.get("tool", {}).get("agent-starter-pack", {})
 
-            table.add_row(agent_name, f"/{relative_path}", description)
-            found_agents = True
+                # Skip pyproject.toml files that don't have agent-starter-pack config
+                if not config:
+                    continue
+
+                template_root = config_path.parent
+
+                # Use fallbacks to [project] section if needed
+                project_info = pyproject_data.get("project", {})
+                agent_name = (
+                    config.get("name") or project_info.get("name") or template_root.name
+                )
+                description = (
+                    config.get("description") or project_info.get("description") or ""
+                )
+
+                # Display the agent's path relative to the scanned directory
+                relative_path = template_root.relative_to(base_path)
 
-        except Exception as e:
-            logging.warning(f"Could not load agent from {config_path.parent}: {e}")
+                table.add_row(agent_name, f"/{relative_path}", description)
+                found_agents = True
+
+            except Exception as e:
+                logging.warning(f"Could not load agent from {config_path.parent}: {e}")
 
     if not found_agents:
         console.print(f"No agents found in {source_name}", style="yellow")
     else:
+        # Show explanation for inferred agents at the top (only for ADK samples)
+        if is_adk_samples:
+            from ..utils.remote_template import display_adk_caveat_if_needed
+
+            display_adk_caveat_if_needed(adk_agents)
+
         console.print(table)
 
 
@@ -103,7 +130,14 @@ def list_remote_agents(remote_source: str, scan_from_root: bool = False) -> None
         repo_path, template_path = template_dir_path
         scan_path = repo_path if scan_from_root else template_path
 
-        display_agents_from_path(scan_path, remote_source)
+        # Check if this is ADK samples to enable inference
+        is_adk_samples = (
+            spec.is_adk_samples if hasattr(spec, "is_adk_samples") else False
+        )
+
+        display_agents_from_path(
+            scan_path, remote_source, is_adk_samples=is_adk_samples
+        )
 
     except (RuntimeError, FileNotFoundError) as e:
         console.print(f"Error: {e}", style="bold red")

src/cli/utils/gcp.py

@@ -14,9 +14,11 @@
 
 # ruff: noqa: E722
 import subprocess
+import time
 
 import google.auth
 from google.api_core.client_options import ClientOptions
+from google.api_core.exceptions import PermissionDenied
 from google.api_core.gapic_v1.client_info import ClientInfo
 from google.cloud.aiplatform import initializer
 from google.cloud.aiplatform_v1beta1.services.prediction_service import (
@@ -25,9 +27,94 @@ from google.cloud.aiplatform_v1beta1.services.prediction_service import (
 from google.cloud.aiplatform_v1beta1.types.prediction_service import (
     CountTokensRequest,
 )
+from rich.console import Console
+from rich.prompt import Confirm
 
 from src.cli.utils.version import PACKAGE_NAME, get_current_version
 
+console = Console()
+
+
+def enable_vertex_ai_api(project_id: str, auto_approve: bool = False) -> bool:
+    """Enable Vertex AI API with user confirmation and propagation waiting."""
+    api_name = "aiplatform.googleapis.com"
+
+    # First test if API is already working with a direct connection
+    if _test_vertex_ai_connection(project_id):
+        return True
+
+    if not auto_approve:
+        console.print(
+            f"Vertex AI API is not enabled in project '{project_id}'.", style="yellow"
+        )
+        console.print(
+            "To continue, we need to enable the Vertex AI API.", style="yellow"
+        )
+
+        if not Confirm.ask(
+            "Do you want to enable the Vertex AI API now?", default=True
+        ):
+            return False
+
+    try:
+        console.print("Enabling Vertex AI API...")
+        subprocess.run(
+            [
+                "gcloud",
+                "services",
+                "enable",
+                api_name,
+                "--project",
+                project_id,
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        console.print("✓ Vertex AI API enabled successfully")
+
+        # Wait for API propagation
+        console.print("⏳ Waiting for API availability to propagate...")
+        max_wait_time = 180  # 3 minutes
+        check_interval = 10  # 10 seconds
+        start_time = time.time()
+
+        while time.time() - start_time < max_wait_time:
+            if _test_vertex_ai_connection(project_id):
+                console.print("✓ Vertex AI API is now available")
+                return True
+            time.sleep(check_interval)
+            console.print("⏳ Still waiting for API propagation...")
+
+        console.print(
+            "⚠️ API propagation took longer than expected, but continuing...",
+            style="yellow",
+        )
+        return True
+
+    except subprocess.CalledProcessError as e:
+        console.print(f"Failed to enable Vertex AI API: {e.stderr}", style="bold red")
+        return False
+
+
+def _test_vertex_ai_connection(project_id: str, location: str = "us-central1") -> bool:
+    """Test Vertex AI connection without raising exceptions."""
+    try:
+        credentials, _ = google.auth.default()
+        client = PredictionServiceClient(
+            credentials=credentials,
+            client_options=ClientOptions(
+                api_endpoint=f"{location}-aiplatform.googleapis.com"
+            ),
+            client_info=get_client_info(),
+            transport=initializer.global_config._api_transport,
+        )
+        request = get_dummy_request(project_id=project_id)
+        client.count_tokens(request=request)
+        return True
+    except Exception:
+        return False
+
 
 def get_user_agent() -> str:
     """Returns custom user agent header tuple (version, agent string)."""
@@ -52,8 +139,18 @@ def get_dummy_request(project_id: str) -> CountTokensRequest:
 def verify_vertex_connection(
     project_id: str,
     location: str = "us-central1",
+    auto_approve: bool = False,
 ) -> None:
     """Verifies Vertex AI connection with a test Gemini request."""
+    # First try direct connection - if it works, we're done
+    if _test_vertex_ai_connection(project_id, location):
+        return
+
+    # If that failed, try to enable the API
+    if not enable_vertex_ai_api(project_id, auto_approve):
+        raise Exception("Vertex AI API is not enabled and user declined to enable it")
+
+    # After enabling, test again with proper error handling
     credentials, _ = google.auth.default()
     client = PredictionServiceClient(
         credentials=credentials,
@@ -64,7 +161,31 @@ def verify_vertex_connection(
         transport=initializer.global_config._api_transport,
     )
     request = get_dummy_request(project_id=project_id)
-    client.count_tokens(request=request)
+
+    try:
+        client.count_tokens(request=request)
+    except PermissionDenied as e:
+        error_message = str(e)
+        # Check if the error is specifically about API not being enabled
+        if (
+            "has not been used" in error_message
+            and "aiplatform.googleapis.com" in error_message
+        ):
+            # This shouldn't happen since we checked above, but handle it gracefully
+            console.print(
+                "⚠️ API may still be propagating, retrying in 30 seconds...",
+                style="yellow",
+            )
+            time.sleep(30)
+            try:
+                client.count_tokens(request=request)
+            except PermissionDenied:
+                raise Exception(
+                    "Vertex AI API is enabled but not yet available. Please wait a few more minutes and try again."
+                ) from e
+        else:
+            # Re-raise other permission errors
+            raise
 
 
 def verify_credentials() -> dict:

src/cli/utils/remote_template.py

@@ -28,6 +28,7 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 from jinja2 import Environment
+from rich.console import Console
 
 
 @dataclass
@@ -94,10 +95,14 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
             template_path = path_parts[0]
             git_ref = path_parts[1]
 
+        # Check if this is the ADK samples repository
+        is_adk_samples = repo_url == "https://github.com/google/adk-samples"
+
         return RemoteTemplateSpec(
             repo_url=repo_url,
             template_path=template_path.strip("/"),
             git_ref=git_ref,
+            is_adk_samples=is_adk_samples,
         )
 
     # GitHub shorthand: <org>/<repo>[/<path>][@<ref>]
@@ -108,10 +113,15 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
         repo = match.group(2)
         template_path = match.group(3) or ""
         git_ref = match.group(4) or "main"
+
+        # Check if this is the ADK samples repository
+        is_adk_samples = org == "google" and repo == "adk-samples"
+
         return RemoteTemplateSpec(
             repo_url=f"https://github.com/{org}/{repo}",
             template_path=template_path,
             git_ref=git_ref,
+            is_adk_samples=is_adk_samples,
         )
 
     return None
@@ -187,29 +197,66 @@ def fetch_remote_template(
         ) from e
 
 
+def _infer_agent_directory_for_adk(
+    template_dir: pathlib.Path, is_adk_sample: bool
+) -> dict[str, Any]:
+    """Infer agent configuration for ADK samples only using Python conventions.
+
+    Args:
+        template_dir: Path to template directory
+        is_adk_sample: Whether this is an ADK sample
+
+    Returns:
+        Dictionary with inferred configuration, or empty dict if not ADK sample
+    """
+    if not is_adk_sample:
+        return {}
+
+    # Convert folder name to Python package convention (hyphens to underscores)
+    folder_name = template_dir.name
+    agent_directory = folder_name.replace("-", "_")
+
+    logging.debug(
+        f"Inferred agent_directory '{agent_directory}' from folder name '{folder_name}' for ADK sample"
+    )
+
+    return {
+        "settings": {
+            "agent_directory": agent_directory,
+        },
+        "has_explicit_config": False,  # Track that this was inferred
+    }
+
+
 def load_remote_template_config(
-    template_dir: pathlib.Path, cli_overrides: dict[str, Any] | None = None
+    template_dir: pathlib.Path,
+    cli_overrides: dict[str, Any] | None = None,
+    is_adk_sample: bool = False,
 ) -> dict[str, Any]:
     """Load template configuration from remote template's pyproject.toml with CLI overrides.
 
     Loads configuration from [tool.agent-starter-pack] section with fallbacks
     to [project] section for name and description if not specified. CLI overrides
-    take precedence over all other sources.
+    take precedence over all other sources. For ADK samples without explicit config,
+    uses smart inference for agent directory naming.
 
     Args:
         template_dir: Path to template directory
         cli_overrides: Configuration overrides from CLI (takes highest precedence)
+        is_adk_sample: Whether this is an ADK sample (enables smart inference)
 
     Returns:
         Template configuration dictionary with merged sources
     """
-    config = {}
+    config: dict[str, Any] = {}
+    has_explicit_config = False
 
     # Start with defaults
     defaults = {
         "base_template": "adk_base",
         "name": template_dir.name,
         "description": "",
+        "agent_directory": "app",  # Default for non-ADK samples
     }
     config.update(defaults)
 
@@ -226,9 +273,13 @@ def load_remote_template_config(
             # Fallback to [project] fields if not specified in agent-starter-pack section
             project_info = pyproject_data.get("project", {})
 
+            # Track if we have explicit configuration
+            has_explicit_config = bool(toml_config)
+
             # Apply pyproject.toml configuration (overrides defaults)
             if toml_config:
                 config.update(toml_config)
+                logging.debug("Found explicit [tool.agent-starter-pack] configuration")
 
             # Apply [project] fallbacks if not already set
             if "name" not in toml_config and "name" in project_info:
@@ -240,6 +291,31 @@ def load_remote_template_config(
             logging.debug(f"Loaded template config from {pyproject_path}")
         except Exception as e:
             logging.error(f"Error loading pyproject.toml config: {e}")
+    else:
+        # No pyproject.toml found
+        if is_adk_sample:
+            logging.debug(
+                f"No pyproject.toml found for ADK sample {template_dir.name}, will use inference"
+            )
+        else:
+            logging.debug(
+                f"No pyproject.toml found for template {template_dir.name}, using defaults"
+            )
+
+    # Apply ADK inference if no explicit config and this is an ADK sample
+    if not has_explicit_config and is_adk_sample:
+        try:
+            inferred_config = _infer_agent_directory_for_adk(
+                template_dir, is_adk_sample
+            )
+            config.update(inferred_config)
+            logging.debug("Applied ADK inference for template without explicit config")
+        except Exception as e:
+            logging.warning(f"Failed to apply ADK inference for {template_dir}: {e}")
+            # Continue with default configuration
+
+    # Add metadata about configuration source
+    config["has_explicit_config"] = bool(has_explicit_config)
 
     # Apply CLI overrides (highest precedence) using deep merge
     if cli_overrides:
@@ -291,6 +367,97 @@ def merge_template_configs(
     return deep_merge(merged_config, remote_config)
 
 
+def discover_adk_agents(repo_path: pathlib.Path) -> dict[int, dict[str, Any]]:
+    """Discover and load all ADK agents from a repository with inference support.
+
+    Args:
+        repo_path: Path to the cloned ADK samples repository
+
+    Returns:
+        Dictionary mapping agent numbers to agent info with keys:
+        - name: Agent display name
+        - description: Agent description
+        - path: Relative path from repo root
+        - spec: adk@ specification string
+        - has_explicit_config: Whether agent has explicit configuration
+    """
+    import logging
+
+    adk_agents = {}
+
+    # Search specifically for agents in python/agents/* directories
+    agents_dir = repo_path / "python" / "agents"
+    logging.debug(f"Looking for agents in: {agents_dir}")
+    if agents_dir.exists():
+        all_items = list(agents_dir.iterdir())
+        logging.debug(
+            f"Found items in agents directory: {[item.name for item in all_items]}"
+        )
+
+        # Collect all agents first, then sort by configuration type
+        all_agents = []
+
+        for agent_dir in sorted(agents_dir.iterdir()):
+            if not agent_dir.is_dir():
+                logging.debug(f"Skipping non-directory: {agent_dir.name}")
+                continue
+            logging.debug(f"Processing agent directory: {agent_dir.name}")
+
+            try:
+                # Load configuration with ADK inference support
+                config = load_remote_template_config(
+                    template_dir=agent_dir, is_adk_sample=True
+                )
+
+                agent_name = config.get("name", agent_dir.name)
+                description = config.get("description", "")
+                has_explicit_config = config.get("has_explicit_config", False)
+
+                # Get the relative path from repo root
+                relative_path = agent_dir.relative_to(repo_path)
+                agent_spec_name = agent_dir.name
+
+                agent_info = {
+                    "name": agent_name,
+                    "description": description,
+                    "path": str(relative_path),
+                    "spec": f"adk@{agent_spec_name}",
+                    "has_explicit_config": has_explicit_config,
+                }
+                all_agents.append(agent_info)
+
+            except Exception as e:
+                logging.warning(f"Could not load agent from {agent_dir}: {e}")
+
+        # Sort agents: explicit config first, then inferred (both alphabetically within their groups)
+        all_agents.sort(key=lambda x: (not x["has_explicit_config"], x["name"].lower()))
+
+        # Convert to numbered dictionary
+        for i, agent_info in enumerate(all_agents, 1):
+            adk_agents[i] = agent_info
+
+    return adk_agents
+
+
+def display_adk_caveat_if_needed(agents: dict[int, dict[str, Any]]) -> None:
+    """Display helpful note for agents that use inference.
+
+    Args:
+        agents: Dictionary of agent info from discover_adk_agents
+    """
+    console = Console()
+    inferred_agents = [
+        a for a in agents.values() if not a.get("has_explicit_config", True)
+    ]
+    if inferred_agents:
+        console.print(
+            "\n[blue]ℹ️  Note: Agents marked with * are templated using starter pack heuristics for ADK samples.[/]"
+        )
+        console.print(
+            "[dim]   The starter pack attempts to create a working codebase, but you'll need to follow the generated README for complete setup.[/]"
+        )
+
+
 def render_and_merge_makefiles(
     base_template_path: pathlib.Path,
     final_destination: pathlib.Path,

src/cli/utils/template.py

@@ -686,7 +686,7 @@ def process_template(
                 llm_txt_content = f.read()
 
             cookiecutter_config = {
-                "project_name": "my-project",
+                "project_name": project_name,
                 "agent_name": agent_name,
                 "package_version": get_current_version(),
                 "agent_description": template_config.get("description", ""),
@@ -752,6 +752,53 @@ def process_template(
                 logging.debug(
                     f"Copying remote template files from {remote_template_path} to {generated_project_dir}"
                 )
+
+                # Preserve base template README and pyproject.toml files before overwriting
+                preserve_files = ["README.md"]
+
+                # Only preserve pyproject.toml if the remote template doesn't have starter pack integration
+                remote_pyproject = remote_template_path / "pyproject.toml"
+                if remote_pyproject.exists():
+                    try:
+                        remote_pyproject_content = remote_pyproject.read_text()
+                        # Check for starter pack integration markers
+                        has_starter_pack_integration = (
+                            "[tool.agent-starter-pack]" in remote_pyproject_content
+                        )
+                        if not has_starter_pack_integration:
+                            preserve_files.append("pyproject.toml")
+                            logging.debug(
+                                "Remote pyproject.toml lacks starter pack integration - will preserve base template version"
+                            )
+                        else:
+                            logging.debug(
+                                "Remote pyproject.toml has starter pack integration - using remote version only"
+                            )
+                    except Exception as e:
+                        logging.warning(
+                            f"Could not read remote pyproject.toml: {e}. Will preserve base template version."
+                        )
+                        preserve_files.append("pyproject.toml")
+                else:
+                    preserve_files.append("pyproject.toml")
+
+                for preserve_file in preserve_files:
+                    base_file = generated_project_dir / preserve_file
+                    remote_file = remote_template_path / preserve_file
+
+                    if base_file.exists() and remote_file.exists():
+                        # Preserve the base template file with starter_pack prefix
+                        base_name = pathlib.Path(preserve_file).stem
+                        extension = pathlib.Path(preserve_file).suffix
+                        preserved_file = (
+                            generated_project_dir
+                            / f"starter_pack_{base_name}{extension}"
+                        )
+                        shutil.copy2(base_file, preserved_file)
+                        logging.debug(
+                            f"Preserved base template {preserve_file} as starter_pack_{base_name}{extension}"
+                        )
+
                 copy_files(
                     remote_template_path,
                     generated_project_dir,
@@ -884,11 +931,35 @@ def process_template(
                 )
 
                 if generated_project_dir.exists():
+                    # Check for existing README and pyproject.toml files before removing destination
+                    existing_preserved_files = []
                     if final_destination.exists():
+                        for item in final_destination.iterdir():
+                            if item.is_file() and (
+                                item.name.lower().startswith("readme")
+                                or item.name == "pyproject.toml"
+                            ):
+                                existing_preserved_files.append(
+                                    (item.name, item.read_text())
+                                )
                         shutil.rmtree(final_destination)
+
                     shutil.copytree(
                         generated_project_dir, final_destination, dirs_exist_ok=True
                     )
+
+                    # Restore existing README and pyproject.toml files with starter_pack prefix
+                    for file_name, file_content in existing_preserved_files:
+                        base_name = pathlib.Path(file_name).stem
+                        extension = pathlib.Path(file_name).suffix
+                        preserved_file_path = (
+                            final_destination / f"starter_pack_{base_name}{extension}"
+                        )
+                        preserved_file_path.write_text(file_content)
+                        logging.debug(
+                            f"File preservation: existing {file_name} preserved as starter_pack_{base_name}{extension}"
+                        )
+
                     logging.debug(
                         f"Project successfully created at {final_destination}"
                     )

src/deployment_targets/cloud_run/Dockerfile

@@ -16,12 +16,28 @@ FROM python:3.11-slim
 
 RUN pip install --no-cache-dir uv==0.6.12
 
+{%- if cookiecutter.agent_name == 'live_api' %}
+# Install Node.js for frontend build
+RUN apt-get update && apt-get install -y \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+{%- endif %}
+
 WORKDIR /code
 
 COPY ./pyproject.toml ./README.md ./uv.lock* ./
 
 COPY ./{{cookiecutter.agent_directory}} ./{{cookiecutter.agent_directory}}
 
+{%- if cookiecutter.agent_name == 'live_api' %}
+# Copy and build frontend
+COPY ./frontend ./frontend
+RUN cd frontend && npm ci && npm run build
+{%- endif %}
+
 RUN uv sync --frozen
 
 ARG COMMIT_SHA=""

src/deployment_targets/cloud_run/{{cookiecutter.agent_directory}}/server.py

@@ -16,11 +16,14 @@ import asyncio
 import json
 import logging
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any, Literal
 
 import backoff
-from fastapi import FastAPI, WebSocket
+from fastapi import FastAPI, HTTPException, WebSocket
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
 from google.cloud import logging as google_cloud_logging
 from google.genai import types
 from google.genai.types import LiveServerToolCall
@@ -36,6 +39,18 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
+
+# Get the path to the frontend build directory
+current_dir = Path(__file__).parent
+frontend_build_dir = current_dir.parent / "frontend" / "build"
+
+# Mount static files if build directory exists
+if frontend_build_dir.exists():
+    app.mount(
+        "/static",
+        StaticFiles(directory=str(frontend_build_dir / "static")),
+        name="static",
+    )
 logging_client = google_cloud_logging.Client()
 logger = logging_client.logger(__name__)
 logging.basicConfig(level=logging.INFO)
@@ -382,8 +397,41 @@ def collect_feedback(feedback: Feedback) -> dict[str, str]:
     """
     logger.log_struct(feedback.model_dump(), severity="INFO")
     return {"status": "success"}
+{% if cookiecutter.agent_name == "live_api" %}
+
+@app.get("/")
+async def serve_frontend_root() -> FileResponse:
+    """Serve the frontend index.html at the root path."""
+    index_file = frontend_build_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(str(index_file))
+    raise HTTPException(
+        status_code=404,
+        detail="Frontend not built. Run 'npm run build' in the frontend directory.",
+    )
 
 
+@app.get("/{full_path:path}")
+async def serve_frontend_spa(full_path: str) -> FileResponse:
+    """Catch-all route to serve the frontend for SPA routing.
+
+    This ensures that client-side routes are handled by the React app.
+    Excludes API routes (ws, feedback) and static assets.
+    """
+    # Don't intercept API routes
+    if full_path.startswith(("ws", "feedback", "static", "api")):
+        raise HTTPException(status_code=404, detail="Not found")
+
+    # Serve index.html for all other routes (SPA routing)
+    index_file = frontend_build_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(str(index_file))
+    raise HTTPException(
+        status_code=404,
+        detail="Frontend not built. Run 'npm run build' in the frontend directory.",
+    )
+{% endif %}
+
 # Main execution
 if __name__ == "__main__":
     import uvicorn

src/frontends/live_api_react/frontend/src/App.tsx

@@ -21,8 +21,9 @@ import SidePanel from "./components/side-panel/SidePanel";
 import ControlTray from "./components/control-tray/ControlTray";
 import cn from "classnames";
 
-const defaultHost = "localhost:8000";
-const defaultUri = `ws://${defaultHost}/`;
+// Use relative URLs that work with integrated setup and deployments
+const defaultHost = window.location.host;
+const defaultUri = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${defaultHost}/`;
 
 function App() {
   const videoRef = useRef<HTMLVideoElement>(null);

src/frontends/live_api_react/frontend/src/utils/multimodal-live-client.ts

@@ -74,7 +74,9 @@ export class MultimodalLiveClient extends EventEmitter<MultimodalLiveClientEvent
   private userId?: string;
   constructor({ url, userId, runId }: MultimodalLiveAPIClientConnection) {
     super();
-    url = url || `ws://localhost:8000/ws`;
+    // Use relative URL that works with integrated setup and deployments
+    const defaultWsUrl = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/ws`;
+    url = url || defaultWsUrl;
     this.url = new URL("ws", url).href;
     this.userId = userId;
     this.runId = runId || crypto.randomUUID(); // Ensure runId is always a string by providing default