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

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/.cloudbuild/cd/test_e2e.yaml

@@ -20,7 +20,7 @@ steps:
     args:
       - "-c"
       - |
-        uv sync --dev --frozen
+        uv sync --dev --locked
 
   # Run unit tests using pytest
   - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
@@ -48,4 +48,4 @@ options:
     - "E2E_PROD_PROJECT=${_E2E_PROD_PROJECT}"
     - "E2E_CICD_PROJECT=${PROJECT_ID}"
     - "RUN_E2E_TESTS=1"
-timeout: 14400s
+timeout: 43200s

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/.cloudbuild/ci/lint.yaml

@@ -20,7 +20,7 @@ steps:
     args:
       - "-c"
       - |
-        uv sync --dev --extra lint --frozen
+        uv sync --dev --extra lint --locked
 
   # Run unit tests using pytest
   - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/.cloudbuild/ci/lint_templated_agents.yaml

@@ -20,7 +20,7 @@ steps:
     args:
       - "-c"
       - |
-        uv sync --frozen
+        uv sync --locked
 
   # Run unit tests using pytest
   - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/.cloudbuild/ci/test.yaml

@@ -20,7 +20,7 @@ steps:
     args:
       - "-c"
       - |
-        uv sync --dev --frozen
+        uv sync --dev --locked
 
   # Run unit tests using pytest
   - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/.cloudbuild/ci/test_templated_agents.yaml

@@ -20,7 +20,7 @@ steps:
     args:
       - "-c"
       - |
-        uv sync --frozen
+        uv sync --locked
 
   # Run unit tests using pytest
   - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.6.4
+Version: 0.7.1
 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
@@ -46,7 +46,7 @@ It accelerates development by providing a holistic, production-ready solution, a
 
 | ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |
 |---|---|---|---|
