agent-starter-pack 0.14.1__tar.gz → 0.15.0__tar.gz

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/.claude/settings.local.json

@@ -10,7 +10,11 @@
       "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)",
       "Bash(make test)",
-      "WebFetch(domain:github.com)"
+      "WebFetch(domain:github.com)",
+      "Bash(uv run ruff check --fix tests/cli/utils/test_remote_template.py)",
+      "Bash(uv run ruff check tests/cli/utils/test_remote_template.py)",
+      "Bash(uv run pytest tests/cli/utils/test_remote_template.py -v)",
+      "Bash(uv run pytest tests/integration/test_pipeline_parity.py::test_staging_parity -v -s)"
     ],
     "deny": [],
     "ask": []

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.14.1
+Version: 0.15.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
@@ -8,7 +8,7 @@ License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: backoff>=2.2.1
 Requires-Dist: click>=8.1.7
-Requires-Dist: cookiecutter~=2.6.0
+Requires-Dist: cookiecutter<3.0.0,>=2.6.0
 Requires-Dist: google-cloud-aiplatform>=1.87.0
 Requires-Dist: pyyaml>=6.0.1
 Requires-Dist: rich>=13.7.0

{agent_starter_pack-0.14.1/agents/agentic_rag → agent_starter_pack-0.15.0/agents/adk_base}/notebooks/adk_app_testing.ipynb

@@ -40,48 +40,64 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "import json\n",
     "\n",
     "import requests\n",
-    "import vertexai.agent_engines"
+    "import vertexai"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## If you are using Agent Engine\n",
-    "See more documentation at [Agent Engine Overview](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)"
+    "### Initialize Vertex AI Client"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize the Vertex AI client\n",
+    "LOCATION = \"us-central1\"\n",
+    "\n",
+    "client = vertexai.Client(\n",
+    "    location=LOCATION,\n",
+    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Remote Testing"
+    "## If you are using Agent Engine\n",
+    "See more documentation at [Agent Engine Overview](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 4,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# Replace with your Agent Engine ID\n",
-    "AGENT_ENGINE_ID = \"projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID\""
+    "### Remote Testing"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "remote_agent_engine = vertexai.agent_engines.get(AGENT_ENGINE_ID)"
+    "# Replace PROJECT_ID and ENGINE_ID with your values\n",
+    "AGENT_ENGINE_ID = \"projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID\"\n",
+    "\n",
+    "# Get the existing agent engine\n",
+    "remote_agent_engine = client.agent_engines.get(name=AGENT_ENGINE_ID)\n",
+    "print(f\"Retrieved agent engine: {remote_agent_engine.api_resource.name}\")"
    ]
   },
   {
@@ -90,7 +106,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for event in remote_agent_engine.stream_query(message=\"hi!\", user_id=\"test\"):\n",
+    "async for event in remote_agent_engine.async_stream_query(\n",
+    "    message=\"hi!\", user_id=\"test\"\n",
+    "):\n",
     "    print(event)"
    ]
   },
@@ -126,7 +144,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -153,7 +171,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for event in agent_engine.stream_query(message=\"hi!\", user_id=\"test\"):\n",
+    "async for event in agent_engine.async_stream_query(message=\"hi!\", user_id=\"test\"):\n",
     "    print(event)"
    ]
   },
@@ -180,7 +198,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -336,7 +354,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "myagent-1757939450",
    "language": "python",
    "name": "python3"
   },
@@ -350,7 +368,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.2"
+   "version": "3.12.9"
   }
  },
  "nbformat": 4,

{agent_starter_pack-0.14.1/agents/adk_base → agent_starter_pack-0.15.0/agents/agentic_rag}/notebooks/adk_app_testing.ipynb

@@ -40,48 +40,64 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "import json\n",
     "\n",
     "import requests\n",
-    "import vertexai.agent_engines"
+    "import vertexai"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## If you are using Agent Engine\n",
-    "See more documentation at [Agent Engine Overview](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)"
+    "### Initialize Vertex AI Client"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize the Vertex AI client\n",
+    "LOCATION = \"us-central1\"\n",
+    "\n",
+    "client = vertexai.Client(\n",
+    "    location=LOCATION,\n",
+    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Remote Testing"
+    "## If you are using Agent Engine\n",
+    "See more documentation at [Agent Engine Overview](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 4,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# Replace with your Agent Engine ID\n",
-    "AGENT_ENGINE_ID = \"projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID\""
+    "### Remote Testing"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "remote_agent_engine = vertexai.agent_engines.get(AGENT_ENGINE_ID)"
+    "# Replace PROJECT_ID and ENGINE_ID with your values\n",
+    "AGENT_ENGINE_ID = \"projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID\"\n",
+    "\n",
+    "# Get the existing agent engine\n",
+    "remote_agent_engine = client.agent_engines.get(name=AGENT_ENGINE_ID)\n",
+    "print(f\"Retrieved agent engine: {remote_agent_engine.api_resource.name}\")"
    ]
   },
   {
@@ -90,7 +106,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for event in remote_agent_engine.stream_query(message=\"hi!\", user_id=\"test\"):\n",
+    "async for event in remote_agent_engine.async_stream_query(\n",
+    "    message=\"hi!\", user_id=\"test\"\n",
+    "):\n",
     "    print(event)"
    ]
   },
@@ -126,7 +144,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -153,7 +171,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for event in agent_engine.stream_query(message=\"hi!\", user_id=\"test\"):\n",
+    "async for event in agent_engine.async_stream_query(message=\"hi!\", user_id=\"test\"):\n",
     "    print(event)"
    ]
   },
@@ -180,7 +198,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -336,7 +354,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "myagent-1757939450",
    "language": "python",
    "name": "python3"
   },
@@ -350,7 +368,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.2"
+   "version": "3.12.9"
   }
  },
  "nbformat": 4,

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/docs/remote-templates/creating-remote-templates.md

@@ -231,6 +231,57 @@ dependencies = [
 
 **Best Practice:** Always include a `uv.lock` file for reproducible builds.
 
+### Version Locking for Guaranteed Compatibility
+
+For maximum compatibility and stability, you can lock your remote template to a specific version of the Agent Starter Pack. This ensures that your template will always be processed with the exact version it was designed for, preventing potential breaking changes from affecting your users.
+
+**To enable version locking:**
+
+1. **Add agent-starter-pack as a dev dependency** in your `pyproject.toml`:
+   ```toml
+   [dependency-groups]
+   dev = [
+       "agent-starter-pack==0.14.1",  # Lock to specific version
+       # ... your other dev dependencies
+   ]
+   ```
+
+2. **Generate the lock file:**
+   ```bash
+   uv lock
+   ```
+
+3. **Commit both files:**
+   ```bash
+   git add pyproject.toml uv.lock
+   git commit -m "Lock agent-starter-pack version for compatibility"
+   ```
+
+**How it works:**
+- When users fetch your remote template, the starter pack automatically detects the locked version in `uv.lock`
+- It then executes `uvx agent-starter-pack==VERSION` with the locked version (requires `uv` to be installed)
+- This guarantees your template is processed with the exact version you tested it with
+
+**Requirements:**
+- Users must have `uv` installed to use version-locked templates
+- If `uv` is not available, the command will fail with installation instructions
+
+**When to use version locking:**
+- ✅ Your template uses specific starter pack features that might change
+- ✅ You want to guarantee long-term stability for your users
+- ✅ Your template is critical infrastructure that needs predictable behavior
+- ❌ You always want the latest starter pack features (trade-off: potential breaking changes)
+
+**Example user experience:**
+```bash
+uvx agent-starter-pack create my-project -a github.com/you/your-template
+
+# Output:
+# 🔒 Remote template specifies agent-starter-pack version 0.14.1 in uv.lock
+# 📦 Executing nested command: uvx agent-starter-pack==0.14.1
+# [continues with locked version]
+```
+
 ### Makefile Customization
 
 If your template includes a `Makefile`, it will be intelligently merged:

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/docs/remote-templates/index.md

@@ -37,9 +37,10 @@ uvx agent-starter-pack create test-agent -a https://github.com/you/your-template
 
 Remote templates work by:
 1. **Fetching** template repositories from Git
-2. **Applying** intelligent defaults based on repository structure  
-3. **Merging** template files with base agent infrastructure
-4. **Generating** complete, production-ready agent projects
+2. **Version locking** - automatically uses the exact starter pack version specified by the template for guaranteed compatibility
+3. **Applying** intelligent defaults based on repository structure  
+4. **Merging** template files with base agent infrastructure
+5. **Generating** complete, production-ready agent projects
 
 Any Git repository can become a template - the system handles the complexity automatically.
 

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/docs/remote-templates/using-remote-templates.md

@@ -7,9 +7,10 @@ Remote templates let you instantly create production-ready AI agents from Git re
 When you use a remote template, the system:
 
 1. **Fetches** the template repository from Git
-2. **Applies intelligent defaults** based on repository structure
-3. **Merges** template files with base agent infrastructure
-4. **Generates** a complete, production-ready agent project
+2. **Checks for version locking** - if the template specifies a starter pack version in `uv.lock`, automatically uses that version for guaranteed compatibility
+3. **Applies intelligent defaults** based on repository structure
+4. **Merges** template files with base agent infrastructure
+5. **Generates** a complete, production-ready agent project
 
 The file merging follows this priority order:
 1. Base template files (foundation)

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.14.1"
+version = "0.15.0"
 description = "CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates."
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },
@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "click>=8.1.7",
-    "cookiecutter~=2.6.0",
+    "cookiecutter>=2.6.0, <3.0.0",
     "google-cloud-aiplatform>=1.87.0",
     "rich>=13.7.0",
     "pyyaml>=6.0.1",

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/src/base_template/Makefile

