agent-starter-pack 0.9.2__py3-none-any.whl → 0.10.0__py3-none-any.whl

src/base_template/{% if cookiecutter.cicd_runner == 'github_actions' %}.github{% else %}unused_github{% endif %}/workflows/pr_checks.yaml

@@ -0,0 +1,65 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: PR Checks
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'app/**'
+      - 'data_ingestion/**'
+      - 'tests/**'
+      - 'deployment/**'
+      - 'uv.lock'
+{%- if cookiecutter.data_ingestion %}
+      - 'data_ingestion/**'
+{%- endif %}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: 'read'
+      id-token: 'write'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        
+      - id: 'auth'
+        name: 'Authenticate to Google Cloud'
+        uses: 'google-github-actions/auth@v2'
+        with:
+          workload_identity_provider: 'projects/{% raw %}${{ vars.GCP_PROJECT_NUMBER }}{% endraw %}/locations/global/workloadIdentityPools/{% raw %}${{ secrets.WIF_POOL_ID }}{% endraw %}/providers/{% raw %}${{ secrets.WIF_PROVIDER_ID }}{% endraw %}'
+          service_account: '{% raw %}${{ secrets.GCP_SERVICE_ACCOUNT }}{% endraw %}'
+          create_credentials_file: true
+          project_id: {% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}
+
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install uv and dependencies
+        run: |
+          pip install uv==0.6.12
+          uv sync --locked
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration

src/base_template/{% if cookiecutter.cicd_runner == 'github_actions' %}.github{% else %}unused_github{% endif %}/workflows/staging.yaml

