agent-starter-pack 0.3.3__py3-none-any.whl → 0.21.0__py3-none-any.whl

llm.txt

@@ -0,0 +1,362 @@
+---
+**llm.txt** documents the "Agent Starter Pack" repository, providing a source of truth on its purpose, features, and usage.
+---
+
+### Section 1: Project Overview
+
+*   **Project Name:** Agent Starter Pack
+*   **Purpose:** Accelerate development of production-ready GenAI Agents on Google Cloud.
+*   **Tagline:** Production-Ready Agents on Google Cloud, faster.
+
+**The "Production Gap":**
+While prototyping GenAI agents is quick, production deployment often takes 3-9 months.
+
+**Key Challenges Addressed:**
+*   **Customization:** Business logic, data grounding, security/compliance.
+*   **Evaluation:** Metrics, quality assessment, test datasets.
+*   **Deployment:** Cloud infrastructure, CI/CD, UI integration.
+*   **Observability:** Performance tracking, user feedback.
+
+**Solution: Agent Starter Pack**
+Provides MLOps and infrastructure templates so developers focus on agent logic.
+
+*   **You Build:** Prompts, LLM interactions, business logic, agent orchestration.
+*   **We Provide:**
+    *   Deployment infrastructure, CI/CD, testing
+    *   Logging, monitoring
+    *   Evaluation tools
+    *   Data connections, UI playground
+    *   Security best practices
+
+Establishes production patterns from day one, saving setup time.
+
+---
+### Section 2: Creating & Enhancing Agent Projects
+
+Start by creating a new agent project from a predefined template, or enhance an existing project with agent capabilities. Both processes support interactive and fully automated setup.
+
+**Prerequisites:**
+Before you begin, ensure you have `uv`/`uvx`, `gcloud` CLI, `terraform`, `git`, and `gh` CLI (for automated CI/CD setup) installed and authenticated.
+
+**Installing the `agent-starter-pack` CLI:**
+Choose one method to get the `agent-starter-pack` command:
+
+1.  **`uvx` (Recommended for Zero-Install/Automation):** Run directly without prior installation.
+    ```bash
+    uvx agent-starter-pack create ...
+    ```
+2.  **Virtual Environment (`pip` or `uv`):**
+    ```bash
+    pip install agent-starter-pack
+    ```
+3.  **Persistent CLI Install (`pipx` or `uv tool`):** Installs globally in an isolated environment.
+
+---
+### `agent-starter-pack create` Command
+
+Generates a new agent project directory based on a chosen template and configuration.
+
+**Usage:**
+```bash
+agent-starter-pack create PROJECT_NAME [OPTIONS]
+```
+
+**Arguments:**
+*   `PROJECT_NAME`: Name for your new project directory and base for GCP resource naming (max 26 chars, converted to lowercase).
+
+**Template Selection:**
+*   `-a, --agent`: Agent template - built-in agents (e.g., `adk_base`, `agentic_rag`), remote templates (`adk@gemini-fullstack`, `github.com/user/repo@branch`), or local projects (`local@./path`).
+
+**Deployment Options:**
+*   `-d, --deployment-target`: Target environment (`cloud_run` or `agent_engine`).
+*   `--cicd-runner`: CI/CD runner (`google_cloud_build` or `github_actions`).
+*   `--region`: GCP region (default: `us-central1`).
+
+**Data & Storage:**
+*   `-i, --include-data-ingestion`: Include data ingestion pipeline.
+*   `-ds, --datastore`: Datastore type (`vertex_ai_search`, `vertex_ai_vector_search`, `cloud_sql`).
+*   `--session-type`: Session storage (`in_memory`, `cloud_sql`, `agent_engine`).
+
+**Project Creation:**
+*   `-o, --output-dir`: Output directory (default: current directory).
+*   `--agent-directory, -dir`: Agent code directory name (default: `app`).
+*   `--in-folder`: Create files in current directory instead of new subdirectory.
+
+**Automation:**
+*   `--auto-approve`: **Skip all interactive prompts (crucial for automation).**
+*   `--skip-checks`: Skip GCP/Vertex AI verification checks.
+*   `--debug`: Enable debug logging.
+
+**Automated Creation Example:**
+```bash
+uvx agent-starter-pack create my-automated-agent \
+  -a adk_base \
+  -d cloud_run \
+  --region us-central1 \
+  --auto-approve
+```
+
+---
+
+### `agent-starter-pack enhance` Command
+
+Enhance your existing project with AI agent capabilities by adding agent-starter-pack features in-place. This command supports all the same options as `create` but templates directly into the current directory instead of creating a new project directory.
+
+**Usage:**
+```bash
+agent-starter-pack enhance [TEMPLATE_PATH] [OPTIONS]
+```
+
+**Key Differences from `create`:**
+*   Templates into current directory (equivalent to `create --in-folder`)
+*   `TEMPLATE_PATH` defaults to current directory (`.`)
+*   Project name defaults to current directory name
+*   Additional `--base-template` option to override template inheritance
+
+**Enhanced Project Example:**
+```bash
+# Enhance current directory with agent capabilities
+uvx agent-starter-pack enhance . \
+  --base-template adk_base \
+  -d cloud_run \
+  --region us-central1 \
+  --auto-approve
+```
+
+**Project Structure:** Expects agent code in `app/` directory (configurable via `--agent-directory`).
+
+---
+
+### Available Agent Templates
+
+Templates for the `create` command (via `-a` or `--agent`):
+
+| Agent Name             | Description                                  |
+| :--------------------- | :------------------------------------------- |
+| `adk_base`             | Base ReAct agent (ADK)                       |
+| `adk_gemini_fullstack` | Production-ready fullstack research agent    |
+| `agentic_rag`          | RAG agent for document retrieval & Q&A       |
+| `langgraph_base`       | Base ReAct agent (LangGraph)                 |
+| `adk_live`             | Real-time multimodal RAG agent               |
+
+---
+
+### Including a Data Ingestion Pipeline (for RAG agents)
+
+For RAG agents needing custom document search, enabling this option automates loading, chunking, embedding documents with Vertex AI, and storing them in a vector database.
+
+**How to enable:**
+```bash
+uvx agent-starter-pack create my-rag-agent \
+  -a agentic_rag \
+  -d cloud_run \
+  -i \
+  -ds vertex_ai_search \
+  --auto-approve
+```
+**Post-creation:** Follow your new project's `data_ingestion/README.md` to deploy the necessary infrastructure.
+
+---
+### Section 3: Development & Automated Deployment Workflow
+---
+
+This section describes the end-to-end lifecycle of an agent, with emphasis on automation.
+
+
+### 1. Local Development & Iteration
+
+Once your project is created, navigate into its directory to begin development.
+
+**First, install dependencies (run once):**
+```bash
+make install
+```
+
+**Next, test your agent. The recommended method is to use a programmatic script.**
+
+#### Programmatic Testing (Recommended Workflow)
+
+This method allows for quick, automated validation of your agent's logic.
+
+1.  **Create a script:** In the project's root directory, create a Python script named `run_agent.py`.
+2.  **Invoke the agent:** In the script, write code to programmatically call your agent with sample input and `print()` the output for inspection.
+    *   **Guidance:** If you're unsure or no guidance exists, you can look at files in the `tests/` directory for examples of how to import and call the agent's main function.
+    *   **Important:** This script is for simple validation. **Assertions are not required**, and you should not create a formal `pytest` file.
+3.  **Run the test:** Execute your script from the terminal using `uv`.
+    ```bash
+    uv run python run_agent.py
+    ```
+You can keep the test file for future testing.
+
+#### Manual Testing with the UI Playground (Optional)
+
+If the user needs to interact with your agent manually in a chat interface for debugging:
+
+1.  Run the following command to start the local web UI:
+    ```bash
+    make playground
+    ```
+    This is useful for human-in-the-loop testing and features hot-reloading.
+
+### 2. Deploying to a Cloud Development Environment
+Before setting up full CI/CD, you can deploy to a personal cloud dev environment.
+
+1.  **Set Project:** `gcloud config set project YOUR_DEV_PROJECT_ID`
+2.  **Provision Resources:** `make setup-dev-env` (uses Terraform).
+3.  **Deploy Backend:** `make deploy` (builds and deploys the agent).
+
+### 3. Automated Production-Ready Deployment with CI/CD
+For reliable deployments, the `setup-cicd` command streamlines the entire process. It creates a GitHub repo, connects it to your chosen CI/CD runner (Google Cloud Build or GitHub Actions), provisions staging/prod infrastructure, and configures deployment triggers.
+
+**Automated CI/CD Setup Example (Recommended):**
+```bash
+# Run from the project root. This command will guide you or can be automated with flags.
+uvx agent-starter-pack setup-cicd
+```
+
+**CI/CD Workflow Logic:**
+*   **On Pull Request:** CI pipeline runs tests.
+*   **On Merge to `main`:** CD pipeline deploys to staging.
+*   **Manual Approval:** A manual approval step triggers the production deployment.
+
+---
+### Section 4: Key Features & Customization
+---
+
+### Deploying with a User Interface (UI)
+*   **Unified Deployment (for Dev/Test):** The backend and frontend can be packaged and served from a single Cloud Run service, secured with Identity-Aware Proxy (IAP).
+*   **Deploying with UI:** `make deploy IAP=true`
+*   **Access Control:** After deploying with IAP, grant users the `IAP-secured Web App User` role in IAM to give them access.
+
+### Session Management
+
+For stateful agents, the starter pack supports persistent sessions.
+*   **Cloud Run:** Choose between `in_memory` (for testing) and durable `cloud_sql` sessions using the `--session-type` flag.
+*   **Agent Engine:** Provides session management automatically.
+
+### Monitoring & Observability
+*   **Technology:** Uses OpenTelemetry to emit events to Google Cloud Trace and Logging.
+*   **Custom Tracer:** A custom tracer in `app/utils/tracing.py` (or a different agent directory instead of app) handles large payloads by linking to GCS, overcoming default service limits.
+*   **Infrastructure:** A Log Router to sink data to BigQuery is provisioned by Terraform.
+
+---
+### Section 5: CLI Reference for CI/CD Setup
+---
+
+### `agent-starter-pack setup-cicd`
+Automates the complete CI/CD infrastructure setup for GitHub-based deployments. Intelligently detects your CI/CD runner (Google Cloud Build or GitHub Actions) and configures everything automatically.
+
+**Usage:**
+```bash
+uvx agent-starter-pack setup-cicd [OPTIONS]
+```
+
+**Prerequisites:** 
+- Run from the project root (directory with `pyproject.toml`)
+- Required tools: `gh` CLI (authenticated), `gcloud` CLI (authenticated), `terraform`
+- `Owner` role on GCP projects
+- GitHub token with `repo` and `workflow` scopes
+
+**Key Options:**
+*   `--staging-project`, `--prod-project`: GCP project IDs (will prompt if omitted).
+*   `--repository-name`, `--repository-owner`: GitHub repo details (will prompt if omitted).
+*   `--cicd-project`: CI/CD resources project (defaults to prod project).
+*   `--dev-project`: Development project ID (optional).
+*   `--region`: GCP region (default: `us-central1`).
+*   `--auto-approve`: Skip all interactive prompts.
+*   `--local-state`: Use local Terraform state instead of GCS backend.
+*   `--debug`: Enable debug logging.
+
+**What it does:**
+1. Creates/connects GitHub repository
+2. Sets up Terraform infrastructure with remote state
+3. Configures CI/CD runner connection (Cloud Build or GitHub Actions with WIF)
+4. Provisions staging/prod environments
+5. Sets up local Git repository with origin remote
+
+**Automated Example:**
+```bash
+uvx agent-starter-pack setup-cicd \
+  --staging-project your-staging-project \
+  --prod-project your-prod-project \
+  --repository-name your-repo-name \
+  --repository-owner your-username \
+  --auto-approve
+```
+
+**After setup, push to trigger pipeline:**
+```bash
+git add . && git commit -m "Initial commit" && git push -u origin main
+```
+
+* Note: For coding agents - ask user for required project IDs and repo details before running with `--auto-approve`.
+* Note: If user prefers different git provider, refer to `deployment/README.md` for manual deployment.
+---
+### Section 6: Operational Guidelines for Coding Agents
+
+These guidelines are essential for interacting with the Agent Starter Pack project effectively.
+
+---
+
+### Principle 1: Code Preservation & Isolation
+
+When executing code modifications using tools like `replace` or `write_file`, your paramount objective is surgical precision. You **must alter only the code segments directly targeted** by the user's request, while **strictly preserving all surrounding and unrelated code.**
+
+**Mandatory Pre-Execution Verification:**
+
+Before finalizing any `new_string` for a `replace` operation, meticulously verify the following:
+
+1.  **Target Identification:** Clearly define the exact lines or expressions to be changed, based *solely* on the user's explicit instructions.
+2.  **Preservation Check:** Compare your proposed `new_string` against the `old_string`. Ensure all code, configuration values (e.g., `model`, `version`, `api_key`), comments, and formatting *outside* the identified target remain identical and verbatim.
+
+**Example: Adhering to Preservation**
+
+*   **User Request:** "Change the agent's instruction to be a recipe suggester."
+*   **Original Code Snippet:**
+    ```python
+    root_agent = Agent(
+        name="root_agent",
+        model="gemini-2.5-flash",
+        instruction="You are a helpful AI assistant."
+    )
+    ```
+*   **Incorrect Modification (VIOLATION):**
+    ```python
+    root_agent = Agent(
+        name="recipe_suggester",
+        model="gemini-1.5-flash", # UNINTENDED MUTATION - model was not requested to change
+        instruction="You are a recipe suggester."
+    )
+    ```
+*   **Correct Modification (COMPLIANT):**
+    ```python
+    root_agent = Agent(
+        name="recipe_suggester", # OK, related to new purpose
+        model="gemini-2.5-flash", # MUST be preserved
+        instruction="You are a recipe suggester." # OK, the direct target
+    )
+    ```
+
+**Critical Error:** Failure to adhere to this preservation principle is a critical error. Always prioritize the integrity of existing, unchanged code over the convenience of rewriting entire blocks.
+
+---
+
+### Principle 2: Workflow & Execution Best Practices
+
+*   **Standard Workflow:**
+    The validated end-to-end process is: `create` → `test` → `setup-cicd` → push to deploy. Trust this high-level workflow as the default for developing and shipping agents.
+
+*   **Agent Testing:**
+    *   **Avoid `make playground`** unless specifically instructed; it is designed for human interaction. Focus on programmatic testing.
+
+*   **Model Selection:**
+    *   **When using Gemini, prefer the 2.5 model family** for optimal performance and capabilities: "gemini-2.5-pro" and "gemini-2.5-flash"
+
+*   **Running Python Commands:**
+    *   Always use `uv` to execute Python commands within this repository (e.g., `uv run run_agent.py`).
+    *   Ensure project dependencies are installed by running `make install` before executing scripts.
+    *   Consult the project's `Makefile` and `README.md` for other useful development commands.
+
+*   **Further Reading & Troubleshooting:**
+    *   For questions about specific frameworks (e.g., LangGraph) or Google Cloud products (e.g., Cloud Run), their official documentation and online resources are the best source of truth.
+    *   **When encountering persistent errors or if you're unsure how to proceed after initial troubleshooting, a targeted Google Search is strongly recommended.** It is often the fastest way to find relevant documentation, community discussions, or direct solutions to your problem.