@@ -76,7 +76,7 @@ backend:
 		--region "us-central1" \
 		--no-allow-unauthenticated \
 		--no-cpu-throttling \
-		--labels "created-by=adk{%- if cookiecutter.agent_garden %},deployed-with=agent-garden{%- endif %}" \
+		--labels "{% if "adk" in cookiecutter.tags %}created-by=adk{% if cookiecutter.agent_garden %},{% endif %}{% endif %}{% if cookiecutter.agent_garden %}deployed-with=agent-garden{% if cookiecutter.agent_sample_id %},vertex-agent-sample-id={{cookiecutter.agent_sample_id}},vertex-agent-sample-publisher={{cookiecutter.agent_sample_publisher}}{% endif %}{% endif %}" \
 		--set-env-vars \
 		"COMMIT_SHA=$(shell git rev-parse HEAD){%- if cookiecutter.data_ingestion %}{%- if cookiecutter.datastore_type == "vertex_ai_search" %},DATA_STORE_ID={{cookiecutter.project_name}}-datastore,DATA_STORE_REGION=us{%- elif cookiecutter.datastore_type == "vertex_ai_vector_search" %},VECTOR_SEARCH_INDEX={{cookiecutter.project_name}}-vector-search,VECTOR_SEARCH_INDEX_ENDPOINT={{cookiecutter.project_name}}-vector-search-endpoint,VECTOR_SEARCH_BUCKET=$$PROJECT_ID-{{cookiecutter.project_name}}-vs{%- endif %}{%- endif %}" \
 		$(if $(IAP),--iap) \

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/src/base_template/deployment/terraform/vars/env.tfvars

@@ -13,8 +13,11 @@ cicd_runner_project_id = "your-cicd-project-id"
 {%- if cookiecutter.cicd_runner == "google_cloud_build" %}
 # Name of the host connection you created in Cloud Build
 host_connection_name = "git-{{cookiecutter.project_name}}"
+github_pat_secret_id = "your-github_pat_secret_id"
 {%- endif %}
 
+repository_owner = "Your GitHub organization or username."
+
 # Name of the repository you added to Cloud Build
 repository_name = "{{cookiecutter.project_name}}"
 
@@ -34,7 +37,3 @@ vector_search_min_replica_count = 1
 vector_search_max_replica_count = 1
 {%- endif %}
 {%- endif %}
-{%- if cookiecutter.cicd_runner == "github_actions" %}
-
-repository_owner = "Your GitHub organization or username."
-{%- endif %}

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/src/base_template/pyproject.toml

@@ -14,14 +14,14 @@ dependencies = [
     "langchain-core~=0.3.9",
     "traceloop-sdk~=0.38.7",
 {%- endif %}
-    "google-cloud-logging~=3.11.4",
+    "google-cloud-logging>=3.12.0",
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
-    "google-cloud-aiplatform[evaluation]~=1.106.0",
+    "google-cloud-aiplatform[evaluation]~=1.113.0",
     "fastapi~=0.115.8",
     "uvicorn~=0.34.0",
     "psycopg2-binary>=2.9.10",
 {%- elif cookiecutter.deployment_target == 'agent_engine' %}
-    "google-cloud-aiplatform[evaluation,agent-engines]~=1.106.0"
+    "google-cloud-aiplatform[evaluation,agent-engines]~=1.113.0"
 {%- endif %}
 ]
 {% if cookiecutter.deployment_target == 'cloud_run' %}
@@ -72,7 +72,7 @@ select = [
     "UP", # pyupgrade
     "RUF", # ruff specific rules
 ]
-ignore = ["E501", "C901"] # ignore line too long, too complex
+ignore = ["E501", "C901", "B006"] # ignore line too long, too complex
 
 [tool.ruff.lint.isort]
 known-first-party = ["{{cookiecutter.agent_directory}}", "frontend"]

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/src/cli/commands/create.py

@@ -226,6 +226,20 @@ def normalize_project_name(project_name: str) -> str:
     help="Template files directly into the current directory instead of creating a new project directory",
     default=False,
 )
