Add base template override support for remote templates (#453)

* feat: add base template override support for remote templates

Enable users to override the base template specified in remote templates
using the --base-template flag. This allows using different foundational
agents while preserving remote template logic and customizations.

Key changes:
- Add --base-template CLI flag to create command
- Implement interactive dependency management via uv add
- Validate base template exists before processing
- Auto-prompt for required dependencies with skip option
- Support --auto-approve for non-interactive workflows
- Add comprehensive test coverage
- Update documentation with usage examples

When overriding a base template, users are prompted to install any
additional dependencies required by the new base. Dependencies are
added using uv add with proper version resolution.

* feat: add --base-template flag with interactive dependency management

  Allows overriding base template for remote templates. CLI prompts users
  to install required dependencies via uv add, with support for auto-approve
  mode. Includes validation, error handling, tests, and documentation.

Author: eliasecchig

agent_starter_pack/cli/commands/create.py

@@ -37,6 +37,7 @@
     parse_agent_spec,
 )
 from ..utils.template import (
+    add_base_template_dependencies_interactively,
     get_available_agents,
     get_deployment_targets,
     get_template_path,
@@ -112,6 +113,11 @@ def shared_template_options(f: Callable) -> Callable:
         "-dir",
         help="Name of the agent directory (overrides template default)",
     )(f)
+    f = click.option(
+        "--base-template",
+        "-bt",
+        help="Base template to use (overrides template default, only for remote templates)",
+    )(f)
     return f
 
 
