agent-starter-pack 0.0.11b0__tar.gz → 0.0.13b0__tar.gz

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.0.11b0
+Version: 0.0.13b0
 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
@@ -52,6 +52,7 @@ agent-starter-pack create my-awesome-agent
 ```
 
 **That's it!** You now have a fully functional agent project, complete with a backend, frontend, and deployment infrastructure, ready to explore and customize.
+For more installation options, see the [Installation Guide](docs/installation.md).
 
 ---
 
@@ -113,10 +114,13 @@ This project represents the next evolution of the [e2e-gen-ai-app-starter-pack](
 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)
+- [CLI Reference](docs/cli/README.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
 **Video Walkthrough:** A [20-Minute Video Walkthrough](https://youtu.be/kwRG7cnqSu0) is available, showcasing the previous `e2e-gen-ai-app-starter-pack`. A new walkthrough for the `agent-starter-pack` will be released soon!
 

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/README.md

@@ -28,6 +28,7 @@ agent-starter-pack create my-awesome-agent
 ```
 
 **That's it!** You now have a fully functional agent project, complete with a backend, frontend, and deployment infrastructure, ready to explore and customize.
+For more installation options, see the [Installation Guide](docs/installation.md).
 
 ---
 
@@ -89,10 +90,13 @@ This project represents the next evolution of the [e2e-gen-ai-app-starter-pack](
 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)
