agent-starter-pack 0.12.0__tar.gz → 0.13.0__tar.gz

agent_starter_pack-0.13.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(PROJECT_IDS=agent-starter-pack-e2e-dev,agent-starter-pack-e2e-st,agent-starter-pack-e2e-pr python tests/cicd/scripts/delete_vector_search.py)",
+      "Bash(make lint)",
+      "Bash(uv run pytest tests/cli/commands/test_create.py::TestCreateCommand::test_create_existing_project_dir -v -s)",
+      "Bash(gcloud serverless vpc-connectors list --project=agent-starter-pack-e2e-dev --region=europe-west1)",
+      "Bash(gcloud compute networks vpc-access connectors list --project=agent-starter-pack-e2e-dev --region=europe-west1)",
+      "Bash(gcloud alpha network-services address-reservations list --project=agent-starter-pack-e2e-dev --location=europe-west1)",
+      "Bash(gcloud beta serverless address-reservations list --project=agent-starter-pack-e2e-dev --location=europe-west1)",
+      "Bash(gcloud run services delete test-797fa619-1755528509 --region=europe-west1 --project=agent-starter-pack-e2e-dev --quiet)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/GEMINI.md

@@ -114,17 +114,57 @@ The project maintains parallel CI/CD implementations. **Any change to CI/CD logi
 
 When adding a new variable or secret, ensure it is configured correctly for both systems in the Terraform scripts that manage them (e.g., `github_actions_variable` resource and Cloud Build trigger substitutions).
 
-## File Modification Checklist
+## Advanced Template System Patterns
+
+### 4-Layer Architecture
+Template processing follows this hierarchy (later layers override earlier ones):
+1. **Base Template** (`src/base_template/`) - Applied to ALL projects
+2. **Deployment Targets** (`src/deployment_targets/`) - Environment overrides  
+3. **Frontend Types** (`src/frontends/`) - UI-specific files
+4. **Agent Templates** (`agents/*/`) - Individual agent logic
+
+**Rule**: Always place changes in the correct layer. Check if deployment targets need corresponding updates.
+
+### Template Processing Flow
+1. Variable resolution from `cookiecutter.json`
+2. File copying (base → overlays)
+3. Jinja2 rendering of content
+4. File/directory name rendering
+
+### Cross-File Dependencies
+Changes often require coordinated updates:
+- **Configuration**: `templateconfig.yaml` → `cookiecutter.json` → rendered templates
+- **CI/CD**: `.github/workflows/` ↔ `.cloudbuild/` (must stay in sync)
+- **Infrastructure**: Base terraform → deployment target overrides
+
+### Conditional Logic Patterns
+```jinja
+{%- if cookiecutter.agent_name == "live_api" %}
+# Agent-specific logic
+{%- elif cookiecutter.deployment_target == "cloud_run" %}
+# Deployment-specific logic  
+{%- endif %}
+```
 
-Before finalizing any change, verify the following:
+### Testing Strategy
+Test changes across multiple dimensions:
+- Agent types (live_api, adk_base, etc.)
+- Deployment targets (cloud_run, agent_engine)
+- Feature combinations (data_ingestion, frontend_type)
+
+### Common Pitfalls
+- **Hardcoded URLs**: Use relative paths for frontend connections
+- **Missing Conditionals**: Wrap agent-specific code in proper `{% if %}` blocks
+- **Dependency Conflicts**: Some agents lack certain extras (e.g., live_api + lint)
+
+## File Modification Checklist
 