@@ -474,6 +480,18 @@ def create(
             if cli_overrides is None:
                 cli_overrides = {}
             if base_template:
+                # Validate that the base template exists
+                if not validate_base_template(base_template):
+                    available_templates = get_available_base_templates()
+                    console.print(
+                        f"Error: Base template '{base_template}' not found.",
+                        style="bold red",
+                    )
+                    console.print(
+                        f"Available base templates: {', '.join(available_templates)}",
+                        style="yellow",
+                    )
+                    raise click.Abort()
                 cli_overrides["base_template"] = base_template
 
             # Load remote template config
@@ -727,6 +745,24 @@ def create(
             # Replace region in all files if a different region was specified
             if region != "us-central1":
                 replace_region_in_files(project_path, region, debug=debug)
+
+            # Handle base template dependencies if override was used
+            if base_template and template_source_path and remote_config:
+                # Load base template config to get extra_dependencies
+                base_template_path = get_template_path(base_template, debug=debug)
+                base_config = load_template_config(base_template_path)
+                base_deps = base_config.get("settings", {}).get(
+                    "extra_dependencies", []
+                )
+
+                if base_deps:
+                    # Call interactive dependency addition
+                    add_base_template_dependencies_interactively(
+                        project_path,
+                        base_deps,
+                        base_template,
+                        auto_approve=auto_approve,
+                    )
         finally:
             # Clean up the temporary directory if one was created
             if temp_dir_to_clean:

agent_starter_pack/cli/utils/template.py

@@ -17,6 +17,7 @@
 import os
 import pathlib
 import shutil
+import subprocess
 import sys
 import tempfile
 from dataclasses import dataclass
@@ -25,7 +26,7 @@
 import yaml
 from cookiecutter.main import cookiecutter
 from rich.console import Console
-from rich.prompt import IntPrompt, Prompt
+from rich.prompt import Confirm, IntPrompt, Prompt
 
 from agent_starter_pack.cli.utils.version import get_current_version
 
@@ -36,6 +37,105 @@
 )
 
 
+def add_base_template_dependencies_interactively(
+    project_path: pathlib.Path,
+    base_dependencies: list[str],
+    base_template_name: str,
+    auto_approve: bool = False,
+) -> bool:
+    """Interactively add base template dependencies using uv add.
+
+    Args:
+        project_path: Path to the project directory
+        base_dependencies: List of dependencies from base template's extra_dependencies
+        base_template_name: Name of the base template being used
+        auto_approve: Whether to skip confirmation and auto-install
+
+    Returns:
+        True if dependencies were added successfully, False otherwise
+    """
+    if not base_dependencies:
+        return True
+
+    console = Console()
+
+    # Construct dependency string once for reuse
+    deps_str = " ".join(f"'{dep}'" for dep in base_dependencies)
+
+    # Show what dependencies will be added
+    console.print(
+        f"\n✓ Base template override: Using '{base_template_name}' as foundation",
+        style="bold cyan",
+    )
+    console.print("  This requires adding the following dependencies:", style="white")
+    for dep in base_dependencies:
+        console.print(f"    • {dep}", style="yellow")
+
+    # Ask for confirmation unless auto-approve
+    should_add = True
+    if not auto_approve:
+        should_add = Confirm.ask(
+            "\n? Add these dependencies automatically?", default=True
+        )
+
+    if not should_add:
+        console.print("\n⚠️  Skipped dependency installation.", style="yellow")
+        console.print("   To add them manually later, run:", style="dim")
+        console.print(f"       cd {project_path.name}", style="dim")
+        console.print(f"       uv add {deps_str}\n", style="dim")
+        return False
+
+    # Run uv add
+    try:
+        if auto_approve:
+            console.print(
+                f"✓ Auto-installing dependencies: {', '.join(base_dependencies)}",
+                style="bold cyan",
+            )
+        else:
+            console.print(f"\n✓ Running: uv add {deps_str}", style="bold cyan")
+
+        # Run uv add in the project directory
+        cmd = ["uv", "add"] + base_dependencies
+        result = subprocess.run(
+            cmd,
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        # Show success message
+        if not auto_approve:
+            # Show a summary line from uv output
+            output_lines = result.stderr.strip().split("\n")
+            for line in output_lines:
+                if "Resolved" in line or "Installed" in line:
+                    console.print(f"  {line}", style="dim")
+                    break
+
+        console.print("✓ Dependencies added successfully\n", style="bold green")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        console.print(
+            f"\n✗ Failed to add dependencies: {e.stderr.strip()}", style="bold red"
+        )
+        console.print("  You can add them manually:", style="yellow")
+        console.print(f"      cd {project_path.name}", style="dim")
+        console.print(f"      uv add {deps_str}\n", style="dim")
+        return False
+    except FileNotFoundError:
+        console.print(
+            "\n✗ uv command not found. Please install uv first.", style="bold red"
+        )
+        console.print("  Install from: https://docs.astral.sh/uv/", style="dim")
+        console.print("\n  To add dependencies manually:", style="yellow")
+        console.print(f"      cd {project_path.name}", style="dim")
+        console.print(f"      uv add {deps_str}\n", style="dim")
+        return False
+
+
 def validate_agent_directory_name(agent_dir: str) -> None:
     """Validate that an agent directory name is a valid Python identifier.
 

docs/cli/create.md

@@ -81,6 +81,30 @@ Output directory for the project (default: current directory)
 ### `--agent-directory`, `-dir` DIRECTORY
 Name of the agent directory (overrides template default, usually `app`). This determines where your agent code files will be located within the project structure.
 
+### `--base-template`, `-bt` TEMPLATE
+Override the base template specified in a remote template's configuration. Only applicable when using remote templates with the `--agent` flag. This allows you to use a different built-in agent as the foundation instead of the one specified in the remote template's `pyproject.toml`.
+
+**Interactive dependency management:**
+When overriding the base template, you'll be prompted to add required dependencies using `uv add`:
+
+```bash
+# Use adk_a2a_base as base instead of the remote template's default
+uvx agent-starter-pack create my-agent -a github.com/user/template --base-template adk_a2a_base
+
+✓ Base template override: Using 'adk_a2a_base' as foundation
+  This requires adding the following dependencies:
+    • google-adk>=1.16.0,<2.0.0
+    • a2a-sdk~=0.3.9
+
+? Add these dependencies automatically? [Y/n]
+```
+
+With `--auto-approve`, dependencies are added automatically without prompting:
+```bash
+uvx agent-starter-pack create my-agent -a template --base-template adk_a2a_base --auto-approve
+# Dependencies are added automatically
+```
+
 ### `--in-folder`
 Create agent files directly in the current directory instead of creating a new project subdirectory.
 
@@ -138,8 +162,11 @@ uvx agent-starter-pack create my-agent -a https://github.com/user/my-template
 # Use shorthand notation with branch
 uvx agent-starter-pack create my-agent -a github.com/user/template@develop
 
-# Use your existing project  
+# Use your existing project
 uvx agent-starter-pack create my-agent -a local@./my-project
+
+# Override the base template of a remote template
+uvx agent-starter-pack create my-agent -a adk@data-science --base-template adk_live
 ```
 
 ### Advanced Configuration

docs/remote-templates/creating-remote-templates.md

@@ -146,6 +146,7 @@ description = "An awesome AI agent template"
 dependencies = ["google-adk>=1.8.0", "custom-lib"]
 
 [tool.agent-starter-pack]
+# Base template to inherit from - users can override with --base-template flag
 base_template = "adk_base"
 name = "My Awesome Template"  # Optional: falls back to [project].name
 description = "Custom description"  # Optional: falls back to [project].description
@@ -157,6 +158,8 @@ frontend_type = "adk_streamlit"
 agent_directory = "app"
 ```
 
+**Note:** Users can override the `base_template` when creating from your template using `--base-template`. When they do, the CLI will automatically prompt them to add any additional dependencies required by the new base template using `uv add`.
+
 ## Configuration Reference
 
 ### Configuration Fallback Behavior

docs/remote-templates/using-remote-templates.md

@@ -116,10 +116,69 @@ uvx agent-starter-pack create my-agent -a template-url --include-data-ingestion
 # Custom session storage
 uvx agent-starter-pack create my-agent -a template-url --session-type alloydb
 
+# Override the base template
+uvx agent-starter-pack create my-agent -a template-url --base-template adk_live
+
 # Skip verification checks
 uvx agent-starter-pack create my-agent -a template-url --skip-checks
 ```
 
+### Overriding Base Templates
+
+Remote templates can specify a base template in their `pyproject.toml` configuration. You can override this using the `--base-template` flag to use a different foundational agent:
+
+```bash
+# Use adk_a2a_base as the base instead of what the template specifies
+uvx agent-starter-pack create my-agent -a adk@data-science --base-template adk_a2a_base
+
+✓ Base template override: Using 'adk_a2a_base' as foundation
+  This requires adding the following dependencies:
+    • google-adk>=1.16.0,<2.0.0
+    • a2a-sdk~=0.3.9
+
+? Add these dependencies automatically? [Y/n] y
+
+✓ Running: uv add 'google-adk>=1.16.0,<2.0.0' 'a2a-sdk~=0.3.9'
+  Resolved 111 packages in 1.2s
+✓ Dependencies added successfully
+```
+
+#### Interactive Dependency Management
+
+When you override the base template, the CLI:
+1. **Shows required dependencies** - Lists all dependencies needed by the new base template
+2. **Prompts for confirmation** - Asks if you want to add them automatically
+3. **Runs `uv add`** - Uses standard `uv` commands to add dependencies with proper version resolution
+4. **Handles conflicts** - `uv` automatically resolves any version conflicts between remote template and base dependencies
+
+**Skipping dependency installation:**
+```bash
+? Add these dependencies automatically? [Y/n] n
+
+⚠️  Skipped dependency installation.
+   To add them manually later, run:
+       cd my-agent
+       uv add 'google-adk>=1.16.0,<2.0.0' 'a2a-sdk~=0.3.9'
+```
+
+**Automatic installation with `--auto-approve`:**
+```bash
+uvx agent-starter-pack create my-agent -a template --base-template adk_a2a_base --auto-approve
+
+✓ Base template override: Using 'adk_a2a_base' as foundation
+✓ Auto-installing dependencies: google-adk>=1.16.0,<2.0.0, a2a-sdk~=0.3.9
+  Resolved 111 packages in 1.2s
+✓ Dependencies added successfully
+```
+
+#### Use Cases
+
+Base template override is useful when:
+- You want to use a remote template's logic with a different foundational agent
+- The template's default base doesn't match your deployment needs (e.g., switching from Cloud Run to Agent Engine)
+- You're experimenting with different base agents for the same custom logic
+- You need features from a different base (e.g., A2A protocol support via `adk_a2a_base`)
+
 ## Discovering Templates
 
 ### List Available Templates