+- [CLI Reference](docs/cli/README.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
 **Video Walkthrough:** A [20-Minute Video Walkthrough](https://youtu.be/kwRG7cnqSu0) is available, showcasing the previous `e2e-gen-ai-app-starter-pack`. A new walkthrough for the `agent-starter-pack` will be released soon!
 

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/agents/multimodal_live_api/README.md

@@ -18,42 +18,6 @@ This pattern showcases a real-time conversational RAG agent powered by Google Ge
 
 ![live api demo](https://storage.googleapis.com/github-repo/generative-ai/sample-apps/e2e-gen-ai-app-starter-pack/live_api_pattern_demo.gif)
 
-## Usage
-
-1.  **Install Dependencies:**
-
-    ```bash
-    make install
-    ```
-
-2.  **Start the Backend and Frontend:**
-
-    **Backend:**
-    ```bash
-    make backend
-    ```
-    
-    The backend will be ready when you see `INFO:     Application startup complete.` in the console.
-
-    <details>
-    <summary><b>Click here if you want to use AI Studio and API Key instead of Vertex AI:</b></summary>
-
-    ```bash
-    export VERTEXAI=false
-    export GOOGLE_API_KEY=your-google-api-key
-    ```
-
-    </details>
-    <br>
-    
-    **Frontend:**
-    ```bash
-    # In a different shell
-    make ui
-    ```
-
-    This is the suggested mode for development as it allows you to see changes in real-time.
-
 Once both the backend and frontend are running, click the play button in the frontend UI to establish a connection with the backend. You can now interact with the Multimodal Live Agent! You can try asking questions such as "Using the tool you have, define Governance in the context MLOPs" to allow the agent to use the [documentation](https://cloud.google.com/architecture/deploy-operate-generative-ai-applications) it was provided to.
 
 ## Additional Resources for Multimodal Live API

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/agents/multimodal_live_api/app/server.py

@@ -77,7 +77,7 @@ class GeminiSession:
                 elif "setup" in data:
                     self.run_id = data["setup"]["run_id"]
                     self.user_id = data["setup"]["user_id"]
-                    logging.info(f"Setup data: {data['setup']}")
+                    logger.log_struct({**data['setup'],"type": "setup"}, severity="INFO")
                 else:
                     logging.warning(f"Received unexpected input from client: {data}")
             except ConnectionClosedError as e:

agent_starter_pack-0.0.13b0/docs/installation.md

@@ -0,0 +1,72 @@
+# Installation
+
+There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow.
+
+## Using pipx (Recommended)
+
+The recommended way to install the Agent Starter Pack is with [pipx](https://pypa.github.io/pipx/), which installs the package in an isolated environment while making the commands globally available:
+
+```bash
+# Install pipx if you don't have it
+python3 -m pip install --user pipx && python3 -m pipx ensurepath
+source ~/.bashrc  # or ~/.zshrc depending on your shell
+
+# Install the Agent Starter Pack
+pipx install agent-starter-pack
+```
+
+## Using pip with a virtual environment
+
+You can also install the Agent Starter Pack in a virtual environment:
+
+```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
+```
+
+## Using uv (Fast Python package installer)
+
+For a faster installation experience, you can use [uv](https://astral.sh/uv):
+
+```bash
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+source ~/.bashrc  # or ~/.zshrc depending on your shell
+
+# Install the Agent Starter Pack
+uv pip install agent-starter-pack
+```
+
+## Getting Started
+
+After installation, you can create a new agent project:
+
+```bash
+# Create a new agent project
+agent-starter-pack create my-awesome-agent
+```
+
+
+## Upgrading
+
+To upgrade, use the same tool you used for installation:
+
+```bash
+pipx upgrade agent-starter-pack  # Using pipx
+pip install --upgrade agent-starter-pack  # Using pip
+uv pip install --upgrade agent-starter-pack  # Using uv
+```
+
+## Uninstalling
+
+To uninstall, use the same tool you used for installation:
+
+```bash
+pipx uninstall agent-starter-pack # Using pipx
+pip uninstall agent-starter-pack  # Using pip
+uv pip uninstall agent-starter-pack  # Using uv
+```

agent_starter_pack-0.0.13b0/docs/troubleshooting.md

@@ -0,0 +1,104 @@
+# Troubleshooting
+
+This guide helps resolve common issues with the Agent Starter Pack.
+
+## Authentication Issues
+
+For detailed information on authentication with Vertex AI, visit the [official documentation](https://cloud.google.com/vertex-ai/docs/authentication).
+
+### "Could not find credentials" or "Could not find project" Error
+
+**Problem**: Missing credentials error with Vertex AI.
+
+**Solution**:
+
+1.  Log in to Google Cloud: `gcloud auth login --update-adc`
+2.  Set the correct project:
+    ```bash
+    gcloud config set project YOUR_PROJECT_ID
+    gcloud auth application-default set-quota-project YOUR_PROJECT_ID
+    ```
+
+### Vertex AI API Not Enabled
+
+**Problem**: Operations fail because the Vertex AI API is not enabled in your project.
+
+**Solution**:
+
+1. Enable the Vertex AI API:
+   ```bash
+   gcloud services enable aiplatform.googleapis.com
+   ```
+
+2. Verify the API is enabled:
+   ```bash
+   gcloud services list --filter=aiplatform.googleapis.com
+   ```
+
+### Permission Denied Errors
+**Problem**: "Permission denied" errors with Google Cloud APIs.
+
+**Solution**: Ensure your user or service account has the necessary IAM roles.  For example, for Vertex AI, you often need `roles/aiplatform.user`.  Grant roles using the `gcloud projects add-iam-policy-binding` command or the Cloud Console.
+
+### Command Not Found: agent-starter-pack
+
+**Problem**: "Command not found" error after installation.
+
+**Solution**:
+
+1. Verify installation:
+   ```bash
+   pip list | grep agent-starter-pack
+   ```
+2. Check PATH:
+   ```bash
+   echo $PATH
+   ```
+3. Reinstall if needed:
+   ```bash
+   pip install --user agent-starter-pack
+   ```
+4. For pipx:
+   ```bash
+   pipx ensurepath
+   source ~/.bashrc  # or ~/.zshrc
+   ```
+
+## Project Creation Issues
+
+### Project Creation Fails
+
+**Problem**: `agent-starter-pack create` fails.
+
+**Solution**:
+
+1.  **Check Error Messages:** Examine output for clues.
+2.  **Write Permissions:** Ensure write access to the directory.
+3.  **Project Name:** Use lowercase letters, numbers and hyphens only.
+4.  **Debug Mode:** Consider using debug mode to get more detailed error information:
+    ```bash
+    agent-starter-pack create my-project-name --debug
+    ```
+
+### Template Rendering Issues
+
+**Problem**: Project created with placeholders (e.g., `{{ project_id }}`).
+
+**Solution**:
+
+1.  **Delete Project:** Remove the incorrect project directory.
+2.  **Debug Mode:** `agent-starter-pack create my-project --debug`.
+3.  **Check Configuration:** Verify GCP project and authentication setup.
+4. **File an Issue:** If it persists, file a bug report with `--debug` output.
+
+## Getting More Help
+
+If issues persist:
+
+1.  **Check GitHub Issues:** Search for existing Github issues in the `agent-starter-pack` Github repository.
+2.  **File a New Issue:** Provide:
+
+    *   Problem description.
+    *   Steps to reproduce.
+    *   Error messages (preferably run with `--debug` flag for detailed logs).
+    *   Environment: OS, Python version, `agent-starter-pack` version, installation method, shell.

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.0.11b"
+version = "0.0.13b"
 description = "CLI tool to create GCP-based AI agent projects from templates"
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/src/base_template/README.md

@@ -12,7 +12,11 @@ This project is organized as follows:
 {{cookiecutter.project_name}}/
 ├── app/                 # Core application code
 │   ├── agent.py         # Main agent logic
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+│   ├── server.py        # FastAPI Backend server
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
 │   ├── agent_engine_app.py # Agent Engine application logic
+{%- endif %}
 │   └── utils/           # Utility functions and helpers
 ├── deployment/          # Infrastructure and deployment scripts
 ├── notebooks/           # Jupyter notebooks for prototyping and evaluation
@@ -35,10 +39,10 @@ Before you begin, ensure you have:
 Install required packages using uv:
 
 ```bash
-uv sync --extra jupyter --extra streamlit --frozen
+make install
 ```
 
-### Setupx
+### Setup
 
 If not done during the initialization, set your default Google Cloud project and Location:
 
@@ -69,23 +73,108 @@ gcloud auth application-default set-quota-project $PROJECT_ID
 
 For full command options and usage, refer to the [Makefile](Makefile).
 
+{% if cookiecutter.agent_name == 'multimodal_live_api' %}
+## Usage
+
+1.  **Install Dependencies:**
+
+    ```bash
+    make install
+    ```
+
+2.  **Start the Backend and Frontend:**
+
+    **Backend:**
+    ```bash
+    make backend
+    ```
+    
+    The backend will be ready when you see `INFO:     Application startup complete.` in the console.
+
+    <details>
+    <summary><b>Click here if you want to use AI Studio and API Key instead of Vertex AI:</b></summary>
+
+    ```bash
+    export VERTEXAI=false
+    export GOOGLE_API_KEY=your-google-api-key
+    ```
+
+    </details>
+    <br>
+    
+    **Frontend:**
+    ```bash
+    # In a different shell
+    make ui
+    ```
+
+    This is the suggested mode for development as it allows you to see changes in real-time.
+
+3.  **Interact with the Agent**
+    Once both the backend and frontend are running, click the play button in the frontend UI to establish a connection with the backend. You can now interact with the Multimodal Live Agent! You can try asking questions such as "Using the tool you have, define Governance in the context MLOPs" to allow the agent to use the documentation it was provided to.
+
+**Cloud Shell usage**
+To use the `multimodal_live_api` agent in Cloud Shell, follow these steps:
+
+1.  **Start the Frontend:**
+
+    ```bash
+    make ui
+    ```
+
+    You may be prompted to run the app on a different port if port 3000 is in use. Accept by pressing Enter. You'll see a message similar to:
+
+    ```
+    You can now view multimodal-live-api-web-console in the browser.
+
+      Local:            http://localhost:3001
+      On Your Network:  http://10.88.0.4:3001
+    ```
+
+    Click the `localhost` link to open a web preview in Cloud Shell.
+
+2.  **Start the Backend:**
+
+    Open a *new* Cloud Shell terminal tab. Remember to set your Cloud Platform project in this new session using `gcloud config set project [PROJECT_ID]`. Then from the root of the repository, run:
+
+    ```bash
+    make backend
+    ```
+
+3.  **Configure Web Preview for the Backend:**
+
+    Trigger a web preview for port 8000 - you'll need to change the default port which is `8080`.  See [Cloud Shell Web Preview documentation](https://cloud.google.com/shell/docs/using-web-preview#preview_the_application) for details.
+
+4.  **Connect Frontend to Backend:**
+
+    *   The web preview will open a new tab in your browser. Copy the URL from the address bar (e.g., `https://8000-cs-8a3189b8-5295-4085-9893-c318f1724456.ql-europe-west1-ojep.cloudshell.dev/?authuser=0`).
+    *   Return to the frontend preview tab (from step 1).
+    *   Paste the copied URL into the frontend's "Server URL" connection settings.
+    *   Click the "Play button" to connect. Start interacting with it!
+
+*   When using Cloud Shell there is a known limitation when using the feedback feature in the Frontend. Feedback submission might fail due to different origins between the frontend and backend in the Cloud Shell environment.
+{%- else %}
 ## Usage
+
 1. **Prototype:** Build your Generative AI Agent using the intro notebooks in `notebooks/` for guidance. Use Vertex AI Evaluation to assess performance.
 2. **Integrate:** Import your chain into the app by editing `app/agent.py`.
 3. **Test:** Explore your chain's functionality using the Streamlit playground with `make playground`. The playground offers features like chat history, user feedback, and various input types, and automatically reloads your agent on code changes.
 4. **Deploy:** Configure and trigger the CI/CD pipelines, editing tests if needed. See the [deployment section](#deployment) for details.
 5. **Monitor:** Track performance and gather insights using Cloud Logging, Tracing, and the Looker Studio dashboard to iterate on your application.
+{% endif %}
 
 ## Deployment
 
 ### Dev Environment
 
+{%- if cookiecutter.deployment_target == 'agent_engine' %}
 You can test deployment towards a Dev Environment using the following command:
 
 ```bash
 gcloud config set project <your-dev-project-id>
 make backend
 ```
+{%- endif %}
 
 The repository includes a Terraform configuration for the setup of the Dev Google Cloud project.
 See [deployment/README.md](deployment/README.md) for instructions.

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/src/cli/utils/cicd.py

@@ -257,6 +257,17 @@ def create_github_connection(
             elif status == "PENDING_USER_OAUTH" or status == "PENDING_INSTALL_APP":
                 if attempt < max_retries - 1:  # Don't print waiting on last attempt
                     console.print("⏳ Waiting for GitHub authorization...")
+                    # Extract and print the action URI for user authentication
+                    try:
+                        action_uri = json.loads(result.stdout).get("installationState", {}).get("actionUri")
+                        if action_uri:
+                            console.print("\n🔑 Authentication Required:", style="bold yellow")
+                            console.print(f"Please visit [link={action_uri}]this page[/link] to authenticate Cloud Build with GitHub:")
+                            console.print(f"{action_uri}", style="bold blue")
+                            console.print("(Copy and paste the link into your browser if clicking doesn't work)")
+                            console.print("After completing authentication, return here to continue the setup.\n")
+                    except (json.JSONDecodeError, KeyError) as e:
+                        console.print(f"⚠️ Could not extract authentication link: {e}", style="yellow")
                     time.sleep(10)
                 continue
             else:

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.13b0}/uv.lock

@@ -11,7 +11,7 @@ resolution-markers = [
 
 [[package]]
 name = "agent-starter-pack"
-version = "0.0.11b0"
+version = "0.0.12b0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },