agent-starter-pack 0.14.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

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 packaging import version as pkg_version
 from rich.console import Console
 
 
@@ -127,15 +128,112 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
     return None
 
 
+def check_and_execute_with_version_lock(
+    template_dir: pathlib.Path,
+    original_agent_spec: str | None = None,
+    locked: bool = False,
+) -> bool:
+    """Check if remote template has agent-starter-pack version lock and execute if found.
+
+    Args:
+        template_dir: Path to the fetched template directory
+        original_agent_spec: The original agent spec (remote URL) to replace with local path
+        locked: Whether this is already a locked execution (prevents recursion)
+
+    Returns:
+        True if version lock was found and executed, False otherwise
+    """
+    # Skip version locking if we're already in a locked execution (prevents recursion)
+    if locked:
+        return False
+    uv_lock_path = template_dir / "uv.lock"
+    version = parse_agent_starter_pack_version_from_lock(uv_lock_path)
+
+    if version:
+        console = Console()
+        console.print(
+            f"🔒 Remote template requires agent-starter-pack version {version}",
+            style="bold blue",
+        )
+        console.print(
+            f"📦 Switching to version {version}...",
+            style="dim",
+        )
+
+        # Reconstruct the original command but with version constraint
+        import sys
+
+        original_args = sys.argv[1:]  # Skip 'agent-starter-pack' or script name
+
+        # Add version lock specific parameters and handle remote URL replacement
+        if original_agent_spec:
+            # Replace remote agent spec with local path
+            modified_args = []
+            for arg in original_args:
+                if arg == original_agent_spec:
+                    # Replace remote URL with local template directory
+                    modified_args.append(f"local@{template_dir}")
+                else:
+                    modified_args.append(arg)
+            original_args = modified_args
+
+        # Add version lock flags only for ASP versions 0.14.1 and above
+        if pkg_version.parse(version) > pkg_version.parse("0.14.1"):
+            original_args.extend(["--skip-welcome", "--locked"])
+
+        try:
+            # Check if uvx is available
+            subprocess.run(["uvx", "--version"], capture_output=True, check=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            console.print(
+                f"❌ Remote template requires agent-starter-pack version {version}, but 'uvx' is not installed",
+                style="bold red",
+            )
+            console.print(
+                "💡 Install uv to use version-locked remote templates:",
+                style="bold blue",
+            )
+            console.print("   curl -LsSf https://astral.sh/uv/install.sh | sh")
+            console.print(
+                "   OR visit: https://docs.astral.sh/uv/getting-started/installation/"
+            )
+            sys.exit(1)
+
+        try:
+            # Execute uvx with the locked version
+            cmd = ["uvx", f"agent-starter-pack=={version}", *original_args]
+            logging.debug(f"Executing nested command: {' '.join(cmd)}")
+            subprocess.run(cmd, check=True)
+            return True
+
+        except subprocess.CalledProcessError as e:
+            console.print(
+                f"❌ Failed to execute with locked version {version}: {e}",
+                style="bold red",
+            )
+            console.print(
+                "⚠️  Continuing with current version, but compatibility is not guaranteed",
+                style="yellow",
+            )
+            # Continue with current execution instead of failing completely
+
+    return False
+
+
 def fetch_remote_template(
     spec: RemoteTemplateSpec,
+    original_agent_spec: str | None = None,
+    locked: bool = False,
 ) -> tuple[pathlib.Path, pathlib.Path]:
     """Fetch remote template and return path to template directory.
 
-    Uses Git to clone the remote repository.
+    Uses Git to clone the remote repository. If the template contains a uv.lock
+    with agent-starter-pack version constraint, will execute nested uvx command.
 
     Args:
         spec: Remote template specification
+        original_agent_spec: Original agent spec string (used to prevent recursion)
+        locked: Whether this is already a locked execution (prevents recursion)
 
     Returns:
         A tuple containing:
@@ -188,6 +286,16 @@ def fetch_remote_template(
                 f"Template path not found in the repository: {spec.template_path}"
             )
 
+        # Check for version lock and execute nested command if found
+        if check_and_execute_with_version_lock(
+            template_dir, original_agent_spec, locked
+        ):
+            # If we executed with locked version, the nested process will handle everything
+            # Clean up and exit successfully
+            shutil.rmtree(temp_path, ignore_errors=True)
+            # Exit with success since the nested command will handle the rest
+            sys.exit(0)
+
         return template_dir, temp_path
     except Exception as e:
         # Clean up on error
@@ -458,6 +566,41 @@ def display_adk_caveat_if_needed(agents: dict[int, dict[str, Any]]) -> None:
         )
 
 
+def parse_agent_starter_pack_version_from_lock(
+    uv_lock_path: pathlib.Path,
+) -> str | None:
+    """Parse agent-starter-pack version from uv.lock file.
+
+    Args:
+        uv_lock_path: Path to uv.lock file
+
+    Returns:
+        Version string if found, None otherwise
+    """
+    if not uv_lock_path.exists():
+        return None
+
+    try:
+        with open(uv_lock_path, "rb") as f:
+            lock_data = tomllib.load(f)
+
+        # Look for agent-starter-pack in the packages section
+        packages = lock_data.get("package", [])
+        for package in packages:
+            if package.get("name") == "agent-starter-pack":
+                version = package.get("version")
+                if version:
+                    logging.debug(
+                        f"Found agent-starter-pack version {version} in uv.lock"
+                    )
+                    return version
+
+    except Exception as e:
+        logging.warning(f"Error parsing uv.lock file {uv_lock_path}: {e}")
+
+    return None
+
+
 def render_and_merge_makefiles(
     base_template_path: pathlib.Path,
     final_destination: pathlib.Path,

src/cli/utils/template.py

@@ -449,6 +449,7 @@ def process_template(
     in_folder: bool = False,
     cli_overrides: dict[str, Any] | None = None,
     agent_garden: bool = False,
+    remote_spec: Any | None = None,
 ) -> None:
     """Process the template directory and create a new project.
 
@@ -526,6 +527,15 @@ def process_template(
         try:
             os.chdir(temp_path)  # Change to temp directory
 
+            # Extract agent sample info for labeling when using agent garden with remote templates
+            agent_sample_id = None
+            agent_sample_publisher = None
+            if agent_garden and remote_spec and remote_spec.is_adk_samples:
+                # For ADK samples, template_path is like "python/agents/sample-name"
+                agent_sample_id = pathlib.Path(remote_spec.template_path).name
+                # For ADK samples, publisher is always "google"
+                agent_sample_publisher = "google"
+
             # Create the cookiecutter template structure
             cookiecutter_template = temp_path / "template"
             cookiecutter_template.mkdir(parents=True)
@@ -706,6 +716,8 @@ def process_template(
                 "datastore_type": datastore if datastore else "",
                 "agent_directory": get_agent_directory(template_config, cli_overrides),
                 "agent_garden": agent_garden,
+                "agent_sample_id": agent_sample_id or "",
+                "agent_sample_publisher": agent_sample_publisher or "",
                 "adk_cheatsheet": adk_cheatsheet_content,
                 "llm_txt": llm_txt_content,
                 "_copy_without_render": [

src/deployment_targets/agent_engine/tests/integration/test_agent_engine_app.py

@@ -38,14 +38,17 @@ def agent_app() -> AgentEngineApp:
     return app
 
 {% if "adk" in cookiecutter.tags %}
-def test_agent_stream_query(agent_app: AgentEngineApp) -> None:
+@pytest.mark.asyncio
+async def test_agent_stream_query(agent_app: AgentEngineApp) -> None:
     """
     Integration test for the agent stream query functionality.
     Tests that the agent returns valid streaming responses.
     """
-    # Create message and events for the stream_query
+    # Create message and events for the async_stream_query
     message = "What's the weather in San Francisco?"
-    events = list(agent_app.stream_query(message=message, user_id="test"))
+    events = []
+    async for event in agent_app.async_stream_query(message=message, user_id="test"):
+        events.append(event)
     assert len(events) > 0, "Expected at least one chunk in response"
 
     # Check for valid content in the response

src/deployment_targets/agent_engine/tests/load_test/load_test.py

@@ -36,7 +36,7 @@ engine_id = parts[5]
 
 # Convert remote agent engine ID to streaming URL.
 base_url = f"https://{location}-aiplatform.googleapis.com"
-url_path = f"/v1beta1/projects/{project_id}/locations/{location}/reasoningEngines/{engine_id}:streamQuery"
+url_path = f"/v1/projects/{project_id}/locations/{location}/reasoningEngines/{engine_id}:streamQuery"
 
 logger.info("Using remote agent engine ID: %s", remote_agent_engine_id)
 logger.info("Using base URL: %s", base_url)
@@ -56,10 +56,11 @@ class ChatStreamUser(HttpUser):
         headers["Authorization"] = f"Bearer {os.environ['_AUTH_TOKEN']}"
 {% if "adk" in cookiecutter.tags %}
         data = {
+            "class_method": "async_stream_query",
             "input": {
-                "message": "What's the weather in San Francisco?",
                 "user_id": "test",
-            }
+                "message": "What's the weather in San Francisco?",
+            },
         }
 {% else %}
         data = {
@@ -83,7 +84,11 @@ class ChatStreamUser(HttpUser):
             headers=headers,
             json=data,
             catch_response=True,
+{%- if "adk" in cookiecutter.tags %}
+            name="/streamQuery async_stream_query",
+{%- else %}
             name="/stream_messages first message",
+{%- endif %}
             stream=True,
             params={"alt": "sse"},
         ) as response:
@@ -107,7 +112,11 @@ class ChatStreamUser(HttpUser):
                 total_time = end_time - start_time
                 self.environment.events.request.fire(
                     request_type="POST",
+{%- if "adk" in cookiecutter.tags %}
+                    name="/streamQuery end",
+{%- else %}
                     name="/stream_messages end",
+{%- endif %}
                     response_time=total_time * 1000,  # Convert to milliseconds
                     response_length=len(events),
                     response=response,

src/deployment_targets/agent_engine/{{cookiecutter.agent_directory}}/agent_engine_app.py

@@ -14,7 +14,6 @@
 
 # mypy: disable-error-code="attr-defined,arg-type"
 {%- if "adk" in cookiecutter.tags %}
-import copy
 import datetime
 import json
 import logging
@@ -27,8 +26,8 @@ from google.adk.artifacts import GcsArtifactService
 from google.cloud import logging as google_cloud_logging
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider, export
-from vertexai import agent_engines
-from vertexai.preview.reasoning_engines import AdkApp
+from vertexai._genai.types import AgentEngine, AgentEngineConfig
+from vertexai.agent_engines.templates.adk import AdkApp
 
 from {{cookiecutter.agent_directory}}.agent import root_agent
 from {{cookiecutter.agent_directory}}.utils.gcs import create_bucket_if_not_exists
@@ -39,7 +38,10 @@ from {{cookiecutter.agent_directory}}.utils.typing import Feedback
 class AgentEngineApp(AdkApp):
     def set_up(self) -> None:
         """Set up logging and tracing for the agent engine app."""
+        import logging
+
         super().set_up()
+        logging.basicConfig(level=logging.INFO)
         logging_client = google_cloud_logging.Client()
         self.logger = logging_client.logger(__name__)
         provider = TracerProvider()
@@ -62,22 +64,9 @@ class AgentEngineApp(AdkApp):
         Extends the base operations to include feedback registration functionality.
         """
         operations = super().register_operations()
-        operations[""] = operations[""] + ["register_feedback"]
+        operations[""] = operations.get("", []) + ["register_feedback"]
         return operations
 
-    def clone(self) -> "AgentEngineApp":
-        """Returns a clone of the ADK application."""
-        template_attributes = self._tmpl_attrs
-
-        return self.__class__(
-            agent=copy.deepcopy(template_attributes["agent"]),
-            enable_tracing=bool(template_attributes.get("enable_tracing", False)),
-            session_service_builder=template_attributes.get("session_service_builder"),
-            artifact_service_builder=template_attributes.get(
-                "artifact_service_builder"
-            ),
-            env_vars=template_attributes.get("env_vars"),
-        )
 {%- else %}
 import datetime
 import json
@@ -93,7 +82,7 @@ import vertexai
 from google.cloud import logging as google_cloud_logging
 from langchain_core.runnables import RunnableConfig
 from traceloop.sdk import Instruments, Traceloop
-from vertexai import agent_engines
+from vertexai._genai.types import AgentEngine, AgentEngineConfig
 
 from {{cookiecutter.agent_directory}}.utils.gcs import create_bucket_if_not_exists
 from {{cookiecutter.agent_directory}}.utils.tracing import CloudTraceLoggingSpanExporter
@@ -209,9 +198,9 @@ def deploy_agent_engine_app(
     extra_packages: list[str] = ["./{{cookiecutter.agent_directory}}"],
     env_vars: dict[str, str] = {},
     service_account: str | None = None,
-) -> agent_engines.AgentEngine:
+) -> AgentEngine:
     """Deploy the agent engine app to Vertex AI."""
-
+    logging.basicConfig(level=logging.INFO)
     staging_bucket_uri = f"gs://{project}-agent-engine"
 {%- if "adk" in cookiecutter.tags %}
     artifacts_bucket_name = f"{project}-{{cookiecutter.project_name}}-logs-data"
@@ -223,7 +212,12 @@ def deploy_agent_engine_app(
         bucket_name=staging_bucket_uri, project=project, location=location
     )
 
-    vertexai.init(project=project, location=location, staging_bucket=staging_bucket_uri)
+    # Initialize vertexai client
+    client = vertexai.Client(
+        project=project,
+        location=location,
+    )
+    vertexai.init(project=project, location=location)
 
     # Read requirements
     with open(requirements_file) as f:
@@ -242,38 +236,51 @@ def deploy_agent_engine_app(
     env_vars["NUM_WORKERS"] = "1"
 
     # Common configuration for both create and update operations
+    config = AgentEngineConfig(
+        display_name=agent_name,
+        description="{{cookiecutter.agent_description}}",
+        extra_packages=extra_packages,
+        env_vars=env_vars,
+        service_account=service_account,
+        requirements=requirements,
+        staging_bucket=staging_bucket_uri,
+    )
+
     agent_config = {
-        "agent_engine": agent_engine,
-        "display_name": agent_name,
-        "description": "{{cookiecutter.agent_description}}",
-        "extra_packages": extra_packages,
-        "env_vars": env_vars,
-        "service_account": service_account,
+        "agent": agent_engine,
+        "config": config,
     }
     logging.info(f"Agent config: {agent_config}")
-    agent_config["requirements"] = requirements
 
     # Check if an agent with this name already exists
-    existing_agents = list(agent_engines.list(filter=f"display_name={agent_name}"))
-    if existing_agents:
+    existing_agents = list(client.agent_engines.list())
+    matching_agents = [
+        agent
+        for agent in existing_agents
+        if agent.api_resource.display_name == agent_name
+    ]
+
+    if matching_agents:
         # Update the existing agent with new configuration
         logging.info(f"Updating existing agent: {agent_name}")
-        remote_agent = existing_agents[0].update(**agent_config)
+        remote_agent = client.agent_engines.update(
+            name=matching_agents[0].api_resource.name, **agent_config
+        )
     else:
         # Create a new agent if none exists
         logging.info(f"Creating new agent: {agent_name}")
-        remote_agent = agent_engines.create(**agent_config)
+        remote_agent = client.agent_engines.create(**agent_config)
 
-    config = {
-        "remote_agent_engine_id": remote_agent.resource_name,
+    metadata = {
+        "remote_agent_engine_id": remote_agent.api_resource.name,
         "deployment_timestamp": datetime.datetime.now().isoformat(),
     }
-    config_file = "deployment_metadata.json"
+    metadata_file = "deployment_metadata.json"
 
-    with open(config_file, "w") as f:
-        json.dump(config, f, indent=2)
+    with open(metadata_file, "w") as f:
+        json.dump(metadata, f, indent=2)
 
-    logging.info(f"Agent Engine ID written to {config_file}")
+    logging.info(f"Agent Engine ID written to {metadata_file}")
 
     return remote_agent
 

src/deployment_targets/cloud_run/deployment/terraform/dev/service.tf

@@ -133,6 +133,18 @@ resource "google_cloud_run_v2_service" "app" {
   project             = var.dev_project_id
   deletion_protection = false
   ingress             = "INGRESS_TRAFFIC_ALL"
+  labels = {
+{%- if "adk" in cookiecutter.tags %}
+    "created-by"                  = "adk"
+{%- 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 %}
+  }
 
   template {
     containers {

src/deployment_targets/cloud_run/deployment/terraform/service.tf

@@ -154,6 +154,18 @@ resource "google_cloud_run_v2_service" "app_staging" {
   project             = var.staging_project_id
   deletion_protection = false
   ingress             = "INGRESS_TRAFFIC_ALL"
+  labels = {
+{%- if "adk" in cookiecutter.tags %}
+    "created-by"                  = "adk"
+{%- 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 %}
+  }
 
   template {
     containers {
@@ -260,6 +272,18 @@ resource "google_cloud_run_v2_service" "app_prod" {
   project             = var.prod_project_id
   deletion_protection = false
   ingress             = "INGRESS_TRAFFIC_ALL"
+  labels = {
+{%- if "adk" in cookiecutter.tags %}
+    "created-by"                  = "adk"
+{%- 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 %}
+  }
 
   template {
     containers {