agent_starter_pack-0.3.3.dist-info/METADATA

@@ -1,164 +0,0 @@
-Metadata-Version: 2.4
-Name: agent-starter-pack
-Version: 0.3.3
-Summary: CLI tool to create GCP-based AI 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: google-cloud-aiplatform~=1.87.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'
-Provides-Extra: lint
-Requires-Dist: codespell~=2.2.0; extra == 'lint'
-Requires-Dist: mypy~=1.15.0; extra == 'lint'
-Requires-Dist: ruff>=0.4.6; extra == 'lint'
-Requires-Dist: types-pyyaml~=6.0.12.20240917; extra == 'lint'
-Requires-Dist: types-requests~=2.32.0.20240914; extra == 'lint'
-Description-Content-Type: text/markdown
-
-# 🚀 Agent Starter Pack
-
-![Version](https://img.shields.io/pypi/v/agent-starter-pack?color=blue) [![1-Minute Video Overview](https://img.shields.io/badge/1--Minute%20Overview-gray)](https://youtu.be/jHt-ZVD660g) [![Docs](https://img.shields.io/badge/Documentation-gray)](./docs/README.md) <a href="https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Ffeat-add-firebase-studio-resources%2Fsrc%2Fresources%2Fidx">
-  <picture>
-    <source
-      media="(prefers-color-scheme: dark)"
-      srcset="https://cdn.firebasestudio.dev/btn/try_light_20.svg">
-    <source
-      media="(prefers-color-scheme: light)"
-      srcset="https://cdn.firebasestudio.dev/btn/try_dark_20.svg">
-    <img
-      height="20"
-      alt="Try in Firebase Studio"
-      src="https://cdn.firebasestudio.dev/btn/try_blue_20.svg">
-  </picture>
-</a> ![Stars](https://img.shields.io/github/stars/GoogleCloudPlatform/agent-starter-pack?color=yellow)
-
-
-The `agent-starter-pack` is a collection of production-ready Generative AI Agent templates built for Google Cloud. <br>
-It accelerates development by providing a holistic, production-ready solution, addressing common challenges (Deployment & Operations, Evaluation, Customization, Observability) in building and deploying GenAI agents.
-
-| ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |
-|---|---|---|---|
-| [Pre-built agent templates](./agents/) (ReAct, RAG, multi-agent, Live Multimodal 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](./docs/observability.md), and [CI/CD](./docs/deployment.md) 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. |
-
----
- 
-## ⚡ Get Started in 1 Minute
-
-Ready to build your AI agent? Simply run this command:
-
-```bash
-# Create and activate a Python virtual environment
-python -m venv venv && source venv/bin/activate
-
-# Install the agent starter pack
-pip install 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.
-For more installation options, see the [Installation Guide](docs/installation.md).  You can also [try it in Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) with zero setup.
-
----
-
- 🆕 The starter pack offers full support for Agent Engine, a new fully managed solution to deploy agents. Simply run this command to get started:
-
-```bash
-agent-starter-pack create my-agent -d agent_engine -a adk_base
-```
-
-*See the [full list of options](docs/cli/create.md) for details.*
-
-## 🤖 Agents
-
-| Agent Name                  | Description                                                                                                                       |
-|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `adk_base`      | A base ReAct agent implemented using Google's [Agent Development Kit](https://github.com/google/adk-python) |
-| `agentic_rag` | A RAG agent for document retrieval and Q&A. 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).       |
-| `langgraph_base_react`      | An agent implementing a base ReAct agent using LangGraph |
-| `crewai_coding_crew`       | A multi-agent system implemented with CrewAI created to support coding activities       |
-| `live_api`       | A real-time multimodal RAG agent powered by Gemini, supporting audio/video/text chat with vector DB-backed responses                       |
-
-**More agents are on the way!** We are continuously expanding our [agent library](./agents/).  Have a specific agent type in mind?  [Contribute!](#contributing)
-
-**🔍 ADK Samples**
-
-Looking to explore more ADK examples? Check out the [ADK Samples Repository](https://github.com/google/adk-samples) for additional examples and use cases demonstrating ADK's capabilities.
-
-#### Extra Features
-
-The `agent-starter-pack` offers two key features to accelerate and simplify the development of your agent:
-
-- **🔄 [CI/CD Automation (Experimental)](docs/cli/setup_cicd.md)** - One command to set up a complete GitHub + Cloud Build pipeline for all environments
-- **📥 [Data Pipeline for RAG with Terraform/CI-CD](docs/data-ingestion.md)** - 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).
-
-
-## High-Level Architecture
-
-This starter pack covers all aspects of Agent development, from prototyping and evaluation to deployment and monitoring.
-
-![High Level Architecture](docs/images/ags_high_level_architecture.png "Architecture")
-
----
-
-## 🔧 Requirements
-
-- Python 3.10+
-- [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)
-- [Terraform](https://developer.hashicorp.com/terraform/downloads) (for deployment)
-
-
-## 📚 Documentation
-See the [documentation](docs/) for more details:
-
-- [Why Use the Starter Pack?](docs/why_starter_pack.md)
-- [Installation](docs/installation.md)
-- [Deployment](docs/deployment.md)
-- [Data Ingestion](docs/data-ingestion.md)
-- [Observability](docs/observability.md)
-- [CLI Reference](docs/cli/README.md)
-- [Troubleshooting](docs/troubleshooting.md)
-
-### Video Walkthrough:
-
-- **March 6, 2025**: A [120 Minute livestream video demo](https://www.youtube.com/watch?v=yIRIT_EtALs&t=235s) of the new `agent-starter-pack` were we build 3 Agents under 30 minutes!
-- **Oct 29, 2024**: A [20-Minute Video Walkthrough](https://youtu.be/kwRG7cnqSu0) is available, showcasing the previous `agent-starter-pack`.
-
-## Explore More Generative AI Resources
-
-Looking for more examples and resources for Generative AI on Google Cloud? Check out the [GoogleCloudPlatform/generative-ai](https://github.com/GoogleCloudPlatform/generative-ai) repository for notebooks, code samples, and more!
-
-## Contributing
-
-Contributions are welcome! See the [Contributing Guide](CONTRIBUTING.md).
-
-## Feedback
-
-We value your input! Your feedback helps us improve this starter pack and make it more useful for the community.
-
-### Getting Help
-
-If you encounter any issues or have specific suggestions, please first consider [raising an issue](https://github.com/GoogleCloudPlatform/generative-ai/issues) on our GitHub repository.
-
-### Share Your Experience
-
-For other types of feedback, or if you'd like to share a positive experience or success story using this starter pack, we'd love to hear from you! You can reach out to us at <a href="mailto:agent-starter-pack@google.com">agent-starter-pack@google.com</a>.
-
-Thank you for your contributions!
-
-## Disclaimer
-
-This repository is for demonstrative purposes only and is not an officially supported Google product.
-
-## Terms of Service
-
-The agent-starter-pack templating CLI and the templates in this starter pack leverage Google Cloud APIs. When you use this starter pack, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details on the terms of service associated with these APIs.