--   [ ] **Jinja Syntax:** Are all `{% if %}` and `{% for %}` blocks correctly closed with `{% endif %}` and `{% endfor %}`?
--   [ ] **Variable Consistency:** Is the `cookiecutter.` variable name spelled correctly and used consistently across all modified files?
--   [ ] **Cross-Target Impact:** If you changed the `base_template`, have you checked if any `deployment_targets` need corresponding updates?
--   [ ] **CI/CD Parity:** If you modified a CI/CD workflow, did you apply the equivalent change to the other system (GitHub Actions vs. Cloud Build)?
--   [ ] **Terraform Validation:** If you changed Terraform files, are resource references correct? Does it pass `terraform validate`?
--   [ ] **Documentation:** Does any user-facing documentation in `docs/` need to be updated to reflect the change?
+-   [ ] **Jinja Syntax:** All `{% if %}` and `{% for %}` blocks correctly closed?
+-   [ ] **Variable Consistency:** `cookiecutter.` variables spelled correctly?
+-   [ ] **Cross-Target Impact:** Base template changes checked against deployment targets?
+-   [ ] **CI/CD Parity:** Changes applied to both GitHub Actions and Cloud Build?
+-   [ ] **Multi-Agent Testing:** Tested with different agent types and configurations?
 
 ### Key Tooling
 
--   **`uv` for Python Command Execution:** `uv` is the primary tool used for managing Python dependencies and executing Python commands within the project, including CLI operations and CI/CD steps. This ensures consistent, isolated, and efficient execution environments.
+-   **`uv` for Python:** Primary tool for dependency management and CLI execution

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.12.0
+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
@@ -12,6 +12,7 @@ Requires-Dist: cookiecutter~=2.6.0
 Requires-Dist: google-cloud-aiplatform>=1.87.0
 Requires-Dist: pyyaml>=6.0.1
 Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.29.5; extra == 'jupyter'
 Requires-Dist: jupyter; extra == 'jupyter'

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.12.0"
+version = "0.13.0"
 description = "CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates."
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },
@@ -15,6 +15,7 @@ dependencies = [
     "rich>=13.7.0",
     "pyyaml>=6.0.1",
     "backoff>=2.2.1",
+    "tomli>=1.1.0; python_version < \"3.11\"",
 ]
 
 [dependency-groups]
@@ -88,7 +89,7 @@ select = [
     "RUF", # ruff specific rules
     "PLW1514", # unspecified-encoding (require encoding in open calls)
 ]
-ignore = ["E501", "C901", "RUF001"]
+ignore = ["E501", "C901", "RUF001", "UP036"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["app", "frontend"]

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/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

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/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.

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/src/cli/commands/create.py

@@ -19,7 +19,6 @@ import pathlib
 import shutil
 import subprocess
 import tempfile
-import tomllib
 from collections.abc import Callable
 
 import click
@@ -244,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)
@@ -307,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@"):
@@ -348,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()
@@ -397,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}")
 
@@ -409,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
@@ -774,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
+        # Use shared ADK discovery function
+        from ..utils.remote_template import discover_adk_agents
 
-        # 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 ""
-                )
-
-                # 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")
@@ -831,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
@@ -1030,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}"
@@ -1053,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(

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/src/cli/commands/enhance.py

@@ -13,12 +13,18 @@
 # limitations under the License.
 
 import pathlib
+import sys
 from typing import Any
 
 import click
 from rich.console import Console
 from rich.prompt import IntPrompt
 
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
 from ..utils.logging import display_welcome_banner, handle_cli_error
 from ..utils.template import get_available_agents
 from .create import (
@@ -253,8 +259,6 @@ def enhance(
             pyproject_path = current_dir / "pyproject.toml"
             if pyproject_path.exists():
                 try:
-                    import tomllib
-
                     with open(pyproject_path, "rb") as f:
                         pyproject_data = tomllib.load(f)
                     packages = (

{agent_starter_pack-0.12.0 → agent_starter_pack-0.13.0}/src/cli/commands/list.py

@@ -14,9 +14,14 @@
 
 import logging
 import pathlib
-import tomllib
+import sys
 
 import click
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 from rich.console import Console
 from rich.table import Table
 
@@ -26,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}[/]",
@@ -42,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 ""
+                )
 
-        except Exception as e:
-            logging.warning(f"Could not load agent from {config_path.parent}: {e}")
+                # Display the agent's path relative to the scanned directory
+                relative_path = template_root.relative_to(base_path)
+
+                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)
 
 
@@ -98,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")