agent-starter-pack 0.7.1__tar.gz → 0.9.0__tar.gz

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

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(uv run:*)",
+      "Bash(git add:*)"
+    ],
+    "deny": []
+  }
+}

agent_starter_pack-0.9.0/.cloudbuild/ci/test_remote_template.yaml

@@ -0,0 +1,36 @@
+# 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.
+
+steps:
+  # Sync dependencies
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv sync --locked
+
+  # Run unit tests using pytest
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: test-templated-agents
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/integration/test_remote_templating.py
+
+logsBucket: gs://${PROJECT_ID}-logs-data/build-logs
+options:
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/.cloudbuild/terraform/build_triggers.tf

@@ -85,16 +85,12 @@ locals {
       value = "live_api,cloud_run"
     },
     {
-      name  = "adk_gemini_fullstack-agent_engine"
-      value = "adk_gemini_fullstack,agent_engine"
-    },
-    {
-      name  = "adk_gemini_fullstack-cloud_run"
-      value = "adk_gemini_fullstack,cloud_run"
+      name  = "adk_base-cloud_run-alloydb"
+      value = "adk_base,cloud_run,--session-type,alloydb"
     },
   ]
 
-  agent_testing_included_files = { for combo in local.agent_testing_combinations :
+agent_testing_included_files = { for combo in local.agent_testing_combinations :
     combo.name => [
       # Only include files for the specific agent being tested
       "agents/${split(",", combo.value)[0]}/**",
@@ -135,8 +131,8 @@ locals {
       value = "live_api,cloud_run"
     },
     {
-      name  = "adk_gemini_fullstack-agent_engine"
-      value = "adk_gemini_fullstack,agent_engine"
+      name  = "adk_base-cloud_run-alloydb"
+      value = "adk_base,cloud_run,--session-type,alloydb"
     },
   ]
   # Create a safe trigger name by replacing underscores with hyphens and dots with hyphens
@@ -146,7 +142,17 @@ locals {
     }
 
   e2e_agent_deployment_included_files = { for combo in local.agent_testing_combinations :
-    combo.name => [
+    combo.name => combo.name == "adk_base-cloud_run-alloydb" ? [
+      "src/deployment_targets/cloud_run/**",
+      "pyproject.toml",
+    ] : substr(combo.name, 0, 11) == "agentic_rag" ? [
+      "agents/agentic_rag/**",
+      "src/data_ingestion/**",
+      "pyproject.toml",
+    ] : substr(combo.name, 0, 8) == "live_api" ? [
+      "agents/live_api/**",
+      "pyproject.toml",
+    ] : [
       # Only include files for the specific agent being tested
       "agents/${split(",", combo.value)[0]}/**",
       # Common files that affect all agents
@@ -313,3 +319,25 @@ resource "google_cloudbuild_trigger" "main_e2e_deployment_test" {
     _E2E_PROD_PROJECT    = var.e2e_test_project_mapping.prod
   }
 }
+
+# f. Create Remote Template Test trigger for PR requests
+resource "google_cloudbuild_trigger" "pr_test_remote_template" {
+  name            = "pr-test-remote-template"
+  project         = var.cicd_runner_project_id
+  location        = var.region
+  description     = "Trigger for PR checks on remote templating"
+  service_account = resource.google_service_account.cicd_runner_sa.id
+
+  repository_event_config {
+    repository = local.repository_path
+    pull_request {
+      branch          = "main"
+      comment_control = "COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY"
+    }
+  }
+
+  filename           = ".cloudbuild/ci/test_remote_template.yaml"
+  included_files     = local.common_included_files
+  ignored_files      = local.common_ignored_files
+  include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
+}

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/.gitignore

@@ -188,6 +188,7 @@ testem.log
 Thumbs.db
 *.vscode*
 
+.locust_env/
 .saved_chats
 .aider*
 target
@@ -196,4 +197,5 @@ delete_genai_repos.sh
 cleanup_e2e_projects.sh
 .cloudbuild/terraform/backend.tf
 .cloudbuild/terraform/vars/env.tfvars
-docs/.vitepress/cache
+docs/.vitepress/cache
+tests/cicd/delete_gcp_resources.sh

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.7.1
+Version: 0.9.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
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: backoff>=2.2.1
-Requires-Dist: click~=8.1.7
-Requires-Dist: cookiecutter~=2.5.0
+Requires-Dist: click>=8.1.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: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
 Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.29.5; extra == 'jupyter'
 Requires-Dist: jupyter; extra == 'jupyter'
@@ -103,7 +103,8 @@ Looking to explore more ADK examples? Check out the [ADK Samples Repository](htt
 The `agent-starter-pack` offers two key features to accelerate and simplify the development of your agent:
 - **🔄 [CI/CD Automation (Experimental)](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - One command to set up a complete GitHub + Cloud Build pipeline for all environments
 - **📥 [Data Pipeline for RAG with Terraform/CI-CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/data-ingestion)** - Seamlessly integrate a data pipeline to process embeddings for RAG into your agent system. Supporting [Vertex AI Search](https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction) and [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview).
-* **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.
+- **[Remote Templates](docs/guide/remote-templating.md)**: Create and share your own agent starter packs templates from any Git repository.
+- **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.
 
 ## High-Level Architecture
 

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/README.md

@@ -78,7 +78,8 @@ Looking to explore more ADK examples? Check out the [ADK Samples Repository](htt
 The `agent-starter-pack` offers two key features to accelerate and simplify the development of your agent:
 - **🔄 [CI/CD Automation (Experimental)](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - One command to set up a complete GitHub + Cloud Build pipeline for all environments
 - **📥 [Data Pipeline for RAG with Terraform/CI-CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/data-ingestion)** - Seamlessly integrate a data pipeline to process embeddings for RAG into your agent system. Supporting [Vertex AI Search](https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction) and [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview).
-* **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.
+- **[Remote Templates](docs/guide/remote-templating.md)**: Create and share your own agent starter packs templates from any Git repository.
+- **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.
 
 ## High-Level Architecture
 

agent_starter_pack-0.9.0/agents/README.md

@@ -0,0 +1,7 @@
+# Agent Templates
+
+This directory contains template implementations for various agents designed to work with the Agent Starter Pack templating system.
+Feel free to browse through these folders to preview what each template offers.
+Direct cloning of this repository isn't necessary to utilize these templates.
+
+For setup instructions and getting started, please refer to the main [README](/README.md) which explains how to install and use the Agent Starter Pack.

agent_starter_pack-0.7.1/agents/adk_base/template/.templateconfig.yaml → agent_starter_pack-0.9.0/agents/adk_base/.template/templateconfig.yaml

@@ -16,7 +16,9 @@ description: "A base ReAct agent built with Google's Agent Development Kit (ADK)
 example_question: "What's the weather in San Francisco?"
 settings:
   requires_data_ingestion: false
+  requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
-  extra_dependencies: ["google-adk~=1.4.2"]
+  extra_dependencies: ["google-adk~=1.6.0"]
   tags: ["adk"]
   frontend_type: "None"
+    

{agent_starter_pack-0.7.1/agents/adk_gemini_fullstack → agent_starter_pack-0.9.0/agents/adk_base}/notebooks/adk_app_testing.ipynb

@@ -207,14 +207,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\", \"Authorization\": f\"Bearer {ID_TOKEN}\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {
@@ -279,14 +280,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {

agent_starter_pack-0.7.1/agents/adk_gemini_fullstack/template/.templateconfig.yaml → agent_starter_pack-0.9.0/agents/adk_gemini_fullstack/.template/templateconfig.yaml

@@ -16,13 +16,14 @@ description: "A production-ready fullstack research agent that uses Gemini to st
 example_question: "A report on the latest Google I/O event"
 settings:
   requires_data_ingestion: false
+  requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
-  extra_dependencies: ["google-adk~=1.4.2"]
+  extra_dependencies: ["google-adk~=1.6.0"]
   tags: ["adk"]
   frontend_type: "adk_gemini_fullstack"
   commands:
     override:
-      install: "npm --prefix frontend install"
+      install: "uv sync --dev --extra jupyter && npm --prefix frontend install"
     extra:
       dev: 
         command: 'make dev-backend & make dev-frontend'

{agent_starter_pack-0.7.1/agents/agentic_rag → agent_starter_pack-0.9.0/agents/adk_gemini_fullstack}/notebooks/adk_app_testing.ipynb

@@ -207,14 +207,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\", \"Authorization\": f\"Bearer {ID_TOKEN}\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {
@@ -279,14 +280,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {

agent_starter_pack-0.7.1/agents/agentic_rag/template/.templateconfig.yaml → agent_starter_pack-0.9.0/agents/agentic_rag/.template/templateconfig.yaml

@@ -16,9 +16,10 @@ description: "ADK RAG agent for document retrieval and Q&A. Includes a data pipe
 example_question: "How to save a pandas dataframe to CSV?"
 settings:
   requires_data_ingestion: true
+  requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
   extra_dependencies: [
-    "google-adk~=1.4.2",
+    "google-adk~=1.6.0",
     "langchain-google-vertexai~=2.0.7",
     "langchain~=0.3.24",
     "langchain-core~=0.3.55",

{agent_starter_pack-0.7.1/agents/adk_base → agent_starter_pack-0.9.0/agents/agentic_rag}/notebooks/adk_app_testing.ipynb

@@ -207,14 +207,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\", \"Authorization\": f\"Bearer {ID_TOKEN}\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {
@@ -279,14 +280,15 @@
    "outputs": [],
    "source": [
     "user_id = \"test_user_123\"\n",
-    "session_id = \"test_session_456\"\n",
     "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
     "\n",
-    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions/{session_id}\"\n",
+    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions\"\n",
     "headers = {\"Content-Type\": \"application/json\"}\n",
     "\n",
     "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
-    "print(f\"Session creation status code: {session_response.status_code}\")"
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
    ]
   },
   {

agent_starter_pack-0.7.1/agents/crewai_coding_crew/template/.templateconfig.yaml → agent_starter_pack-0.9.0/agents/crewai_coding_crew/.template/templateconfig.yaml

@@ -22,6 +22,6 @@ settings:
     "langchain-community~=0.3.17", 
     "langchain-openai~=0.3.5",
     "langgraph~=0.4.8",
-    "crewai~=0.119.0"
+    "crewai~=0.140.0"
   ]
 example_question: "How can I implement a function to sort a list in Python?"

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/docs/.vitepress/config.js

@@ -43,6 +43,13 @@ export default defineConfig({
           { text: 'Troubleshooting', link: '/guide/troubleshooting' }
         ]
       },
+      {
+        text: 'Authoring Templates',
+        items: [
+          { text: 'Remote Templating', link: '/guide/remote-templating' },
+          { text: 'Template Config Reference', link: '/guide/template-config-reference' }
+        ]
+      },
       {
         text: 'Agents',
         items: [

{agent_starter_pack-0.7.1 → agent_starter_pack-0.9.0}/docs/cli/create.md

@@ -22,6 +22,7 @@ The following options will be prompted interactively if not provided via the com
 - `--deployment-target`, `-d`: Deployment target (`agent_engine` or `cloud_run`). Prompts if omitted.
 - `--datastore`, `-ds`: Datastore for RAG agents (`vertex_ai_search` or `vertex_ai_vector_search`). Prompted if `--include-data-ingestion` is specified, or if the selected agent (e.g., `agentic_rag`) requires data ingestion, and this option is omitted.
 - `--region`: GCP region for deployment (default: `us-central1`). Prompts for confirmation if not specified and `--auto-approve` is not used.
+- `--session-type`: Type of session storage to use (`in_memory` or `alloydb`). This is only applicable for agents that require session management and when the deployment target is `cloud_run`.
 
 GCP account and project ID are detected automatically (using your active `gcloud config` settings). You will be prompted to confirm or change them unless `--auto-approve` is used.
 

agent_starter_pack-0.9.0/docs/guide/remote-templating.md

@@ -0,0 +1,211 @@
+# Remote Templates
+
+With remote templating, you can create and share your own agent starter packs without needing to fork the main repository. A remote template is a Git repository that the `agent-starter-pack` CLI can use as a blueprint to create new agent projects. This allows for easy sharing and reuse of customized agent setups.
+
+This guide covers how to build, test, and use remote templates.
+
+## Quickstart: Creating Your First Remote Template
+
+Let's build a simple remote template that customizes the built-in `adk_base` agent.
+
+### Step 1: Create the Template Directory Structure
+
+A remote template is structured just like a standard agent project. The only special part is the `.template/` directory, which holds the configuration.
+
+Create the following structure on your local machine:
+
+```
+my-first-remote-template/
+├── .template/
+│   └── templateconfig.yaml  # Configuration file
+├── app/
+│   └── agent.py             # Your custom agent logic
+└── pyproject.toml           # Your custom dependencies
+```
+
+### Step 2: Configure the Template
+
+The `templateconfig.yaml` file is required. It tells the starter pack how to use your template.
+
+Put the following content in `.template/templateconfig.yaml`:
+
+```yaml
+# (Required) The built-in agent to use as a foundation.
+base_template: "adk_base"
+
+# (Required) Your template's name and description.
+name: "My First Remote Template"
+description: "A simple template that says hello."
+
+# (Optional) Override settings from the base template.
+settings:
+  # This template will only support the 'agent_engine' deployment target.
+  deployment_targets: ["agent_engine"]
+```
+
+### Step 3: Customize Dependencies and Agent Logic
+
+First, define any custom dependencies in `pyproject.toml`. For this example, we'll just use the base dependencies but you could add your own here.
+
+Put the following in `pyproject.toml`:
+```toml
+[project]
+name = "my-first-remote-template"
+version = "0.1.0"
+dependencies = [
+    "google-adk",
+]
+```
+
+Next, we'll override the default `agent.py` to create a simple "hello world" agent.
+
+Put the following code in `app/agent.py`:
+
+```python
+from google.adk.agents import Agent
+
+def get_greeting(name: str = "World") -> str:
+    """Returns a friendly greeting from the remote template."""
+    return f"Hello, {name}! This greeting comes from a remote template."
+
+root_agent = Agent(
+    name="root_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful AI assistant. Use your tools to answer questions.",
+    tools=[get_greeting],
+)
+```
+
+### Step 4: Test Your Template Locally
+
+Before publishing to Git, you can test your template from your local filesystem using the `local@` prefix.
+
+Run the `create` command from the directory *outside* of your template folder:
+
+```bash
+# Make sure you are in the parent directory of 'my-first-remote-template'
+uvx agent-starter-pack create my-test-agent -a local@./my-first-remote-template
+```
+
+This creates a new project `my-test-agent` using your local template.
+
+### Step 5: Publish and Use Your Template
+
+Once you are satisfied, initialize a Git repository, commit your files, and push them to a provider like GitHub. Now, you or anyone else can use your template directly from its Git URL:
+
+```bash
+# Replace with your repository URL
+REPO_URL="https://github.com/your-username/my-first-remote-template"
+
+uvx agent-starter-pack create my-remote-agent -a $REPO_URL
+```
+
+## Template Structure
+
+A remote template repository mirrors the structure of a standard agent. The templating engine copies the entire contents of your repository and overlays them onto the base agent.
+
+-   **Your Agent Files (`app/`, `tests/`, etc.)**: These should be at the root of your repository. They will overwrite the corresponding files from the `base_template`.
+-   **`.template/` directory**: This special directory is **only** for the `templateconfig.yaml` file. It is read by the CLI for configuration but is not copied into the final project.
+-   **Dependencies (`pyproject.toml`, `uv.lock`)**: These must be at the root of your repository.
+
+**Example Structure:**
+```
+my-awesome-template/
+├── .template/
+│   └── templateconfig.yaml      # (Required) Configuration only.
+├── pyproject.toml           # (Required) Custom Python dependencies.
+├── uv.lock                  # (Recommended) Locked Python dependencies.
+├── app/
+│   └── agent.py             # Your custom agent logic.
+└── README.md                # Your repository's README.
+```
+
+## How File Merging Works
+
+Files are copied and overlaid in the following order, with later steps overwriting earlier ones if files have the same name and path:
+
+1.  **[Base Project Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/base_template)**: The foundational files from the starter pack.
+2.  **[Deployment Target Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/deployment_targets)**: Files for the chosen deployment target (e.g., `cloud_run`).
+3.  **[Frontend Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/frontends)** (Optional): If a `frontend_type` is specified, its files are copied.
+4.  **[Base Agent Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/agents)**: The application logic from the `base_template` you specified (e.g., files from `agents/adk_base/`).
+5.  **Remote Template Files**: **(Highest Precedence)** All files from the root of your remote repository (except for the `.template` directory itself).
+
+## Managing Dependencies
+
+You have full control over the Python dependencies. Both `pyproject.toml` and `uv.lock` must be at the **root** of your remote template repository.
+*   **`pyproject.toml`**: Required file that replaces the base template's version. Must include all dependencies for your agent.
+
+*   **`uv.lock`**: Strongly recommended to ensure reproducibility.
+    *   If present, guarantees exact dependency versions.
+    *   If missing, falls back to base template's lock file. A new lock file will be generatede by the user when performing installation.
+
+**Best Practice:** Always run `uv lock` after changing dependencies and commit the resulting lock file.
+
+## Makefile Behavior
+
+You cannot replace the `Makefile` from the `base_template`. However, you can add new commands or override existing ones via the `settings.commands` section in your `templateconfig.yaml`.
+
+**Example:**
+```yaml
+settings:
+  commands:
+    override:
+      # Replaces the default 'make install' command
+      install: "uv sync --dev --extra jupyter"
+    extra:
+      # Adds 'make custom-lint'
+      custom-lint:
+        command: "ruff check ."
+        description: "Run a custom lint check."
+```
+
+## Configuration Reference
+
+The `templateconfig.yaml` file is the control center for defining an agent's properties, for both built-in and remote templates. For a complete breakdown of all available fields and their options, see the [Template Config Reference](./template-config-reference.md).
+
+## Usage Reference
+
+### Creating a Project from a Template
+
+Use the `create` command with the `--agent` (`-a`) flag.
+
+*   **Full GitHub URL:**
+    ```bash
+    uvx agent-starter-pack create my-agent -a https://github.com/my-org/my-repo/tree/main/path-to-template
+    ```
+
+*   **Shorthand URL (GitHub, GitLab, Bitbucket):**
+    ```bash
+    # Specify a branch/tag with @
+    uvx agent-starter-pack create my-agent -a github.com/my-org/my-repo/path-to-template@develop
+    ```
+
+*   **ADK Samples Shortcut:** A convenient alias for official Google agent examples. It allows you to create projects from the [google/adk-samples](https://github.com/google/adk-samples) repository without needing to type the full URL.
+    ```bash
+    # Creates a project from the 'gemini-fullstack' template in adk-samples
+    uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
+    ```
+
+*   **Local Testing:**
+    ```bash
+    uvx agent-starter-pack create my-test-project -a local@./path/to/your/template
+    ```
+
+### Listing Available Agents
+
+The `list` command helps you discover templates.
+
+*   **List Built-in Agents:**
+    ```bash
+    uvx agent-starter-pack list
+    ```
+
+*   **List Agents in a Remote Repository:**
+    ```bash
+    uvx agent-starter-pack list --source https://github.com/my-org/my-repo
+    ```
+
+*   **List Official ADK Samples:**
+    ```bash
+    uvx agent-starter-pack list --adk
+    ```