agent-starter-pack 0.4.2__tar.gz → 0.4.4__tar.gz

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.4.2
+Version: 0.4.4
 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

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/agents/live_api/README.md

@@ -6,7 +6,7 @@ This pattern showcases a real-time conversational agent powered by Google Gemini
 
 **Key components:**
 
-- **Python Backend** (in `app/` folder): A production-ready server built with [FastAPI](https://fastapi.tiangolo.com/) and [google-genai](https://googleapis.github.io/python-python-genai/) that features:
+- **Python Backend** (in `app/` folder): A production-ready server built with [FastAPI](https://fastapi.tiangolo.com/) and [google-genai](https://googleapis.github.io/python-genai/) that features:
 
   - **Real-time bidirectional communication** via WebSockets between the frontend and Gemini model
   - **Integrated tool calling** with a weather information tool for demonstrating external data retrieval

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/agents/live_api/app/agent.py

@@ -22,8 +22,7 @@ from google.genai import types
 # Constants
 VERTEXAI = os.getenv("VERTEXAI", "true").lower() == "true"
 LOCATION = "us-central1"
-EMBEDDING_MODEL = "text-embedding-004"
-MODEL_ID = "gemini-2.0-flash-exp"
+MODEL_ID = "gemini-2.0-flash-live-preview-04-09"
 
 # Initialize Google Cloud clients
 credentials, project_id = google.auth.default()

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/agents/live_api/app/server.py

@@ -70,6 +70,7 @@ class GeminiSession:
         while True:
             try:
                 data = await self.websocket.receive_json()
+
                 if isinstance(data, dict) and (
                     "realtimeInput" in data or "clientContent" in data
                 ):
@@ -98,13 +99,7 @@ class GeminiSession:
     async def _handle_tool_call(
         self, session: Any, tool_call: LiveServerToolCall
     ) -> None:
-        """Process tool calls from Gemini and send back responses.
-
-        Args:
-            session: The Gemini session
-            tool_call: Tool call request from Gemini
-        """
-        # Handle case where function_calls might be None
+        """Process tool calls from Gemini and send back responses."""
         if tool_call.function_calls is None:
             logging.debug("No function calls in tool_call")
             return
@@ -116,7 +111,14 @@ class GeminiSession:
                 logging.error(f"Function {fc.name} not found")
                 continue
             args = fc.args if fc.args is not None else {}
-            response = func(**args)
+
+            # Handle both async and sync functions appropriately
+            if asyncio.iscoroutinefunction(func):
+                # Function is already async
+                response = await func(**args)
+            else:
+                # Run sync function in a thread pool to avoid blocking
+                response = await asyncio.to_thread(func, **args)
 
             tool_response = types.LiveClientToolResponse(
                 function_responses=[
@@ -127,18 +129,15 @@ class GeminiSession:
             await session.send(input=tool_response)
 
     async def receive_from_gemini(self) -> None:
-        """Listen for and process messages from Gemini.
-
-        Continuously receives messages from Gemini, forwards them to the client,
-        and handles any tool calls. Handles connection errors gracefully.
-        """
+        """Listen for and process messages from Gemini without blocking."""
         while result := await self.session._ws.recv(decode=False):
             await self.websocket.send_bytes(result)
             raw_message = json.loads(result)
             if "toolCall" in raw_message:
                 message = types.LiveServerMessage.model_validate(raw_message)
                 tool_call = LiveServerToolCall.model_validate(message.tool_call)
-                await self._handle_tool_call(self.session, tool_call)
+                # Create a separate task to handle the tool call without blocking
+                asyncio.create_task(self._handle_tool_call(self.session, tool_call))
 
 
 def get_connect_and_run_callable(websocket: WebSocket) -> Callable:

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/docs/.vitepress/config.js

@@ -32,6 +32,7 @@ export default defineConfig({
         text: 'Guide',
         items: [
           { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Development Guide', link: '/guide/development-guide' },
           { text: 'Why Starter Pack?', link: '/guide/why_starter_pack' },
           { text: 'Video Tutorials', link: '/guide/video-tutorials' },
           { text: 'Installation', link: '/guide/installation' },

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

@@ -0,0 +1,96 @@
+# Development Guide
+
+::: tip Note
+This starter pack embraces a **"bring your own agent"** philosophy. You focus on your unique business logic, and we provide the scaffolding for UI, infrastructure, deployment, and monitoring.
+:::
+
+### 1. Prototype Your Agent
+Begin by building and experimenting with your Generative AI Agent.
+
+*   Use the introductory notebooks in `notebooks/` for guidance. This is ideal for rapid experimentation and focused agent logic development before integrating into the full application structure
+*   Evaluate its performance with [Vertex AI Evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview).
+
+### 2. Integrate Your Agent
+Incorporate your prototyped agent into the application.
+
+*   Edit `app/agent.py` to import and configure your agent.
+*   Customize code within the `app/` directory (e.g., prompts, tools, API endpoints, business logic, functionality).
+
+### 3. Test Locally
+Iterate on your agent using the built-in UI playground. It automatically reloads on code changes and offers features like chat history, user feedback, and diverse input types.
+
+> Note: The specific UI playground (e.g., Streamlit, ADK web UI) launched by `make playground` depends on the agent template you selected.
+
+### 4. 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.*
+
+#### A. Cloud Development Environment Setup
+Establish a development (dev) environment in the cloud for initial 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 (scripts in `deployment/terraform/dev/`) to set up necessary cloud resources (IAM, databases, etc.):
+```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 to staging and production, a CI/CD pipeline is essential. Customize tests within your pipeline as needed.
+
+**Option 1: One-Command CI/CD Setup (Recommended for GitHub)**
+The `agent-starter-pack` CLI streamlines CI/CD setup with GitHub:
+```bash
+agent-starter-pack setup-cicd
+```
+This automates creating a GitHub repository, connecting to Cloud Build, setting up staging/production infrastructure with Terraform, and configuring CI/CD triggers.
+
+Follow the interactive prompts. For critical systems needing granular control, consider the manual setup.
+See the [`agent-starter-pack setup-cicd` CLI reference](https://github.com/GoogleCloudPlatform/agent-starter-pack/blob/main/docs/cli/setup_cicd.md) for details. *(Note: Automated setup currently supports GitHub only).*
+
+**Option 2: Manual CI/CD Setup**
+For full control and compatibility with other Git providers, refer to the [manual deployment setup guide](./deployment.md).
+
+**Initial Commit & Push (After CI/CD Setup):**
+Once CI/CD is configured, commit and push your code to trigger the first pipeline run:
+```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
+```
+
+### 5. Monitor Your Deployed Agent
+Track your agent's performance and gather insights using integrated observability tools.
+
+*   **Technology**: OpenTelemetry events are sent to Google Cloud.
+*   **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 project's data sources).*
+
+➡️ For details, see the [Observability Guide](./observability.md).
+
+### 6. Advanced Customization & Data
+Tailor the starter pack further to meet specific needs.
+
+*   **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 requirements.
+    ➡️ Refer to the [Deployment Guide](./deployment.md).

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/docs/guide/getting-started.md

@@ -7,11 +7,7 @@ This guide quickly walks you through setting up your first agent project.
 
 ### Prerequisites
 
-Ensure you have:
-
-1.  **Python 3.10+**
-2.  **Google Cloud SDK:** [Install Guide](https://cloud.google.com/sdk/docs/install).
-3.  **Terraform:** [Install Guide](https://developer.hashicorp.com/terraform/downloads).
+**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/)
 
 ### 1. Install the Starter Pack
 

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/docs/index.md

@@ -13,6 +13,9 @@ hero:
     - theme: brand
       text: Get Started Guide
       link: /guide/getting-started
+    - theme: alt
+      text: Development Guide
+      link: /guide/development-guide
     - theme: alt
       text: Watch Demo Video
       link: https://www.youtube.com/watch?v=9zqwym-N3lg

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.4.2"
+version = "0.4.4"
 description = "CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates."
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/src/base_template/Makefile

@@ -22,7 +22,7 @@ playground:
 	uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 --reload &
 {%- endif %}
 {%- if cookiecutter.agent_name == 'live_api' %}
-	npm --prefix frontend start
+	PORT=8501 npm --prefix frontend start
 {%- else %}
 	{% if cookiecutter.deployment_target == 'agent_engine' %}PYTHONPATH=. {% endif %}uv run streamlit run frontend/streamlit_app.py --browser.serverAddress=localhost --server.enableCORS=false --server.enableXsrfProtection=false
 {%- endif %}
@@ -54,7 +54,7 @@ local-backend:
 {%- if cookiecutter.agent_name == 'live_api' %}
 
 ui:
-	npm --prefix frontend start
+	PORT=8501 npm --prefix frontend start
 {%- endif %}
 {%- endif %}
 

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/src/base_template/README.md

@@ -110,7 +110,7 @@ Here’s the recommended workflow for local development:
     This launches the Streamlit application, which connects to the backend server (by default at `http://localhost:8000`).
 
 4.  **Interact and Iterate:**
-    *   Open the Streamlit UI in your browser (usually `http://localhost:3000` or `http://localhost:3001`).
+    *   Open the Streamlit UI in your browser (usually `http://localhost:8501` or `http://localhost:3001`).
     *   Click the play button in the UI to connect to the backend.
     *   Interact with the agent! Try prompts like: *"Using the tool you have, define Governance in the context MLOPs"*
     *   Modify the agent logic in `app/agent.py`. The backend server (FastAPI with `uvicorn --reload`) should automatically restart when you save changes. Refresh the frontend if needed to see behavioral changes.

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/src/cli/commands/create.py

@@ -134,7 +134,7 @@ def create(
         console.print("\n=== GCP Agent Starter Pack :rocket:===", style="bold blue")
         console.print("Welcome to the Agent Starter Pack!")
         console.print(
-            "This tool will help you create an end-to-end production-ready AI agent in GCP!\n"
+            "This tool will help you create an end-to-end production-ready AI agent in Google Cloud!\n"
         )
         # Validate project name
         if len(project_name) > 26:
@@ -317,9 +317,9 @@ def create(
 
         console.print("\n> Success! Your agent project is ready.")
         console.print(
-            "\n📖 For more information on project structure, usage, and deployment, check out the README:"
+            f"\n📖 Project README: [cyan]cat {cd_path}/README.md[/]"
+            "\n   Online Development Guide: [cyan][link=https://goo.gle/asp-dev]https://goo.gle/asp-dev[/link][/cyan]"
         )
-        console.print(f"   [cyan]cat {cd_path}/README.md[/]")
         # Determine the correct path to display based on whether output_dir was specified
         console.print("\n🚀 To get started, run the following command:")
         console.print(

{agent_starter_pack-0.4.2 → agent_starter_pack-0.4.4}/uv.lock

@@ -11,7 +11,7 @@ resolution-markers = [
 
 [[package]]
 name = "agent-starter-pack"
-version = "0.4.2"
+version = "0.4.4"
 source = { editable = "." }
 dependencies = [
     { name = "backoff" },