+@click.option(
+    "--skip-welcome",
+    is_flag=True,
+    hidden=True,
+    help="Skip the welcome banner",
+    default=False,
+)
+@click.option(
+    "--locked",
+    is_flag=True,
+    hidden=True,
+    help="Internal flag for version-locked remote templates",
+    default=False,
+)
 @shared_template_options
 @handle_cli_error
 def create(
@@ -247,6 +261,7 @@ def create(
     agent_garden: bool = False,
     base_template: str | None = None,
     skip_welcome: bool = False,
+    locked: bool = False,
     cli_overrides: dict | None = None,
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
@@ -337,8 +352,22 @@ def create(
                     ignore=get_standard_ignore_patterns(),
                 )
 
+                # Check for version lock and execute nested command if found
+                from ..utils.remote_template import check_and_execute_with_version_lock
+
+                if check_and_execute_with_version_lock(
+                    template_source_path, agent, locked
+                ):
+                    # If we executed with locked version, cleanup and exit
+                    shutil.rmtree(temp_dir, ignore_errors=True)
+                    return
+
                 selected_agent = f"local_{template_source_path.name}"
-                console.print(f"Using local template: {local_path}")
+                if locked:
+                    # In locked mode, show a nicer message
+                    console.print("✅ Using version-locked template", style="green")
+                else:
+                    console.print(f"Using local template: {local_path}")
                 logging.debug(
                     f"Copied local template to temporary dir: {template_source_path}"
                 )
@@ -354,7 +383,7 @@ def create(
                     else:
                         console.print(f"Fetching remote template: {agent}")
                     template_source_path, temp_dir_path = fetch_remote_template(
-                        remote_spec
+                        remote_spec, agent, locked
                     )
                     temp_dir_to_clean = str(temp_dir_path)
                     selected_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
@@ -416,7 +445,7 @@ def create(
                     else:
                         console.print(f"Fetching remote template: {agent}")
                     template_source_path, temp_dir_path = fetch_remote_template(
-                        remote_spec
+                        remote_spec, agent, locked
                     )
                     temp_dir_to_clean = str(temp_dir_path)
                     final_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
@@ -638,14 +667,7 @@ def create(
             except Exception as e:
                 if debug:
                     logging.warning(f"GCP environment setup failed: {e}")
-                console.print(
-                    f"> Warning: GCP environment setup failed: {e}", style="yellow"
-                )
-                console.print(
-                    "> Please check your authentication settings and permissions. "
-                    "> Visit https://cloud.google.com/vertex-ai/docs/authentication for help.",
-                    style="yellow",
-                )
+                console.print(f"> ⚠️  {e}", style="bold yellow")
                 console.print(
                     "> Continuing with template processing...", style="yellow"
                 )
@@ -690,6 +712,7 @@ def create(
                 in_folder=in_folder,
                 cli_overrides=final_cli_overrides,
                 agent_garden=agent_garden,
+                remote_spec=remote_spec,
             )
 
             # Replace region in all files if a different region was specified

{agent_starter_pack-0.14.1 → agent_starter_pack-0.15.0}/src/cli/utils/gcp.py

@@ -13,9 +13,13 @@
 # limitations under the License.
 
 # ruff: noqa: E722
+import os
 import subprocess
 import time
 
+# Suppress gRPC verbose logging
+os.environ["GRPC_VERBOSITY"] = "NONE"
+
 import google.auth
 from google.api_core.client_options import ClientOptions
 from google.api_core.exceptions import PermissionDenied
@@ -34,6 +38,12 @@ from src.cli.utils.version import PACKAGE_NAME, get_current_version
 
 console = Console()
 
+_AUTH_ERROR_MESSAGE = (
+    "Looks like you are not authenticated with Google Cloud.\n"
+    "Please run: `gcloud auth login --update-adc`\n"
+    "Then set your project: `gcloud config set project YOUR_PROJECT_ID`"
+)
+
 
 def enable_vertex_ai_api(
     project_id: str, auto_approve: bool = False, context: str | None = None
@@ -240,5 +250,14 @@ def verify_credentials() -> dict:
             account = "Unknown account"
 
         return {"project": project, "account": account}
+    except google.auth.exceptions.DefaultCredentialsError as e:
+        # Authentication error - provide friendly message
+        raise Exception(_AUTH_ERROR_MESSAGE) from e
     except Exception as e:
+        # Check if the error message indicates authentication issues
+        error_str = str(e).lower()
+        if any(
+            keyword in error_str for keyword in ["credential", "auth", "login", "token"]
+        ):
+            raise Exception(_AUTH_ERROR_MESSAGE) from e
         raise Exception(f"Failed to verify GCP credentials: {e!s}") from e