-| [Pre-built agent templates](./agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. |
+| [Pre-built agent templates](./agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. 🆕 Now integrating with [Gemini CLI](https://github.com/google-gemini/gemini-cli) |
 
 ---
  
@@ -59,24 +59,27 @@ Ready to build your AI agent? Simply run this command:
 python -m venv .venv && source .venv/bin/activate
 
 # Install the agent starter pack
-pip install agent-starter-pack
+pip install --upgrade agent-starter-pack
 
 # Create a new agent project
 agent-starter-pack create my-awesome-agent
 ```
 
-**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
-See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
-
----
-
- 🆕 The starter pack offers full support for Agent Engine, a new fully managed solution to deploy agents. Simply run this command to get started:
+<details>
+<summary> ✨ Alternative: Using uv</summary>
 
+If you have [`uv`](https://github.com/astral-sh/uv) installed, you can create and set up your project with a single command:
 ```bash
-agent-starter-pack create my-agent -d agent_engine -a adk_base
+uvx agent-starter-pack create my-fullstack-agent
 ```
+This command handles creating the project without needing to pre-install the package into a virtual environment.
+</details>
 
-*See the [full list of options](https://googlecloudplatform.github.io/agent-starter-pack/cli/create) for details.*
+**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
+
+See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
+
+---
 
 ## 🤖 Agents
 
@@ -100,7 +103,7 @@ 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.
 
 ## High-Level Architecture
 

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

@@ -21,7 +21,7 @@ It accelerates development by providing a holistic, production-ready solution, a
 
 | ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |
 |---|---|---|---|
-| [Pre-built agent templates](./agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. |
+| [Pre-built agent templates](./agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. 🆕 Now integrating with [Gemini CLI](https://github.com/google-gemini/gemini-cli) |
 
 ---
  
@@ -34,24 +34,27 @@ Ready to build your AI agent? Simply run this command:
 python -m venv .venv && source .venv/bin/activate
 
 # Install the agent starter pack
-pip install agent-starter-pack
+pip install --upgrade agent-starter-pack
 
 # Create a new agent project
 agent-starter-pack create my-awesome-agent
 ```
 
-**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
-See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
-
----
-
- 🆕 The starter pack offers full support for Agent Engine, a new fully managed solution to deploy agents. Simply run this command to get started:
+<details>
+<summary> ✨ Alternative: Using uv</summary>
 
+If you have [`uv`](https://github.com/astral-sh/uv) installed, you can create and set up your project with a single command:
 ```bash
-agent-starter-pack create my-agent -d agent_engine -a adk_base
+uvx agent-starter-pack create my-fullstack-agent
 ```
+This command handles creating the project without needing to pre-install the package into a virtual environment.
+</details>
 
-*See the [full list of options](https://googlecloudplatform.github.io/agent-starter-pack/cli/create) for details.*
+**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.
+
+See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).
+
+---
 
 ## 🤖 Agents
 
@@ -75,7 +78,7 @@ 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.
 
 ## High-Level Architecture
 

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/agents/adk_gemini_fullstack/app/agent.py

@@ -182,12 +182,33 @@ class EscalationChecker(BaseAgent):
 plan_generator = LlmAgent(
     model=config.worker_model,
     name="plan_generator",
-    description="Generates a 4-5 line action-oriented research plan, using minimal search only for topic clarification.",
+    description="Generates or refine the existing 5 line action-oriented research plan, using minimal search only for topic clarification.",
     instruction=f"""
-    You are a research strategist. Your job is to create a high-level RESEARCH PLAN, not a summary.
-    **RULE: Your output MUST be a bulleted list of 4-5 action-oriented research goals or key questions.**
-    - A good goal starts with a verb like "Analyze," "Identify," "Investigate."
+    You are a research strategist. Your job is to create a high-level RESEARCH PLAN, not a summary. If there is already a RESEARCH PLAN in the session state,
+    improve upon it based on the user feedback.
+
+    RESEARCH PLAN(SO FAR):
+    {{ research_plan? }}
+
+    **GENERAL INSTRUCTION: CLASSIFY TASK TYPES**
+    Your plan must clearly classify each goal for downstream execution. Each bullet point should start with a task type prefix:
+    - **`[RESEARCH]`**: For goals that primarily involve information gathering, investigation, analysis, or data collection (these require search tool usage by a researcher).
+    - **`[DELIVERABLE]`**: For goals that involve synthesizing collected information, creating structured outputs (e.g., tables, charts, summaries, reports), or compiling final output artifacts (these are executed AFTER research tasks, often without further search).
+
+    **INITIAL RULE: Your initial output MUST start with a bulleted list of 5 action-oriented research goals or key questions, followed by any *inherently implied* deliverables.**
+    - All initial 5 goals will be classified as `[RESEARCH]` tasks.
+    - A good goal for `[RESEARCH]` starts with a verb like "Analyze," "Identify," "Investigate."
     - A bad output is a statement of fact like "The event was in April 2024."
+    - **Proactive Implied Deliverables (Initial):** If any of your initial 5 `[RESEARCH]` goals inherently imply a standard output or deliverable (e.g., a comparative analysis suggesting a comparison table, or a comprehensive review suggesting a summary document), you MUST add these as additional, distinct goals immediately after the initial 5. Phrase these as *synthesis or output creation actions* (e.g., "Create a summary," "Develop a comparison," "Compile a report") and prefix them with `[DELIVERABLE][IMPLIED]`.
+
+    **REFINEMENT RULE**:
+    - **Integrate Feedback & Mark Changes:** When incorporating user feedback, make targeted modifications to existing bullet points. Add `[MODIFIED]` to the existing task type and status prefix (e.g., `[RESEARCH][MODIFIED]`). If the feedback introduces new goals:
+        - If it's an information gathering task, prefix it with `[RESEARCH][NEW]`.
+        - If it's a synthesis or output creation task, prefix it with `[DELIVERABLE][NEW]`.
+    - **Proactive Implied Deliverables (Refinement):** Beyond explicit user feedback, if the nature of an existing `[RESEARCH]` goal (e.g., requiring a structured comparison, deep dive analysis, or broad synthesis) or a `[DELIVERABLE]` goal inherently implies an additional, standard output or synthesis step (e.g., a detailed report following a summary, or a visual representation of complex data), proactively add this as a new goal. Phrase these as *synthesis or output creation actions* and prefix them with `[DELIVERABLE][IMPLIED]`.
+    - **Maintain Order:** Strictly maintain the original sequential order of existing bullet points. New bullets, whether `[NEW]` or `[IMPLIED]`, should generally be appended to the list, unless the user explicitly instructs a specific insertion point.
+    - **Flexible Length:** The refined plan is no longer constrained by the initial 5-bullet limit and may comprise more goals as needed to fully address the feedback and implied deliverables.
+
     **TOOL USE IS STRICTLY LIMITED:**
     Your goal is to create a generic, high-quality plan *without searching*.
     Only use `google_search` if a topic is ambiguous or time-sensitive and you absolutely cannot create a plan without a key piece of identifying information.
@@ -204,6 +225,7 @@ section_planner = LlmAgent(
     description="Breaks down the research plan into a structured markdown outline of report sections.",
     instruction="""
     You are an expert report architect. Using the research topic and the plan from the 'research_plan' state key, design a logical structure for the final report.
+    Note: Ignore all the tag nanes ([MODIFIED], [NEW], [RESEARCH], [DELIVERABLE]) in the research plan.
     Your task is to create a markdown outline with 4-6 distinct sections that cover the topic comprehensively without overlap.
     You can use any markdown format you prefer, but here's a suggested structure:
     # Section Name
@@ -224,10 +246,42 @@ section_researcher = LlmAgent(
         thinking_config=genai_types.ThinkingConfig(include_thoughts=True)
     ),
     instruction="""
-    You are a diligent and exhaustive researcher. Your task is to perform the initial, broad information gathering for a report.
-    You will be provided with a list of sections in the 'report_sections' state key.
-    For each section where 'research' is marked as 'true', generate a comprehensive list of 4-5 targeted search queries to cover the topic from multiple angles.
-    Execute all of these queries using the 'google_search' tool and synthesize the results into a detailed summary for that section.
+    You are a highly capable and diligent research and synthesis agent. Your comprehensive task is to execute a provided research plan with **absolute fidelity**, first by gathering necessary information, and then by synthesizing that information into specified outputs.
+
+    You will be provided with a sequential list of research plan goals, stored in the `research_plan` state key. Each goal will be clearly prefixed with its primary task type: `[RESEARCH]` or `[DELIVERABLE]`.
+
+    Your execution process must strictly adhere to these two distinct and sequential phases:
+
+    ---
+
+    **Phase 1: Information Gathering (`[RESEARCH]` Tasks)**
+
+    *   **Execution Directive:** You **MUST** systematically process every goal prefixed with `[RESEARCH]` before proceeding to Phase 2.
+    *   For each `[RESEARCH]` goal:
+        *   **Query Generation:** Formulate a comprehensive set of 4-5 targeted search queries. These queries must be expertly designed to broadly cover the specific intent of the `[RESEARCH]` goal from multiple angles.
+        *   **Execution:** Utilize the `google_search` tool to execute **all** generated queries for the current `[RESEARCH]` goal.
+        *   **Summarization:** Synthesize the search results into a detailed, coherent summary that directly addresses the objective of the `[RESEARCH]` goal.
+        *   **Internal Storage:** Store this summary, clearly tagged or indexed by its corresponding `[RESEARCH]` goal, for later and exclusive use in Phase 2. You **MUST NOT** lose or discard any generated summaries.
+
+    ---
+
+    **Phase 2: Synthesis and Output Creation (`[DELIVERABLE]` Tasks)**
+
+    *   **Execution Prerequisite:** This phase **MUST ONLY COMMENCE** once **ALL** `[RESEARCH]` goals from Phase 1 have been fully completed and their summaries are internally stored.
+    *   **Execution Directive:** You **MUST** systematically process **every** goal prefixed with `[DELIVERABLE]`. For each `[DELIVERABLE]` goal, your directive is to **PRODUCE** the artifact as explicitly described.
+    *   For each `[DELIVERABLE]` goal:
+        *   **Instruction Interpretation:** You will interpret the goal's text (following the `[DELIVERABLE]` tag) as a **direct and non-negotiable instruction** to generate a specific output artifact.
+            *   *If the instruction details a table (e.g., "Create a Detailed Comparison Table in Markdown format"), your output for this step **MUST** be a properly formatted Markdown table utilizing columns and rows as implied by the instruction and the prepared data.*
+            *   *If the instruction states to prepare a summary, report, or any other structured output, your output for this step **MUST** be that precise artifact.*
+        *   **Data Consolidation:** Access and utilize **ONLY** the summaries generated during Phase 1 (`[RESEARCH]` tasks`) to fulfill the requirements of the current `[DELIVERABLE]` goal. You **MUST NOT** perform new searches.
+        *   **Output Generation:** Based on the specific instruction of the `[DELIVERABLE]` goal:
+            *   Carefully extract, organize, and synthesize the relevant information from your previously gathered summaries.
+            *   Must always produce the specified output artifact (e.g., a concise summary, a structured comparison table, a comprehensive report, a visual representation, etc.) with accuracy and completeness.
+        *   **Output Accumulation:** Maintain and accumulate **all** the generated `[DELIVERABLE]` artifacts. These are your final outputs.
+
+    ---
+
+    **Final Output:** Your final output will comprise the complete set of processed summaries from `[RESEARCH]` tasks AND all the generated artifacts from `[DELIVERABLE]` tasks, presented clearly and distinctly.
     """,
     tools=[google_search],
     output_key="section_research_findings",

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

@@ -39,6 +39,7 @@ export default defineConfig({
           { text: 'Deployment', link: '/guide/deployment' },
           { text: 'Data Ingestion', link: '/guide/data-ingestion' },
           { text: 'Observability', link: '/guide/observability' },
+          { text: 'Deploy UI', link: '/guide/deploy-ui' },
           { text: 'Troubleshooting', link: '/guide/troubleshooting' }
         ]
       },

agent_starter_pack-0.7.1/docs/guide/deploy-ui.md

@@ -0,0 +1,91 @@
+# Deploying with a User Interface
+
+This guide covers strategies for deploying agent applications with UIs to Google Cloud, focusing on approaches for development, testing, and demos.
+
+### 1. Deployment Strategies
+
+When deploying an application with both a backend and a frontend UI, two primary strategies exist.
+
+#### A. Unified Deployment
+*   **Description**: The backend and frontend are packaged and served from a single, unified service.
+*   **Best For**: This approach is simpler and well-suited for **development and testing purposes**.
+*   **Technology**: Google Cloud Run supports this model and can secure it with a single [Identity-Aware Proxy (IAP)](https://cloud.google.com/run/docs/securing/identity-aware-proxy-cloud-run) endpoint.
+
+#### B. Decoupled Deployment
+*   **Description**: The backend and frontend run as separate, independent services.
+*   **Best For**: This is a more robust, **production-oriented** architecture.
+*   **When to Use**: It becomes necessary if your backend technology is not suited for serving web frontends (e.g., if you are using a dedicated `Agent Engine`). In this case, the frontend is deployed separately to another Cloud Run service or to Cloud Storage.
+
+::: tip Note
+This guide focuses on the **Unified Deployment** strategy using Google Cloud Run, which is ideal for rapid development and internal testing.
+:::
+
+### 2. Deploy to Cloud Run with IAP
+
+The deployment method depends on whether you are using a framework's built-in UI or a custom one.
+
+#### A. Scenario 1: Built-In Framework UI
+Many agent frameworks (like ADK) include a built-in web UI or "playground" ([`adk-web`](https://github.com/google/adk-web)) that is served alongside the backend API by default. This is useful for quickly exposing the service to other developers or testers.
+
+**i. Deploy the Service:**
+Navigate to your project's root directory and run the pre-configured `make` command:
+```bash
+make backend IAP=true
+```
+This single command typically handles building the container, pushing it to a registry, deploying it to Cloud Run, and configuring IAP.
+
+#### B. Scenario 2: Custom Frontend
+If you have a separate, custom frontend (e.g., a React app for a `gemini_fullstack` agent or `live_api`) and want to deploy it with the backend for testing, the process requires a custom container configuration.
+
+**Strategy**: For development, modify the `Dockerfile` to build and run both the frontend's development server and the backend's API server within a single container.
+
+> **Important:** This approach, especially running a frontend dev server like `npm run dev`, is intended **for development and testing purposes only**. For production, you should build static frontend assets and serve them efficiently.
+
+**i. Configure the Dockerfile:**
+Create or modify your `Dockerfile` to install both Python and Node.js dependencies and to launch both services concurrently.
+
+::: details Example Dockerfile for combined backend and frontend
+```dockerfile
+FROM python:3.11-slim
+
+# Install Node.js and npm
+RUN apt-get update && apt-get install -y \
+    nodejs \
+    npm \
+    curl \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv==0.6.12
+
+WORKDIR /code
+
+# Copy backend files
+COPY ./pyproject.toml ./README.md ./uv.lock* ./
+COPY ./app ./app
+
+# Copy frontend files
+COPY ./frontend ./frontend
+
+# Install dependencies
+RUN uv sync --frozen && npm --prefix frontend install
+
+EXPOSE 8000 5173
+
+# Start both backend and frontend in parallel
+CMD ["sh", "-c", "ALLOW_ORIGINS='*' uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 & npm --prefix frontend run dev -- --host 0.0.0.0 & wait"]
+```
+:::
+
+
+**ii. 🚀 Deploy the Combined Service:**
+When deploying, you must instruct Cloud Run to direct traffic to the **frontend's port**. Pass the `PORT` variable to your `make` command. If your frontend runs on port `5173`, as in the example:
+```bash
+make backend IAP=true PORT=5173
+```
+This ensures the public, IAP-protected URL serves your user interface.
+
+### 3. Manage User Access
+Once deployed, your Cloud Run service is protected by IAP, but no users are authorized to access it yet. You must grant the "httpsResourceAccessor" role to the appropriate users or Google Groups.
+
+➡️ Follow the official Google Cloud documentation to manage access for your service: [Manage user or group access](https://cloud.google.com/run/docs/securing/identity-aware-proxy-cloud-run#manage_user_or_group_access).

agent_starter_pack-0.7.1/docs/guide/development-guide.md

@@ -0,0 +1,139 @@
+# Development Guide
+
+This guide walks you through the entire lifecycle of creating, developing, deploying, and monitoring your agent project.
+
+::: tip Our Philosophy: "Bring Your Own Agent"
+This starter pack provides the scaffolding for UI, infrastructure, deployment, and monitoring. You focus on building your unique agent logic, and we handle the rest.
+:::
+
+::: details Create Your Project
+You can use the `pip` workflow for a traditional setup, or `uvx` to create a project in a single command without a permanent install.
+
+::: code-group
+```bash [pip]
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# 2. Install the package
+pip install agent-starter-pack
+
+# 3. Run the create command
+agent-starter-pack create my-awesome-agent
+```
+
+```bash [⚡ uvx]
+# This single command downloads and runs the latest version
+`uvx agent-starter-pack create my-awesome-agent
+```
+:::
+
+## 1. Local Development & Iteration
+
+Navigate into your new project to begin development.
+
+```bash
+cd my-awesome-agent
+```
+
+Inside, you'll find a complete project structure:
+
+::: tip Leveraging AI Tools (like Gemini CLI)
+The starter pack includes a `GEMINI.md` file with guidance formatted for AI interaction. Tools like the [Gemini CLI](https://github.com/google-gemini/gemini-cli) can leverage this file when used within your project directory, providing context for questions about your template.
+:::
+
+*   `app/`: Backend agent code (prompts, tools, business logic).
+*   `deployment/`: Terraform infrastructure code.
+*   `tests/`: Unit and integration tests.
+*   `notebooks/`: Jupyter notebooks for prototyping and evaluation.
+*   `frontend/`: (If applicable) Web UI for interacting with your agent.
+*   `README.md`: **Project-specific instructions for your chosen template.**
+*   `GEMINI.md`: Use this file with AI tools (like [Gemini CLI](https://github.com/google-gemini/gemini-cli)) to ask questions about the template, ADK concepts, or project structure.
+
+
+Your development loop will look like this:
+
+1.  **Prototype:** Use the notebooks in `notebooks/` for rapid experimentation with your agent's core logic. This is ideal for trying new prompts or tools before integrating them.
+2.  **Integrate:** Edit `app/agent.py` and other files in the `app/` directory to incorporate your new logic into the main application.
+3.  **Test:** Run the interactive UI playground to test your changes. It features hot-reloading, chat history, and user feedback.
+
+```bash
+# Install dependencies and launch the local playground
+make install && make playground
+```
+> Note: The specific UI playground launched by `make playground` depends on the agent template you selected during creation.
+
+## 2. Deploy to the Cloud
+
+Once you're satisfied with local testing, you are ready to deploy your agent to Google Cloud.
+
+*All `make` commands should be run from the root of your agent project (`my-awesome-agent`).*
+
+### A. Cloud Development Environment Setup
+
+First, provision a non-production environment in the cloud for remote testing.
+
+**i. Set Google Cloud Project**
+Configure `gcloud` to target your development project.
+```bash
+# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID
+gcloud config set project YOUR_DEV_PROJECT_ID
+```
+
+**ii. Provision Cloud Resources**
+This command uses Terraform to set up necessary cloud resources for your dev environment.
+```bash
+make setup-dev-env
+```
+
+**iii. Deploy Agent Backend**
+Build and deploy your agent's backend to the dev environment.
+```bash
+make backend
+```
+
+### B. Production-Ready Deployment with CI/CD
+
+For reliable, automated deployments, a CI/CD pipeline is essential.
+
+**Option 1: One-Command CI/CD Setup (Recommended for GitHub)**
+The `agent-starter-pack` CLI can automate the entire CI/CD setup process.
+```bash
+uvx agent-starter-pack setup-cicd
+```
+This command creates a GitHub repository, connects it to Cloud Build, provisions staging/production infrastructure, and configures deployment triggers. For details, see the [`setup-cicd` CLI reference](../cli/setup_cicd).
+
+**Option 2: Manual CI/CD Setup**
+For full control or for other Git providers, refer to the [manual deployment setup guide](./deployment.md).
+
+**Trigger Your First Deployment**
+After CI/CD is configured, commit and push your code to trigger the pipeline.
+```bash
+git add -A
+git config --global user.email "you@example.com" # If not already configured
+git config --global user.name "Your Name"     # If not already configured
+git commit -m "Initial commit of agent code"
+git push --set-upstream origin main
+```
+
+## 3. Monitor Your Deployed Agent
+
+Track your agent's performance using integrated observability tools. OpenTelemetry events are automatically sent to Google Cloud services.
+
+*   **Cloud Trace & Logging**: Inspect request flows, analyze latencies, and review prompts/outputs. Access traces at: `https://console.cloud.google.com/traces/list?project=YOUR_PROD_PROJECT_ID`
+*   **BigQuery**: Route trace and log data to BigQuery for long-term storage and advanced analytics.
+*   **Looker Studio Dashboards**: Visualize agent performance with pre-built templates:
+    *   ADK Agents: [Looker Studio ADK Dashboard](https://lookerstudio.google.com/c/reporting/46b35167-b38b-4e44-bd37-701ef4307418/page/tEnnC)
+    *   Non-ADK Agents: [Looker Studio Non-ADK Dashboard](https://lookerstudio.google.com/c/reporting/fa742264-4b4b-4c56-81e6-a667dd0f853f/page/tEnnC)
+    *(Remember to follow the "Setup Instructions" within the dashboards to connect your data sources).*
+
+➡️ For details, see the [Observability Guide](./observability.md).
+
+## 4. Advanced Customization
+
+Tailor the starter pack further to meet your specific requirements.
+
+*   **RAG Data Ingestion**: For Retrieval Augmented Generation (RAG) agents, configure data pipelines to process your information and load embeddings into Vertex AI Search or Vector Search.
+    ➡️ See the [Data Ingestion Guide](./data-ingestion.md).
+*   **Custom Terraform**: Modify Terraform configurations in `deployment/terraform/` for unique infrastructure needs.
+    ➡️ Refer to the [Deployment Guide](./deployment.md).

{agent_starter_pack-0.6.4 → agent_starter_pack-0.7.1}/docs/guide/getting-started.md

@@ -1,4 +1,3 @@
-
 # 🚀 Getting Started
 
 This guide quickly walks you through setting up your first agent project.
@@ -7,44 +6,48 @@ This guide quickly walks you through setting up your first agent project.
 
 ### Prerequisites
 
-**Python 3.10+** | **Google Cloud SDK** [Install Guide](https://cloud.google.com/sdk/docs/install) | **Terraform** [Install Guide](https://developer.hashicorp.com/terraform/downloads) | **`uv` (automatically installed)** [Manual Install Guide](https://docs.astral.sh/uv/getting-started/installation/)
+**Python 3.10+** | **Google Cloud SDK** [Install Guide](https://cloud.google.com/sdk/docs/install) | **Terraform** [Install Guide](https://developer.hashicorp.com/terraform/downloads) | **`uv` (Optional, Recommended)** [Install Guide](https://docs.astral.sh/uv/getting-started/installation/)
 
-### 1. Install the Starter Pack
+### 1. Create Your Agent Project
 
-```bash
-# Create and activate a Python virtual environment (Recommended)
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+You can use the `pip` workflow for a traditional setup, or `uvx` to create a project in a single command without a permanent install. Choose your preferred method below.
 
-# Install the package
-pip install agent-starter-pack
-```
-Check the [Installation Guide](/guide/installation) for alternative installation methods.
+::: code-group
 
-### 2. Create Your Agent Project
+```bash [pip]
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate
 
-Run the `create` command and follow the prompts:
+# 2. Install the package
+pip install agent-starter-pack
 
-```bash
+# 3. Run the create command
 agent-starter-pack create my-awesome-agent
 ```
 
-This command:
-*   Lets you choose an agent template (e.g., `adk_base`, `agentic_rag`).
-*   Lets you select a deployment target (e.g., `cloud_run`, `agent_engine`).
-*   Generates a complete project structure (backend, optional frontend, deployment infra).
+```bash [⚡ uvx]
+# This single command downloads and runs the latest version
+uvx agent-starter-pack create my-awesome-agent
+```
+
+:::
+
+No matter which method you choose, the `create` command will:
+*   Let you choose an agent template (e.g., `adk_base`, `agentic_rag`).
+*   Let you select a deployment target (e.g., `cloud_run`, `agent_engine`).
+*   Generate a complete project structure (backend, optional frontend, deployment infra).
 
 **Examples:**
 
 ```bash
-# Create a RAG agent for Cloud Run (select options when prompted)
-agent-starter-pack create my-rag-agent
-
-# Create a base ADK agent for Agent Engine directly
+# You can also pass flags to skip the prompts
 agent-starter-pack create my-adk-agent -a adk_base -d agent_engine
 ```
 
-### 3. Explore and Run Locally
+### 2. Explore and Run Locally
+
+Now, navigate into your new project and run its setup commands.
 
 ```bash
 cd my-awesome-agent && make install && make playground
@@ -67,4 +70,4 @@ You're ready to go! See the [Development Guide](/guide/development-guide) for de
 
 - **Add Data (RAG):** Configure [Data Ingestion](/guide/data-ingestion) for knowledge-based agents.
 - **Monitor Performance:** Explore [Observability](/guide/observability) features for production monitoring.
-- **Deploy to Production:** Follow the [Deployment Guide](/guide/deployment) to deploy your agent to Google Cloud.
+- **Deploy to Production:** Follow the [Deployment Guide](/guide/deployment) to deploy your agent to Google Cloud.