@@ -0,0 +1,170 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Deploy to Staging
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'app/**'
+      - 'data_ingestion/**'
+      - 'tests/**'
+      - 'deployment/**'
+      - 'uv.lock'
+
+jobs:
+  deploy_and_test_staging:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: 'read'
+      id-token: 'write'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - id: 'auth'
+        name: 'Authenticate to Google Cloud'
+        uses: 'google-github-actions/auth@v2'
+        with:
+          workload_identity_provider: 'projects/{% raw %}${{ vars.GCP_PROJECT_NUMBER }}{% endraw %}/locations/global/workloadIdentityPools/{% raw %}${{ secrets.WIF_POOL_ID }}{% endraw %}/providers/{% raw %}${{ secrets.WIF_PROVIDER_ID }}{% endraw %}'
+          service_account: '{% raw %}${{ secrets.GCP_SERVICE_ACCOUNT }}{% endraw %}'
+          create_credentials_file: true
+          project_id: {% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+
+      - name: Set up Cloud SDK
+        uses: 'google-github-actions/setup-gcloud@v2'
+{%- endif %}
+{%- if cookiecutter.data_ingestion %}
+
+      - name: Deploy data ingestion pipeline (Staging)
+        run: |
+          cd data_ingestion && pip install uv==0.6.12 && cd data_ingestion_pipeline && \
+          uv sync --locked && uv run python submit_pipeline.py
+        env:
+          PIPELINE_ROOT: {% raw %}${{ vars.PIPELINE_GCS_ROOT_STAGING }}{% endraw %}
+          REGION: {% raw %}${{ vars.REGION }}{% endraw %}
+{%- if cookiecutter.datastore_type == "vertex_ai_search" %}
+          DATA_STORE_REGION: {% raw %}${{ vars.DATA_STORE_REGION }}{% endraw %}
+          DATA_STORE_ID: {% raw %}${{ vars.DATA_STORE_ID_STAGING }}{% endraw %}
+{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %}
+          VECTOR_SEARCH_INDEX: {% raw %}${{ vars.VECTOR_SEARCH_INDEX_STAGING }}{% endraw %}
+          VECTOR_SEARCH_INDEX_ENDPOINT: {% raw %}${{ vars.VECTOR_SEARCH_INDEX_ENDPOINT_STAGING }}{% endraw %}
+          VECTOR_SEARCH_BUCKET: {% raw %}${{ vars.VECTOR_SEARCH_BUCKET_STAGING }}{% endraw %}
+{%- endif %}
+          PROJECT_ID: {% raw %}${{ vars.STAGING_PROJECT_ID }}{% endraw %}
+          SERVICE_ACCOUNT: {% raw %}${{ vars.PIPELINE_SA_EMAIL_STAGING }}{% endraw %}
+          PIPELINE_NAME: {% raw %}${{ vars.PIPELINE_NAME }}{% endraw %}
+{%- endif %}
+
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+
+      - name: Configure Docker for Artifact Registry
+        run: |
+          gcloud auth configure-docker {% raw %}${{ vars.REGION }}{% endraw %}-docker.pkg.dev --quiet
+          
+      - name: Build and Push Docker Image
+        run: |
+          docker build -t {% raw %}${{ vars.REGION }}{% endraw %}-docker.pkg.dev/{% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}/{% raw %}${{ vars.ARTIFACT_REGISTRY_REPO_NAME }}{% endraw %}/{% raw %}${{ vars.CONTAINER_NAME }}{% endraw %} \
+            --build-arg COMMIT_SHA={% raw %}${{ github.sha }}{% endraw %} .
+          docker push {% raw %}${{ vars.REGION }}{% endraw %}-docker.pkg.dev/{% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}/{% raw %}${{ vars.ARTIFACT_REGISTRY_REPO_NAME }}{% endraw %}/{% raw %}${{ vars.CONTAINER_NAME }}{% endraw %}
+
+      - name: Deploy to Staging (Cloud Run)
+        run: |
+          gcloud run deploy {{cookiecutter.project_name}} \
+            --image {% raw %}${{ vars.REGION }}{% endraw %}-docker.pkg.dev/{% raw %}${{ vars.CICD_PROJECT_ID }}{% endraw %}/{% raw %}${{ vars.ARTIFACT_REGISTRY_REPO_NAME }}{% endraw %}/{% raw %}${{ vars.CONTAINER_NAME }}{% endraw %} \
+            --region {% raw %}${{ vars.REGION }}{% endraw %} \
+            --project {% raw %}${{ vars.STAGING_PROJECT_ID }}{% endraw %}
+
+      - name: Fetch Staging Service URL
+        id: fetch-url
+        run: |
+          _STAGING_URL=$(gcloud run services describe {{cookiecutter.project_name}} \
+            --region {% raw %}${{ vars.REGION }}{% endraw %} --project {% raw %}${{ vars.STAGING_PROJECT_ID }}{% endraw %} --format="value(status.url)")
+          echo "_staging_url=${_STAGING_URL}" >> $GITHUB_OUTPUT
+
+      - name: Fetch ID Token
+        id: fetch-token
+        run: |
+          _ID_TOKEN=$(gcloud auth print-identity-token --impersonate-service-account={% raw %}${{ secrets.GCP_SERVICE_ACCOUNT }}{% endraw %} -q)
+          echo "::add-mask::${_ID_TOKEN}"
+          echo "_id_token=${_ID_TOKEN}" >> $GITHUB_OUTPUT
+
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+
+      - name: Install uv and dependencies
+        run: |
+          pip install uv==0.6.12
+          uv sync --locked
+
+      - name: Deploy to Staging (Agent Engine)
+        run: |
+          uv export --no-hashes --no-sources --no-header --no-dev --no-emit-project --no-annotate --locked > .requirements.txt
+          uv run app/agent_engine_app.py \
+            --project {% raw %}${{ vars.STAGING_PROJECT_ID }}{% endraw %} \
+            --location {% raw %}${{ vars.REGION }}{% endraw %} \
+            --set-env-vars="COMMIT_SHA={% raw %}${{ github.sha }}{% endraw %}{%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID={% raw %}${{ vars.DATA_STORE_ID_STAGING }}{% endraw %},DATA_STORE_REGION={% raw %}${{ vars.DATA_STORE_REGION }}{% endraw %}{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX={% raw %}${{ vars.VECTOR_SEARCH_INDEX_STAGING }}{% endraw %},VECTOR_SEARCH_INDEX_ENDPOINT={% raw %}${{ vars.VECTOR_SEARCH_INDEX_ENDPOINT_STAGING }}{% endraw %},VECTOR_SEARCH_BUCKET={% raw %}${{ vars.VECTOR_SEARCH_BUCKET_STAGING }}{% endraw %}{%- endif %}{%- endif %}"
+
+      - name: Fetch Auth Token
+        id: fetch-token
+        run: |
+          _AUTH_TOKEN=$(gcloud auth print-access-token -q)
+          echo "::add-mask::${_AUTH_TOKEN}"
+          echo "_auth_token=${_AUTH_TOKEN}" >> $GITHUB_OUTPUT
+{%- endif %}
+
+      - name: Run load test
+        run: |
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+          export _ID_TOKEN="{% raw %}${{ steps.fetch-token.outputs._id_token }}{% endraw %}"
+          export _STAGING_URL="{% raw %}${{ steps.fetch-url.outputs._staging_url }}{% endraw %}"
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+          export _AUTH_TOKEN="{% raw %}${{ steps.fetch-token.outputs._auth_token }}{% endraw %}"
+{%- endif %}
+          pip install locust==2.31.1
+          locust -f tests/load_test/load_test.py \
+          --headless \
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+          -H ${_STAGING_URL} \
+          -t 30s -u 10 -r 0.5 \
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+          -t 30s -u 2 -r 0.5 \
+{%- endif %}
+          --csv=tests/load_test/.results/results \
+          --html=tests/load_test/.results/report.html
+
+      - name: Export Load Test Results to GCS
+        run: |
+          TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+          gcloud storage cp --recursive tests/load_test/.results gs://{% raw %}${{ vars.BUCKET_NAME_LOAD_TEST_RESULTS }}{% endraw %}/results-${TIMESTAMP} --quiet
+          echo "_________________________________________________________________________"
+          echo "Load test results copied to gs://{% raw %}${{ vars.BUCKET_NAME_LOAD_TEST_RESULTS }}{% endraw %}/results-${TIMESTAMP}"
+          echo "HTTP link: https://console.cloud.google.com/storage/browser/{% raw %}${{ vars.BUCKET_NAME_LOAD_TEST_RESULTS }}{% endraw %}/results-${TIMESTAMP}"
+          echo "_________________________________________________________________________"
+
+  call_production_workflow:
+    needs: deploy_and_test_staging
+    uses: ./.github/workflows/deploy-to-prod.yaml
+    permissions:
+      contents: 'read'
+      id-token: 'write'
+    secrets: inherit

src/base_template/{deployment/cd/deploy-to-prod.yaml → {% if cookiecutter.cicd_runner == 'google_cloud_build' %}.cloudbuild{% else %}unused_.cloudbuild{% endif %}/deploy-to-prod.yaml }

@@ -23,18 +23,18 @@ steps:
         cd data_ingestion && pip install uv==0.6.12 --user && cd data_ingestion_pipeline && \
         uv sync --locked && uv run python submit_pipeline.py
     env:
-      - "PIPELINE_ROOT=${_PIPELINE_GCS_ROOT}"
+      - "PIPELINE_ROOT=${_PIPELINE_GCS_ROOT_PROD}"
       - "REGION=${_REGION}"
       {%- if cookiecutter.datastore_type == "vertex_ai_search" %}
       - "DATA_STORE_REGION=${_DATA_STORE_REGION}"
-      - "DATA_STORE_ID=${_DATA_STORE_ID}"
+      - "DATA_STORE_ID=${_DATA_STORE_ID_PROD}"
       {%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %}
-      - "VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX}"
-      - "VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT}"
-      - "VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET}"
+      - "VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX_PROD}"
+      - "VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT_PROD}"
+      - "VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET_PROD}"
       {%- endif %}
       - "PROJECT_ID=${_PROD_PROJECT_ID}"
-      - "SERVICE_ACCOUNT=${_PIPELINE_SA_EMAIL}"
+      - "SERVICE_ACCOUNT=${_PIPELINE_SA_EMAIL_PROD}"
       - "PIPELINE_NAME=${_PIPELINE_NAME}"
       - "CRON_SCHEDULE=${_PIPELINE_CRON_SCHEDULE}"
       - "DISABLE_CACHING=TRUE"
@@ -77,7 +77,7 @@ steps:
         uv run app/agent_engine_app.py \
           --project ${_PROD_PROJECT_ID} \
           --location ${_REGION} \
-          --set-env-vars="COMMIT_SHA=${COMMIT_SHA}{%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID=${_DATA_STORE_ID},DATA_STORE_REGION=${_DATA_STORE_REGION}{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX},VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT},VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET}{%- endif %}{%- endif %}"
+          --set-env-vars="COMMIT_SHA=${COMMIT_SHA}{%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID=${_DATA_STORE_ID_PROD},DATA_STORE_REGION=${_DATA_STORE_REGION}{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX_PROD},VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT_PROD},VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET_PROD}{%- endif %}{%- endif %}"
     env:
       - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
 {%- endif %}

src/base_template/{deployment/cd/staging.yaml → {% if cookiecutter.cicd_runner == 'google_cloud_build' %}.cloudbuild{% else %}unused_.cloudbuild{% endif %}/staging.yaml }

@@ -23,18 +23,18 @@ steps:
         cd data_ingestion && pip install uv==0.6.12 --user && cd data_ingestion_pipeline && \
         uv sync --locked && uv run python submit_pipeline.py
     env:
-      - "PIPELINE_ROOT=${_PIPELINE_GCS_ROOT}"
+      - "PIPELINE_ROOT=${_PIPELINE_GCS_ROOT_STAGING}"
       - "REGION=${_REGION}"
 {%- if cookiecutter.datastore_type == "vertex_ai_search" %}
       - "DATA_STORE_REGION=${_DATA_STORE_REGION}"
-      - "DATA_STORE_ID=${_DATA_STORE_ID}"
+      - "DATA_STORE_ID=${_DATA_STORE_ID_STAGING}"
 {%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %}
-      - "VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX}"
-      - "VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT}"
-      - "VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET}"
+      - "VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX_STAGING}"
+      - "VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT_STAGING}"
+      - "VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET_STAGING}"
 {%- endif %}
       - "PROJECT_ID=${_STAGING_PROJECT_ID}"
-      - "SERVICE_ACCOUNT=${_PIPELINE_SA_EMAIL}"
+      - "SERVICE_ACCOUNT=${_PIPELINE_SA_EMAIL_STAGING}"
       - "PIPELINE_NAME=${_PIPELINE_NAME}"
       - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
 {%- endif %}
@@ -111,7 +111,7 @@ steps:
         uv run app/agent_engine_app.py \
           --project ${_STAGING_PROJECT_ID} \
           --location ${_REGION} \
-          --set-env-vars="COMMIT_SHA=${COMMIT_SHA}{%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID=${_DATA_STORE_ID},DATA_STORE_REGION=${_DATA_STORE_REGION}{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX},VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT},VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET}{%- endif %}{%- endif %}"
+          --set-env-vars="COMMIT_SHA=${COMMIT_SHA}{%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID=${_DATA_STORE_ID_STAGING},DATA_STORE_REGION=${_DATA_STORE_REGION}{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX=${_VECTOR_SEARCH_INDEX_STAGING},VECTOR_SEARCH_INDEX_ENDPOINT=${_VECTOR_SEARCH_INDEX_ENDPOINT_STAGING},VECTOR_SEARCH_BUCKET=${_VECTOR_SEARCH_BUCKET_STAGING}{%- endif %}{%- endif %}"
     env:
       - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
 

src/cli/commands/create.py

@@ -40,6 +40,7 @@ from ..utils.template import (
     get_template_path,
     load_template_config,
     process_template,
+    prompt_cicd_runner_selection,
     prompt_datastore_selection,
     prompt_deployment_target,
     prompt_session_type_selection,
@@ -96,6 +97,11 @@ def normalize_project_name(project_name: str) -> str:
     type=click.Choice(["agent_engine", "cloud_run"]),
     help="Deployment target name",
 )
+@click.option(
+    "--cicd-runner",
+    type=click.Choice(["google_cloud_build", "github_actions"]),
+    help="CI/CD runner to use",
+)
 @click.option(
     "--include-data-ingestion",
     "-i",
@@ -110,7 +116,7 @@ def normalize_project_name(project_name: str) -> str:
 )
 @click.option(
     "--session-type",
-    type=click.Choice(["in_memory", "alloydb"]),
+    type=click.Choice(["in_memory", "alloydb", "agent_engine"]),
     help="Type of session storage to use",
 )
 @click.option("--debug", is_flag=True, help="Enable debug logging")
@@ -140,6 +146,7 @@ def create(
     project_name: str,
     agent: str | None,
     deployment_target: str | None,
+    cicd_runner: str | None,
     include_data_ingestion: bool,
     datastore: str | None,
     session_type: str | None,
@@ -430,6 +437,20 @@ def create(
         if debug and final_session_type:
             logging.debug(f"Selected session type: {final_session_type}")
 
+        # CI/CD runner selection
+        final_cicd_runner = cicd_runner
+        if not final_cicd_runner:
+            if auto_approve:
+                final_cicd_runner = "google_cloud_build"
+                console.print(
+                    "Info: --cicd-runner not specified. Defaulting to 'google_cloud_build' in auto-approve mode.",
+                    style="yellow",
+                )
+            else:
+                final_cicd_runner = prompt_cicd_runner_selection()
+        if debug:
+            logging.debug(f"Selected CI/CD runner: {final_cicd_runner}")
+
         # Region confirmation (if not explicitly passed)
         if (
             not auto_approve
@@ -460,7 +481,7 @@ def create(
                 )
                 console.print(
                     "> Please check your authentication settings and permissions. "
-                    "Visit https://cloud.google.com/vertex-ai/docs/authentication for help.",
+                    "> Visit https://cloud.google.com/vertex-ai/docs/authentication for help.",
                     style="yellow",
                 )
                 console.print(
@@ -490,6 +511,7 @@ def create(
                 template_path,
                 project_name,
                 deployment_target=final_deployment,
+                cicd_runner=final_cicd_runner,
                 include_data_ingestion=include_data_ingestion,
                 datastore=datastore,
                 session_type=final_session_type,
@@ -584,14 +606,108 @@ def display_agent_selection(deployment_target: str | None = None) -> str:
             f"{num}. [bold]{agent['name']}[/] - [dim]{agent['description']}[/]"
         )
 
+    # Add special option for adk-samples
+    adk_samples_option = len(agents) + 1
+    console.print(
+        f"{adk_samples_option}. [bold]Browse agents from [link=https://github.com/google/adk-samples]google/adk-samples[/link][/] - [dim]Discover additional samples[/]"
+    )
+
     choice = IntPrompt.ask(
         "\nEnter the number of your template choice", default=1, show_default=True
     )
 
-    if choice not in agents:
+    if choice == adk_samples_option:
+        return display_adk_samples_selection()
+    elif choice in agents:
+        return agents[choice]["name"]
+    else:
         raise ValueError(f"Invalid agent selection: {choice}")
 
-    return agents[choice]["name"]
+
+def display_adk_samples_selection() -> str:
+    """Display adk-samples agents and prompt for selection."""
+
+    from ..utils.remote_template import fetch_remote_template, parse_agent_spec
+
+    console.print("\n> Fetching agents from [bold blue]google/adk-samples[/]...")
+
+    try:
+        # Parse the adk-samples repository
+        spec = parse_agent_spec("https://github.com/google/adk-samples")
+        if not spec:
+            raise RuntimeError("Failed to parse adk-samples repository")
+
+        # Fetch the repository
+        repo_path, _ = fetch_remote_template(spec)
+
+        # Scan for agents in the repository
+        adk_agents = {}
+        agent_count = 1
+
+        # Search for templateconfig.yaml files to identify agents
+        for config_path in sorted(repo_path.glob("**/templateconfig.yaml")):
+            try:
+                import yaml
+
+                with open(config_path, encoding="utf-8") as f:
+                    config = yaml.safe_load(f)
+
+                agent_name = config.get("name", config_path.parent.parent.name)
+                description = config.get("description", "No description available")
+
+                # Get the relative path from repo root
+                relative_path = config_path.parent.parent.relative_to(repo_path)
+
+                adk_agents[agent_count] = {
+                    "name": agent_name,
+                    "description": description,
+                    "path": str(relative_path),
+                    "spec": f"adk@{relative_path}",
+                }
+                agent_count += 1
+
+            except Exception as e:
+                logging.warning(
+                    f"Could not load agent from {config_path.parent.parent}: {e}"
+                )
+
+        if not adk_agents:
+            console.print("No agents found in adk-samples repository", style="yellow")
+            # Fall back to local agents
+            return display_agent_selection()
+
+        console.print("\n> Available agents from [bold blue]google/adk-samples[/]:")
+        for num, agent in adk_agents.items():
+            console.print(
+                f"{num}. [bold]{agent['name']}[/] - [dim]{agent['description']}[/]"
+            )
+
+        # Add option to go back to local agents
+        back_option = len(adk_agents) + 1
+        console.print(
+            f"{back_option}. [bold]← Back to built-in agents[/] - [dim]Return to local agent selection[/]"
+        )
+
+        choice = IntPrompt.ask(
+            "\nEnter the number of your choice", default=1, show_default=True
+        )
+
+        if choice == back_option:
+            return display_agent_selection()
+        elif choice in adk_agents:
+            # Return the adk@ spec for the selected agent
+            selected_agent = adk_agents[choice]
+            console.print(
+                f"\n> Selected: [bold]{selected_agent['name']}[/] from adk-samples"
+            )
+            return selected_agent["spec"]
+        else:
+            raise ValueError(f"Invalid agent selection: {choice}")
+
+    except Exception as e:
+        console.print(f"Error fetching adk-samples agents: {e}", style="bold red")
+        console.print("Falling back to built-in agents...", style="yellow")
+        return display_agent_selection()
 
 
 def set_gcp_project(project_id: str, set_quota_project: bool = True) -> None:

src/cli/commands/list.py

@@ -45,7 +45,7 @@ def display_agents_from_path(base_path: pathlib.Path, source_name: str) -> None:
     # Search for templateconfig.yaml files to identify agents
     for config_path in sorted(base_path.glob("**/templateconfig.yaml")):
         try:
-            with open(config_path) as f:
+            with open(config_path, encoding="utf-8") as f:
                 config = yaml.safe_load(f)
 
             agent_name = config.get("name", config_path.parent.parent.name)