update the code that demoed on saturday 22 nov

.backup_adk-rag-agent_20251120_223056/.gitignore

@@ -0,0 +1,3 @@
+.env
+__pycache__/
+.venv/

.backup_adk-rag-agent_20251120_223056/README.md

@@ -0,0 +1,125 @@
+# Vertex AI RAG Agent with ADK
+
+This repository contains a Google Agent Development Kit (ADK) implementation of a Retrieval Augmented Generation (RAG) agent using Google Cloud Vertex AI.
+
+## Overview
+
+The Vertex AI RAG Agent allows you to:
+
+- Query document corpora with natural language questions
+- List available document corpora
+- Create new document corpora
+- Add new documents to existing corpora
+- Get detailed information about specific corpora
+- Delete corpora when they're no longer needed
+
+## Prerequisites
+
+- A Google Cloud account with billing enabled
+- A Google Cloud project with the Vertex AI API enabled
+- Appropriate access to create and manage Vertex AI resources
+- Python 3.9+ environment
+
+## Setting Up Google Cloud Authentication
+
+Before running the agent, you need to set up authentication with Google Cloud:
+
+1. **Install Google Cloud CLI**:
+   - Visit [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) for installation instructions for your OS
+
+2. **Initialize the Google Cloud CLI**:
+   ```bash
+   gcloud init
+   ```
+   This will guide you through logging in and selecting your project.
+
+3. **Set up Application Default Credentials**:
+   ```bash
+   gcloud auth application-default login
+   ```
+   This will open a browser window for authentication and store credentials in:
+   `~/.config/gcloud/application_default_credentials.json`
+
+4. **Verify Authentication**:
+   ```bash
+   gcloud auth list
+   gcloud config list
+   ```
+
+5. **Enable Required APIs** (if not already enabled):
+   ```bash
+   gcloud services enable aiplatform.googleapis.com
+   ```
+
+## Installation
+
+1. **Set up a virtual environment**:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+2. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Using the Agent
+
+The agent provides the following functionality through its tools:
+
+### 1. Query Documents
+Allows you to ask questions and get answers from your document corpus:
+- Automatically retrieves relevant information from the specified corpus
+- Generates informative responses based on the retrieved content
+
+### 2. List Corpora
+Shows all available document corpora in your project:
+- Displays corpus names and basic information
+- Helps you understand what data collections are available
+
+### 3. Create Corpus
+Create a new empty document corpus:
+- Specify a custom name for your corpus
+- Sets up the corpus with recommended embedding model configuration
+- Prepares the corpus for document ingestion
+
+### 4. Add New Data
+Add documents to existing corpora or create new ones:
+- Supports Google Drive URLs and GCS (Google Cloud Storage) paths
+- Automatically creates new corpora if they don't exist
+
+### 5. Get Corpus Information
+Provides detailed information about a specific corpus:
+- Shows document count, file metadata, and creation time
+- Useful for understanding corpus contents and structure
+
+### 6. Delete Corpus
+Removes corpora that are no longer needed:
+- Requires confirmation to prevent accidental deletion
+- Permanently removes the corpus and all associated files
+
+## Troubleshooting
+
+If you encounter issues:
+
+- **Authentication Problems**:
+  - Run `gcloud auth application-default login` again
+  - Check if your service account has the necessary permissions
+
+- **API Errors**:
+  - Ensure the Vertex AI API is enabled: `gcloud services enable aiplatform.googleapis.com`
+  - Verify your project has billing enabled
+
+- **Quota Issues**:
+  - Check your Google Cloud Console for any quota limitations
+  - Request quota increases if needed
+
+- **Missing Dependencies**:
+  - Ensure all requirements are installed: `pip install -r requirements.txt`
+
+## Additional Resources
+
+- [Vertex AI RAG Documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/rag-overview)
+- [Google Agent Development Kit (ADK) Documentation](https://github.com/google/agents-framework)
+- [Google Cloud Authentication Guide](https://cloud.google.com/docs/authentication)

.backup_adk-rag-agent_20251120_223056/rag_agent/__init__.py

@@ -0,0 +1,35 @@
+"""
+Vertex AI RAG Agent
+
+A package for interacting with Google Cloud Vertex AI RAG capabilities.
+"""
+
+import os
+
+import vertexai
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Get Vertex AI configuration from environment
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
+LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION")
+
+# Initialize Vertex AI at package load time
+try:
+    if PROJECT_ID and LOCATION:
+        print(f"Initializing Vertex AI with project={PROJECT_ID}, location={LOCATION}")
+        vertexai.init(project=PROJECT_ID, location=LOCATION)
+        print("Vertex AI initialization successful")
+    else:
+        print(
+            f"Missing Vertex AI configuration. PROJECT_ID={PROJECT_ID}, LOCATION={LOCATION}. "
+            f"Tools requiring Vertex AI may not work properly."
+        )
+except Exception as e:
+    print(f"Failed to initialize Vertex AI: {str(e)}")
+    print("Please check your Google Cloud credentials and project settings.")
+
+# Import agent after initialization is complete
+from . import agent

.backup_adk-rag-agent_20251120_223056/rag_agent/agent.py

@@ -0,0 +1,115 @@
+from google.adk.agents import Agent
+
+from .tools.add_data import add_data
+from .tools.create_corpus import create_corpus
+from .tools.delete_corpus import delete_corpus
+from .tools.delete_document import delete_document
+from .tools.get_corpus_info import get_corpus_info
+from .tools.list_corpora import list_corpora
+from .tools.rag_query import rag_query
+
+root_agent = Agent(
+    name="RagAgent",
+    # Using Gemini 2.5 Flash for best performance with RAG operations
+    model="gemini-2.5-flash-preview-04-17",
+    description="Vertex AI RAG Agent",
+    tools=[
+        rag_query,
+        list_corpora,
+        create_corpus,
+        add_data,
+        get_corpus_info,
+        delete_corpus,
+        delete_document,
+    ],
+    instruction="""
+    # 🧠 Vertex AI RAG Agent
+
+    You are a helpful RAG (Retrieval Augmented Generation) agent that can interact with Vertex AI's document corpora.
+    You can retrieve information from corpora, list available corpora, create new corpora, add new documents to corpora, 
+    get detailed information about specific corpora, delete specific documents from corpora, 
+    and delete entire corpora when they're no longer needed.
+    
+    ## Your Capabilities
+    
+    1. **Query Documents**: You can answer questions by retrieving relevant information from document corpora.
+    2. **List Corpora**: You can list all available document corpora to help users understand what data is available.
+    3. **Create Corpus**: You can create new document corpora for organizing information.
+    4. **Add New Data**: You can add new documents (Google Drive URLs, etc.) to existing corpora.
+    5. **Get Corpus Info**: You can provide detailed information about a specific corpus, including file metadata and statistics.
+    6. **Delete Document**: You can delete a specific document from a corpus when it's no longer needed.
+    7. **Delete Corpus**: You can delete an entire corpus and all its associated files when it's no longer needed.
+    
+    ## How to Approach User Requests
+    
+    When a user asks a question:
+    1. First, determine if they want to manage corpora (list/create/add data/get info/delete) or query existing information.
+    2. If they're asking a knowledge question, use the `rag_query` tool to search the corpus.
+    3. If they're asking about available corpora, use the `list_corpora` tool.
+    4. If they want to create a new corpus, use the `create_corpus` tool.
+    5. If they want to add data, ensure you know which corpus to add to, then use the `add_data` tool.
+    6. If they want information about a specific corpus, use the `get_corpus_info` tool.
+    7. If they want to delete a specific document, use the `delete_document` tool with confirmation.
+    8. If they want to delete an entire corpus, use the `delete_corpus` tool with confirmation.
+    
+    ## Using Tools
+    
+    You have seven specialized tools at your disposal:
+    
+    1. `rag_query`: Query a corpus to answer questions
+       - Parameters:
+         - corpus_name: The name of the corpus to query (required, but can be empty to use current corpus)
+         - query: The text question to ask
+    
+    2. `list_corpora`: List all available corpora
+       - When this tool is called, it returns the full resource names that should be used with other tools
+    
+    3. `create_corpus`: Create a new corpus
+       - Parameters:
+         - corpus_name: The name for the new corpus
+    
+    4. `add_data`: Add new data to a corpus
+       - Parameters:
+         - corpus_name: The name of the corpus to add data to (required, but can be empty to use current corpus)
+         - paths: List of Google Drive or GCS URLs
+    
+    5. `get_corpus_info`: Get detailed information about a specific corpus
+       - Parameters:
+         - corpus_name: The name of the corpus to get information about
+         
+    6. `delete_document`: Delete a specific document from a corpus
+       - Parameters:
+         - corpus_name: The name of the corpus containing the document
+         - document_id: The ID of the document to delete (can be obtained from get_corpus_info results)
+         - confirm: Boolean flag that must be set to True to confirm deletion
+         
+    7. `delete_corpus`: Delete an entire corpus and all its associated files
+       - Parameters:
+         - corpus_name: The name of the corpus to delete
+         - confirm: Boolean flag that must be set to True to confirm deletion
+    
+    ## INTERNAL: Technical Implementation Details
+    
+    This section is NOT user-facing information - don't repeat these details to users:
+    
+    - The system tracks a "current corpus" in the state. When a corpus is created or used, it becomes the current corpus.
+    - For rag_query and add_data, you can provide an empty string for corpus_name to use the current corpus.
+    - If no current corpus is set and an empty corpus_name is provided, the tools will prompt the user to specify one.
+    - Whenever possible, use the full resource name returned by the list_corpora tool when calling other tools.
+    - Using the full resource name instead of just the display name will ensure more reliable operation.
+    - Do not tell users to use full resource names in your responses - just use them internally in your tool calls.
+    
+    ## Communication Guidelines
+    
+    - Be clear and concise in your responses.
+    - If querying a corpus, explain which corpus you're using to answer the question.
+    - If managing corpora, explain what actions you've taken.
+    - When new data is added, confirm what was added and to which corpus.
+    - When corpus information is displayed, organize it clearly for the user.
+    - When deleting a document or corpus, always ask for confirmation before proceeding.
+    - If an error occurs, explain what went wrong and suggest next steps.
+    - When listing corpora, just provide the display names and basic information - don't tell users about resource names.
+    
+    Remember, your primary goal is to help users access and manage information through RAG capabilities.
+    """,
+)

.backup_adk-rag-agent_20251120_223056/rag_agent/config.py

@@ -0,0 +1,26 @@
+"""
+Configuration settings for the RAG Agent.
+
+These settings are used by the various RAG tools.
+Vertex AI initialization is performed in the package's __init__.py
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+# Load environment variables (this is redundant if __init__.py is imported first,
+# but included for safety when importing config directly)
+load_dotenv()
+
+# Vertex AI settings
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
+LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION")
+
+# RAG settings
+DEFAULT_CHUNK_SIZE = 512
+DEFAULT_CHUNK_OVERLAP = 100
+DEFAULT_TOP_K = 3
+DEFAULT_DISTANCE_THRESHOLD = 0.5
+DEFAULT_EMBEDDING_MODEL = "publishers/google/models/text-embedding-005"
+DEFAULT_EMBEDDING_REQUESTS_PER_MIN = 1000

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/__init__.py

@@ -0,0 +1,29 @@
+"""
+RAG Tools package for interacting with Vertex AI RAG corpora.
+"""
+
+from .add_data import add_data
+from .create_corpus import create_corpus
+from .delete_corpus import delete_corpus
+from .delete_document import delete_document
+from .get_corpus_info import get_corpus_info
+from .list_corpora import list_corpora
+from .rag_query import rag_query
+from .utils import (
+    check_corpus_exists,
+    get_corpus_resource_name,
+    set_current_corpus,
+)
+
+__all__ = [
+    "add_data",
+    "create_corpus",
+    "list_corpora",
+    "rag_query",
+    "get_corpus_info",
+    "delete_corpus",
+    "delete_document",
+    "check_corpus_exists",
+    "get_corpus_resource_name",
+    "set_current_corpus",
+]

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/add_data.py

@@ -0,0 +1,156 @@
+"""
+Tool for adding new data sources to a Vertex AI RAG corpus.
+"""
+
+import re
+from typing import List
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from ..config import (
+    DEFAULT_CHUNK_OVERLAP,
+    DEFAULT_CHUNK_SIZE,
+    DEFAULT_EMBEDDING_REQUESTS_PER_MIN,
+)
+from .utils import check_corpus_exists, get_corpus_resource_name
+
+
+def add_data(
+    corpus_name: str,
+    paths: List[str],
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Add new data sources to a Vertex AI RAG corpus.
+
+    Args:
+        corpus_name (str): The name of the corpus to add data to. If empty, the current corpus will be used.
+        paths (List[str]): List of URLs or GCS paths to add to the corpus.
+                          Supported formats:
+                          - Google Drive: "https://drive.google.com/file/d/{FILE_ID}/view"
+                          - Google Docs/Sheets/Slides: "https://docs.google.com/{type}/d/{FILE_ID}/..."
+                          - Google Cloud Storage: "gs://{BUCKET}/{PATH}"
+                          Example: ["https://drive.google.com/file/d/123", "gs://my_bucket/my_files_dir"]
+        tool_context (ToolContext): The tool context
+
+    Returns:
+        dict: Information about the added data and status
+    """
+    # Check if the corpus exists
+    if not check_corpus_exists(corpus_name, tool_context):
+        return {
+            "status": "error",
+            "message": f"Corpus '{corpus_name}' does not exist. Please create it first using the create_corpus tool.",
+            "corpus_name": corpus_name,
+            "paths": paths,
+        }
+
+    # Validate inputs
+    if not paths or not all(isinstance(path, str) for path in paths):
+        return {
+            "status": "error",
+            "message": "Invalid paths: Please provide a list of URLs or GCS paths",
+            "corpus_name": corpus_name,
+            "paths": paths,
+        }
+
+    # Pre-process paths to validate and convert Google Docs URLs to Drive format if needed
+    validated_paths = []
+    invalid_paths = []
+    conversions = []
+
+    for path in paths:
+        if not path or not isinstance(path, str):
+            invalid_paths.append(f"{path} (Not a valid string)")
+            continue
+
+        # Check for Google Docs/Sheets/Slides URLs and convert them to Drive format
+        docs_match = re.match(
+            r"https:\/\/docs\.google\.com\/(?:document|spreadsheets|presentation)\/d\/([a-zA-Z0-9_-]+)(?:\/|$)",
+            path,
+        )
+        if docs_match:
+            file_id = docs_match.group(1)
+            drive_url = f"https://drive.google.com/file/d/{file_id}/view"
+            validated_paths.append(drive_url)
+            conversions.append(f"{path} → {drive_url}")
+            continue
+
+        # Check for valid Drive URL format
+        drive_match = re.match(
+            r"https:\/\/drive\.google\.com\/(?:file\/d\/|open\?id=)([a-zA-Z0-9_-]+)(?:\/|$)",
+            path,
+        )
+        if drive_match:
+            # Normalize to the standard Drive URL format
+            file_id = drive_match.group(1)
+            drive_url = f"https://drive.google.com/file/d/{file_id}/view"
+            validated_paths.append(drive_url)
+            if drive_url != path:
+                conversions.append(f"{path} → {drive_url}")
+            continue
+
+        # Check for GCS paths
+        if path.startswith("gs://"):
+            validated_paths.append(path)
+            continue
+
+        # If we're here, the path wasn't in a recognized format
+        invalid_paths.append(f"{path} (Invalid format)")
+
+    # Check if we have any valid paths after validation
+    if not validated_paths:
+        return {
+            "status": "error",
+            "message": "No valid paths provided. Please provide Google Drive URLs or GCS paths.",
+            "corpus_name": corpus_name,
+            "invalid_paths": invalid_paths,
+        }
+
+    try:
+        # Get the corpus resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # Set up chunking configuration
+        transformation_config = rag.TransformationConfig(
+            chunking_config=rag.ChunkingConfig(
+                chunk_size=DEFAULT_CHUNK_SIZE,
+                chunk_overlap=DEFAULT_CHUNK_OVERLAP,
+            ),
+        )
+
+        # Import files to the corpus
+        import_result = rag.import_files(
+            corpus_resource_name,
+            validated_paths,
+            transformation_config=transformation_config,
+            max_embedding_requests_per_min=DEFAULT_EMBEDDING_REQUESTS_PER_MIN,
+        )
+
+        # Set this as the current corpus if not already set
+        if not tool_context.state.get("current_corpus"):
+            tool_context.state["current_corpus"] = corpus_name
+
+        # Build the success message
+        conversion_msg = ""
+        if conversions:
+            conversion_msg = " (Converted Google Docs URLs to Drive format)"
+
+        return {
+            "status": "success",
+            "message": f"Successfully added {import_result.imported_rag_files_count} file(s) to corpus '{corpus_name}'{conversion_msg}",
+            "corpus_name": corpus_name,
+            "files_added": import_result.imported_rag_files_count,
+            "paths": validated_paths,
+            "invalid_paths": invalid_paths,
+            "conversions": conversions,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error adding data to corpus: {str(e)}",
+            "corpus_name": corpus_name,
+            "paths": paths,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/create_corpus.py

@@ -0,0 +1,78 @@
+"""
+Tool for creating a new Vertex AI RAG corpus.
+"""
+
+import re
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from ..config import (
+    DEFAULT_EMBEDDING_MODEL,
+)
+from .utils import check_corpus_exists
+
+
+def create_corpus(
+    corpus_name: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Create a new Vertex AI RAG corpus with the specified name.
+
+    Args:
+        corpus_name (str): The name for the new corpus
+        tool_context (ToolContext): The tool context for state management
+
+    Returns:
+        dict: Status information about the operation
+    """
+    # Check if corpus already exists
+    if check_corpus_exists(corpus_name, tool_context):
+        return {
+            "status": "info",
+            "message": f"Corpus '{corpus_name}' already exists",
+            "corpus_name": corpus_name,
+            "corpus_created": False,
+        }
+
+    try:
+        # Clean corpus name for use as display name
+        display_name = re.sub(r"[^a-zA-Z0-9_-]", "_", corpus_name)
+
+        # Configure embedding model
+        embedding_model_config = rag.RagEmbeddingModelConfig(
+            vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
+                publisher_model=DEFAULT_EMBEDDING_MODEL
+            )
+        )
+
+        # Create the corpus
+        rag_corpus = rag.create_corpus(
+            display_name=display_name,
+            backend_config=rag.RagVectorDbConfig(
+                rag_embedding_model_config=embedding_model_config
+            ),
+        )
+
+        # Update state to track corpus existence
+        tool_context.state[f"corpus_exists_{corpus_name}"] = True
+
+        # Set this as the current corpus
+        tool_context.state["current_corpus"] = corpus_name
+
+        return {
+            "status": "success",
+            "message": f"Successfully created corpus '{corpus_name}'",
+            "corpus_name": rag_corpus.name,
+            "display_name": rag_corpus.display_name,
+            "corpus_created": True,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error creating corpus: {str(e)}",
+            "corpus_name": corpus_name,
+            "corpus_created": False,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/delete_corpus.py

@@ -0,0 +1,67 @@
+"""
+Tool for deleting a Vertex AI RAG corpus when it's no longer needed.
+"""
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from .utils import check_corpus_exists, get_corpus_resource_name
+
+
+def delete_corpus(
+    corpus_name: str,
+    confirm: bool,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Delete a Vertex AI RAG corpus when it's no longer needed.
+    Requires confirmation to prevent accidental deletion.
+
+    Args:
+        corpus_name (str): The full resource name of the corpus to delete.
+                           Preferably use the resource_name from list_corpora results.
+        confirm (bool): Must be set to True to confirm deletion
+        tool_context (ToolContext): The tool context
+
+    Returns:
+        dict: Status information about the deletion operation
+    """
+    # Check if corpus exists
+    if not check_corpus_exists(corpus_name, tool_context):
+        return {
+            "status": "error",
+            "message": f"Corpus '{corpus_name}' does not exist",
+            "corpus_name": corpus_name,
+        }
+
+    # Check if deletion is confirmed
+    if not confirm:
+        return {
+            "status": "error",
+            "message": "Deletion requires explicit confirmation. Set confirm=True to delete this corpus.",
+            "corpus_name": corpus_name,
+        }
+
+    try:
+        # Get the corpus resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # Delete the corpus
+        rag.delete_corpus(corpus_resource_name)
+
+        # Remove from state by setting to False
+        state_key = f"corpus_exists_{corpus_name}"
+        if state_key in tool_context.state:
+            tool_context.state[state_key] = False
+
+        return {
+            "status": "success",
+            "message": f"Successfully deleted corpus '{corpus_name}'",
+            "corpus_name": corpus_name,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error deleting corpus: {str(e)}",
+            "corpus_name": corpus_name,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/delete_document.py

@@ -0,0 +1,58 @@
+"""
+Tool for deleting a specific document from a Vertex AI RAG corpus.
+"""
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from .utils import check_corpus_exists, get_corpus_resource_name
+
+
+def delete_document(
+    corpus_name: str,
+    document_id: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Delete a specific document from a Vertex AI RAG corpus.
+
+    Args:
+        corpus_name (str): The full resource name of the corpus containing the document.
+                          Preferably use the resource_name from list_corpora results.
+        document_id (str): The ID of the specific document/file to delete. This can be
+                          obtained from get_corpus_info results.
+        tool_context (ToolContext): The tool context
+
+    Returns:
+        dict: Status information about the deletion operation
+    """
+    # Check if corpus exists
+    if not check_corpus_exists(corpus_name, tool_context):
+        return {
+            "status": "error",
+            "message": f"Corpus '{corpus_name}' does not exist",
+            "corpus_name": corpus_name,
+            "document_id": document_id,
+        }
+
+    try:
+        # Get the corpus resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # Delete the document
+        rag_file_path = f"{corpus_resource_name}/ragFiles/{document_id}"
+        rag.delete_file(rag_file_path)
+
+        return {
+            "status": "success",
+            "message": f"Successfully deleted document '{document_id}' from corpus '{corpus_name}'",
+            "corpus_name": corpus_name,
+            "document_id": document_id,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error deleting document: {str(e)}",
+            "corpus_name": corpus_name,
+            "document_id": document_id,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/get_corpus_info.py

@@ -0,0 +1,99 @@
+"""
+Tool for retrieving detailed information about a specific RAG corpus.
+"""
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from .utils import check_corpus_exists, get_corpus_resource_name
+
+
+def get_corpus_info(
+    corpus_name: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Get detailed information about a specific RAG corpus, including its files.
+
+    Args:
+        corpus_name (str): The full resource name of the corpus to get information about.
+                           Preferably use the resource_name from list_corpora results.
+        tool_context (ToolContext): The tool context
+
+    Returns:
+        dict: Information about the corpus and its files
+    """
+    try:
+        # Check if corpus exists
+        if not check_corpus_exists(corpus_name, tool_context):
+            return {
+                "status": "error",
+                "message": f"Corpus '{corpus_name}' does not exist",
+                "corpus_name": corpus_name,
+            }
+
+        # Get the corpus resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # Try to get corpus details first
+        corpus_display_name = corpus_name  # Default if we can't get actual display name
+
+        # Process file information
+        file_details = []
+        try:
+            # Get the list of files
+            files = rag.list_files(corpus_resource_name)
+            for rag_file in files:
+                # Get document specific details
+                try:
+                    # Extract the file ID from the name
+                    file_id = rag_file.name.split("/")[-1]
+
+                    file_info = {
+                        "file_id": file_id,
+                        "display_name": (
+                            rag_file.display_name
+                            if hasattr(rag_file, "display_name")
+                            else ""
+                        ),
+                        "source_uri": (
+                            rag_file.source_uri
+                            if hasattr(rag_file, "source_uri")
+                            else ""
+                        ),
+                        "create_time": (
+                            str(rag_file.create_time)
+                            if hasattr(rag_file, "create_time")
+                            else ""
+                        ),
+                        "update_time": (
+                            str(rag_file.update_time)
+                            if hasattr(rag_file, "update_time")
+                            else ""
+                        ),
+                    }
+
+                    file_details.append(file_info)
+                except Exception:
+                    # Continue to the next file
+                    continue
+        except Exception:
+            # Continue without file details
+            pass
+
+        # Basic corpus info
+        return {
+            "status": "success",
+            "message": f"Successfully retrieved information for corpus '{corpus_display_name}'",
+            "corpus_name": corpus_name,
+            "corpus_display_name": corpus_display_name,
+            "file_count": len(file_details),
+            "files": file_details,
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error getting corpus information: {str(e)}",
+            "corpus_name": corpus_name,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/list_corpora.py

@@ -0,0 +1,51 @@
+"""
+Tool for listing all available Vertex AI RAG corpora.
+"""
+
+from typing import Dict, List, Union
+
+from vertexai import rag
+
+
+def list_corpora() -> dict:
+    """
+    List all available Vertex AI RAG corpora.
+
+    Returns:
+        dict: A list of available corpora and status, with each corpus containing:
+            - resource_name: The full resource name to use with other tools
+            - display_name: The human-readable name of the corpus
+            - create_time: When the corpus was created
+            - update_time: When the corpus was last updated
+    """
+    try:
+        # Get the list of corpora
+        corpora = rag.list_corpora()
+
+        # Process corpus information into a more usable format
+        corpus_info: List[Dict[str, Union[str, int]]] = []
+        for corpus in corpora:
+            corpus_data: Dict[str, Union[str, int]] = {
+                "resource_name": corpus.name,  # Full resource name for use with other tools
+                "display_name": corpus.display_name,
+                "create_time": (
+                    str(corpus.create_time) if hasattr(corpus, "create_time") else ""
+                ),
+                "update_time": (
+                    str(corpus.update_time) if hasattr(corpus, "update_time") else ""
+                ),
+            }
+
+            corpus_info.append(corpus_data)
+
+        return {
+            "status": "success",
+            "message": f"Found {len(corpus_info)} available corpora",
+            "corpora": corpus_info,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error listing corpora: {str(e)}",
+            "corpora": [],
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/rag_query.py

@@ -0,0 +1,112 @@
+"""
+Tool for querying Vertex AI RAG corpora and retrieving relevant information.
+"""
+
+import logging
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from ..config import (
+    DEFAULT_DISTANCE_THRESHOLD,
+    DEFAULT_TOP_K,
+)
+from .utils import check_corpus_exists, get_corpus_resource_name
+
+
+def rag_query(
+    corpus_name: str,
+    query: str,
+    tool_context: ToolContext,
+) -> dict:
+    """
+    Query a Vertex AI RAG corpus with a user question and return relevant information.
+
+    Args:
+        corpus_name (str): The name of the corpus to query. If empty, the current corpus will be used.
+                          Preferably use the resource_name from list_corpora results.
+        query (str): The text query to search for in the corpus
+        tool_context (ToolContext): The tool context
+
+    Returns:
+        dict: The query results and status
+    """
+    try:
+
+        # Check if the corpus exists
+        if not check_corpus_exists(corpus_name, tool_context):
+            return {
+                "status": "error",
+                "message": f"Corpus '{corpus_name}' does not exist. Please create it first using the create_corpus tool.",
+                "query": query,
+                "corpus_name": corpus_name,
+            }
+
+        # Get the corpus resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # Configure retrieval parameters
+        rag_retrieval_config = rag.RagRetrievalConfig(
+            top_k=DEFAULT_TOP_K,
+            filter=rag.Filter(vector_distance_threshold=DEFAULT_DISTANCE_THRESHOLD),
+        )
+
+        # Perform the query
+        print("Performing retrieval query...")
+        response = rag.retrieval_query(
+            rag_resources=[
+                rag.RagResource(
+                    rag_corpus=corpus_resource_name,
+                )
+            ],
+            text=query,
+            rag_retrieval_config=rag_retrieval_config,
+        )
+
+        # Process the response into a more usable format
+        results = []
+        if hasattr(response, "contexts") and response.contexts:
+            for ctx_group in response.contexts.contexts:
+                result = {
+                    "source_uri": (
+                        ctx_group.source_uri if hasattr(ctx_group, "source_uri") else ""
+                    ),
+                    "source_name": (
+                        ctx_group.source_display_name
+                        if hasattr(ctx_group, "source_display_name")
+                        else ""
+                    ),
+                    "text": ctx_group.text if hasattr(ctx_group, "text") else "",
+                    "score": ctx_group.score if hasattr(ctx_group, "score") else 0.0,
+                }
+                results.append(result)
+
+        # If we didn't find any results
+        if not results:
+            return {
+                "status": "warning",
+                "message": f"No results found in corpus '{corpus_name}' for query: '{query}'",
+                "query": query,
+                "corpus_name": corpus_name,
+                "results": [],
+                "results_count": 0,
+            }
+
+        return {
+            "status": "success",
+            "message": f"Successfully queried corpus '{corpus_name}'",
+            "query": query,
+            "corpus_name": corpus_name,
+            "results": results,
+            "results_count": len(results),
+        }
+
+    except Exception as e:
+        error_msg = f"Error querying corpus: {str(e)}"
+        logging.error(error_msg)
+        return {
+            "status": "error",
+            "message": error_msg,
+            "query": query,
+            "corpus_name": corpus_name,
+        }

.backup_adk-rag-agent_20251120_223056/rag_agent/tools/utils.py

@@ -0,0 +1,117 @@
+"""
+Utility functions for the RAG tools.
+"""
+
+import logging
+import re
+
+from google.adk.tools.tool_context import ToolContext
+from vertexai import rag
+
+from ..config import (
+    LOCATION,
+    PROJECT_ID,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_corpus_resource_name(corpus_name: str) -> str:
+    """
+    Convert a corpus name to its full resource name if needed.
+    Handles various input formats and ensures the returned name follows Vertex AI's requirements.
+
+    Args:
+        corpus_name (str): The corpus name or display name
+
+    Returns:
+        str: The full resource name of the corpus
+    """
+    logger.info(f"Getting resource name for corpus: {corpus_name}")
+
+    # If it's already a full resource name with the projects/locations/ragCorpora format
+    if re.match(r"^projects/[^/]+/locations/[^/]+/ragCorpora/[^/]+$", corpus_name):
+        return corpus_name
+
+    # Check if this is a display name of an existing corpus
+    try:
+        # List all corpora and check if there's a match with the display name
+        corpora = rag.list_corpora()
+        for corpus in corpora:
+            if hasattr(corpus, "display_name") and corpus.display_name == corpus_name:
+                return corpus.name
+    except Exception as e:
+        logger.warning(f"Error when checking for corpus display name: {str(e)}")
+        # If we can't check, continue with the default behavior
+        pass
+
+    # If it contains partial path elements, extract just the corpus ID
+    if "/" in corpus_name:
+        # Extract the last part of the path as the corpus ID
+        corpus_id = corpus_name.split("/")[-1]
+    else:
+        corpus_id = corpus_name
+
+    # Remove any special characters that might cause issues
+    corpus_id = re.sub(r"[^a-zA-Z0-9_-]", "_", corpus_id)
+
+    # Construct the standardized resource name
+    return f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{corpus_id}"
+
+
+def check_corpus_exists(corpus_name: str, tool_context: ToolContext) -> bool:
+    """
+    Check if a corpus with the given name exists.
+
+    Args:
+        corpus_name (str): The name of the corpus to check
+        tool_context (ToolContext): The tool context for state management
+
+    Returns:
+        bool: True if the corpus exists, False otherwise
+    """
+    # Check state first if tool_context is provided
+    if tool_context.state.get(f"corpus_exists_{corpus_name}"):
+        return True
+
+    try:
+        # Get full resource name
+        corpus_resource_name = get_corpus_resource_name(corpus_name)
+
+        # List all corpora and check if this one exists
+        corpora = rag.list_corpora()
+        for corpus in corpora:
+            if (
+                corpus.name == corpus_resource_name
+                or corpus.display_name == corpus_name
+            ):
+                # Update state
+                tool_context.state[f"corpus_exists_{corpus_name}"] = True
+                # Also set this as the current corpus if no current corpus is set
+                if not tool_context.state.get("current_corpus"):
+                    tool_context.state["current_corpus"] = corpus_name
+                return True
+
+        return False
+    except Exception as e:
+        logger.error(f"Error checking if corpus exists: {str(e)}")
+        # If we can't check, assume it doesn't exist
+        return False
+
+
+def set_current_corpus(corpus_name: str, tool_context: ToolContext) -> bool:
+    """
+    Set the current corpus in the tool context state.
+
+    Args:
+        corpus_name (str): The name of the corpus to set as current
+        tool_context (ToolContext): The tool context for state management
+
+    Returns:
+        bool: True if the corpus exists and was set as current, False otherwise
+    """
+    # Check if corpus exists first
+    if check_corpus_exists(corpus_name, tool_context):
+        tool_context.state["current_corpus"] = corpus_name
+        return True
+    return False

.backup_adk-rag-agent_20251120_223056/requirements.txt

@@ -0,0 +1,5 @@
+google-cloud-aiplatform==1.92.0
+google-cloud-storage==2.19.0
+google-genai==1.14.0
+gitpython==3.1.40
+google-adk==0.5.0

.cloudbuild/deploy-to-prod.yaml

@@ -0,0 +1,52 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+steps:
+  - name: "python:3.12-slim"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        pip install uv==0.8.13 --user && uv sync --locked
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+  - name: "python:3.12-slim"
+    id: trigger-deployment
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv export --no-hashes --no-sources --no-header --no-dev --no-emit-project --no-annotate --locked > rag_agent/app_utils/.requirements.txt
+        uv run python -m rag_agent.app_utils.deploy \
+          --project ${_PROD_PROJECT_ID} \
+          --location ${_REGION} \
+          --source-packages=./rag_agent \
+          --entrypoint-module=rag_agent.agent_engine_app \
+          --entrypoint-object=agent_engine \
+          --requirements-file=rag_agent/app_utils/.requirements.txt \
+          --service-account=${_APP_SERVICE_ACCOUNT_PROD} \
+          --set-env-vars="COMMIT_SHA=${COMMIT_SHA},LOGS_BUCKET_NAME=${_LOGS_BUCKET_NAME_PROD}"
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+substitutions:
+  _PROD_PROJECT_ID: YOUR_PROD_PROJECT_ID
+  _REGION: asia-southeast1
+
+logsBucket: gs://${PROJECT_ID}-adk-rag-agent-logs/build-logs
+options:
+  substitutionOption: ALLOW_LOOSE
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

.cloudbuild/pr_checks.yaml

@@ -0,0 +1,51 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+steps:
+  # Install uv package manager and sync dependencies
+  - name: "python:3.12-slim"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        pip install uv==0.8.13 --user && uv sync --locked
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+  # Run unit tests using pytest
+  - name: "python:3.12-slim"
+    id: unit-tests
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/unit
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+  # Run integration tests
+  - name: "python:3.12-slim"
+    id: integration-tests
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/integration
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+logsBucket: gs://${PROJECT_ID}-adk-rag-agent-logs/build-logs
+options:
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

.cloudbuild/staging.yaml

@@ -0,0 +1,120 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+steps:
+  - name: "python:3.12-slim"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        pip install uv==0.8.13 --user && uv sync --locked
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+  - name: "python:3.12-slim"
+    id: deploy-staging
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv export --no-hashes --no-sources --no-header --no-dev --no-emit-project --no-annotate --locked > rag_agent/app_utils/.requirements.txt
+        uv run python -m rag_agent.app_utils.deploy \
+          --project ${_STAGING_PROJECT_ID} \
+          --location ${_REGION} \
+          --source-packages=./rag_agent \
+          --entrypoint-module=rag_agent.agent_engine_app \
+          --entrypoint-object=agent_engine \
+          --requirements-file=rag_agent/app_utils/.requirements.txt \
+          --service-account=${_APP_SERVICE_ACCOUNT_STAGING} \
+          --set-env-vars="COMMIT_SHA=${COMMIT_SHA},LOGS_BUCKET_NAME=${_LOGS_BUCKET_NAME_STAGING}"
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+
+  - name: gcr.io/cloud-builders/gcloud
+    id: fetch-auth-token
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        echo $(gcloud auth print-access-token -q) > auth_token.txt
+
+  # Load Testing
+  - name: "python:3.12-slim"
+    id: load_test
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        export _AUTH_TOKEN=$(cat auth_token.txt)
+        pip install locust==2.31.1 --user
+        locust -f tests/load_test/load_test.py \
+        --headless \
+        -t 30s -u 2 -r 0.5 \
+        --csv=tests/load_test/.results/results \
+        --html=tests/load_test/.results/report.html
+    env:
+      - 'PATH=/usr/local/bin:/usr/bin:~/.local/bin'
+
+  # Export Load Test Results to GCS
+  - name: gcr.io/cloud-builders/gcloud
+    id: export-results-to-gcs
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        export _TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+        gsutil -m cp -r tests/load_test/.results gs://${_LOGS_BUCKET_NAME_STAGING}/load-test-results/results-$${_TIMESTAMP}
+        echo "_________________________________________________________________________"
+        echo "Load test results copied to gs://${_LOGS_BUCKET_NAME_STAGING}/load-test-results/results-$${_TIMESTAMP}"
+        echo "HTTP link: https://console.cloud.google.com/storage/browser/${_LOGS_BUCKET_NAME_STAGING}/load-test-results/results-$${_TIMESTAMP}"
+        echo "_________________________________________________________________________"
+
+  # Trigger Prod Deployment
+  - name: gcr.io/cloud-builders/gcloud
+    id: trigger-prod-deployment
+    entrypoint: gcloud
+    args:
+      - "beta"
+      - "builds"
+      - "triggers"
+      - "run"
+      - "deploy-adk-rag-agent"
+      - "--region"
+      - "$LOCATION"
+      - "--project"
+      - "$PROJECT_ID"
+      - "--sha"
+      - $COMMIT_SHA
+
+  - name: gcr.io/cloud-builders/gcloud
+    id: echo-view-build-trigger-link
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        echo "_________________________________________________________________________"
+        echo "Production deployment triggered. View progress and / or approve on the Cloud Build Console:"
+        echo "https://console.cloud.google.com/cloud-build/builds;region=$LOCATION"
+        echo "_________________________________________________________________________"
+
+substitutions:
+  _STAGING_PROJECT_ID: YOUR_STAGING_PROJECT_ID
+  _REGION: asia-southeast1
+
+logsBucket: gs://${PROJECT_ID}-adk-rag-agent-logs/build-logs
+options:
+  substitutionOption: ALLOW_LOOSE
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

.gitignore

@@ -1,3 +1,4 @@
 .env
 __pycache__/
 .venv/
+deployment/terraform/

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

GEMINI.md

@@ -0,0 +1,1992 @@
+Coding Agent guidance:
+# Google Agent Development Kit (ADK) Python Cheatsheet
+
+This document serves as a long-form, comprehensive reference for building, orchestrating, and deploying AI agents using the Python Agent Development Kit (ADK). It aims to cover every significant aspect with greater detail, more code examples, and in-depth best practices.
+
+## Table of Contents
+
+1.  [Core Concepts & Project Structure](#1-core-concepts--project-structure)
+    *   1.1 ADK's Foundational Principles
+    *   1.2 Essential Primitives
+    *   1.3 Standard Project Layout
+    *   1.A Build Agents without Code (Agent Config)
+2.  [Agent Definitions (`LlmAgent`)](#2-agent-definitions-llmagent)
+    *   2.1 Basic `LlmAgent` Setup
+    *   2.2 Advanced `LlmAgent` Configuration
+    *   2.3 LLM Instruction Crafting
+    *   2.4 Production Wrapper (`App`)
+3.  [Orchestration with Workflow Agents](#3-orchestration-with-workflow-agents)
+    *   3.1 `SequentialAgent`: Linear Execution
+    *   3.2 `ParallelAgent`: Concurrent Execution
+    *   3.3 `LoopAgent`: Iterative Processes
+4.  [Multi-Agent Systems & Communication](#4-multi-agent-systems--communication)
+    *   4.1 Agent Hierarchy
+    *   4.2 Inter-Agent Communication Mechanisms
+    *   4.3 Common Multi-Agent Patterns
+    *   4.A Distributed Communication (A2A Protocol)
+5.  [Building Custom Agents (`BaseAgent`)](#5-building-custom-agents-baseagent)
+    *   5.1 When to Use Custom Agents
+    *   5.2 Implementing `_run_async_impl`
+6.  [Models: Gemini, LiteLLM, and Vertex AI](#6-models-gemini-litellm-and-vertex-ai)
+    *   6.1 Google Gemini Models (AI Studio & Vertex AI)
+    *   6.2 Other Cloud & Proprietary Models via LiteLLM
+    *   6.3 Open & Local Models via LiteLLM (Ollama, vLLM)
+    *   6.4 Customizing LLM API Clients
+7.  [Tools: The Agent's Capabilities](#7-tools-the-agents-capabilities)
+    *   7.1 Defining Function Tools: Principles & Best Practices
+    *   7.2 The `ToolContext` Object: Accessing Runtime Information
+    *   7.3 All Tool Types & Their Usage
+    *   7.4 Tool Confirmation (Human-in-the-Loop)
+8.  [Context, State, and Memory Management](#8-context-state-and-memory-management)
+    *   8.1 The `Session` Object & `SessionService`
+    *   8.2 `State`: The Conversational Scratchpad
+    *   8.3 `Memory`: Long-Term Knowledge & Retrieval
+    *   8.4 `Artifacts`: Binary Data Management
+9.  [Runtime, Events, and Execution Flow](#9-runtime-events-and-execution-flow)
+    *   9.1 Runtime Configuration (`RunConfig`)
+    *   9.2 The `Runner`: The Orchestrator
+    *   9.3 The Event Loop: Core Execution Flow
+    *   9.4 `Event` Object: The Communication Backbone
+    *   9.5 Asynchronous Programming (Python Specific)
+10. [Control Flow with Callbacks](#10-control-flow-with-callbacks)
+    *   10.1 Callback Mechanism: Interception & Control
+    *   10.2 Types of Callbacks
+    *   10.3 Callback Best Practices
+    *   10.A Global Control with Plugins
+11. [Authentication for Tools](#11-authentication-for-tools)
+    *   11.1 Core Concepts: `AuthScheme` & `AuthCredential`
+    *   11.2 Interactive OAuth/OIDC Flows
+    *   11.3 Custom Tool Authentication
+12. [Deployment Strategies](#12-deployment-strategies)
+    *   12.1 Local Development & Testing (`adk web`, `adk run`, `adk api_server`)
+    *   12.2 Vertex AI Agent Engine
+    *   12.3 Cloud Run
+    *   12.4 Google Kubernetes Engine (GKE)
+    *   12.5 CI/CD Integration
+13. [Evaluation and Safety](#13-evaluation-and-safety)
+    *   13.1 Agent Evaluation (`adk eval`)
+    *   13.2 Safety & Guardrails
+14. [Debugging, Logging & Observability](#14-debugging-logging--observability)
+15. [Streaming & Advanced I/O](#15-streaming--advanced-io)
+16. [Performance Optimization](#16-performance-optimization)
+17. [General Best Practices & Common Pitfalls](#17-general-best-practices--common-pitfalls)
+18. [Official API & CLI References](#18-official-api--cli-references)
+
+---
+
+## 1. Core Concepts & Project Structure
+
+### 1.1 ADK's Foundational Principles
+
+*   **Modularity**: Break down complex problems into smaller, manageable agents and tools.
+*   **Composability**: Combine simple agents and tools to build sophisticated systems.
+*   **Observability**: Detailed event logging and tracing capabilities to understand agent behavior.
+*   **Extensibility**: Easily integrate with external services, models, and frameworks.
+*   **Deployment-Agnostic**: Design agents once, deploy anywhere.
+
+### 1.2 Essential Primitives
+
+*   **`Agent`**: The core intelligent unit. Can be `LlmAgent` (LLM-driven) or `BaseAgent` (custom/workflow).
+*   **`Tool`**: Callable function/class providing external capabilities (`FunctionTool`, `OpenAPIToolset`, etc.).
+*   **`Session`**: A unique, stateful conversation thread with history (`events`) and short-term memory (`state`).
+*   **`State`**: Key-value dictionary within a `Session` for transient conversation data.
+*   **`Memory`**: Long-term, searchable knowledge base beyond a single session (`MemoryService`).
+*   **`Artifact`**: Named, versioned binary data (files, images) associated with a session or user.
+*   **`Runner`**: The execution engine; orchestrates agent activity and event flow.
+*   **`Event`**: Atomic unit of communication and history; carries content and side-effect `actions`.
+*   **`InvocationContext`**: The comprehensive root context object holding all runtime information for a single `run_async` call.
+
+### 1.3 Standard Project Layout
+
+A well-structured ADK project is crucial for maintainability and leveraging `adk` CLI tools.
+
+```
+your_project_root/
+├── my_first_agent/             # Each folder is a distinct agent app
+│   ├── __init__.py             # Makes `my_first_agent` a Python package (`from . import agent`)
+│   ├── agent.py                # Contains `root_agent` definition and `LlmAgent`/WorkflowAgent instances
+│   ├── tools.py                # Custom tool function definitions
+│   ├── data/                   # Optional: static data, templates
+│   └── .env                    # Environment variables (API keys, project IDs)
+├── my_second_agent/
+│   ├── __init__.py
+│   └── agent.py
+├── requirements.txt            # Project's Python dependencies (e.g., google-adk, litellm)
+├── tests/                      # Unit and integration tests
+│   ├── unit/
+│   │   └── test_tools.py
+│   └── integration/
+│       └── test_my_first_agent.py
+│       └── my_first_agent.evalset.json # Evaluation dataset for `adk eval`
+└── main.py                     # Optional: Entry point for custom FastAPI server deployment
+```
+*   `adk web` and `adk run` automatically discover agents in subdirectories with `__init__.py` and `agent.py`.
+*   `.env` files are automatically loaded by `adk` tools when run from the root or agent directory.
+
+### 1.A Build Agents without Code (Agent Config)
+
+ADK allows you to define agents, tools, and even multi-agent workflows using a simple YAML format, eliminating the need to write Python code for orchestration. This is ideal for rapid prototyping and for non-programmers to configure agents.
+
+#### **Getting Started with Agent Config**
+
+*   **Create a Config-based Agent**:
+    ```bash
+    adk create --type=config my_yaml_agent
+    ```
+    This generates a `my_yaml_agent/` folder with `root_agent.yaml` and `.env` files.
+
+*   **Environment Setup** (in `.env` file):
+    ```bash
+    # For Google AI Studio (simpler setup)
+    GOOGLE_GENAI_USE_VERTEXAI=0
+    GOOGLE_API_KEY=<your-Google-Gemini-API-key>
+    
+    # For Google Cloud Vertex AI (production)
+    GOOGLE_GENAI_USE_VERTEXAI=1
+    GOOGLE_CLOUD_PROJECT=<your_gcp_project>
+    GOOGLE_CLOUD_LOCATION=asia-southeast1
+    ```
+
+#### **Core Agent Config Structure**
+
+*   **Basic Agent (`root_agent.yaml`)**:
+    ```yaml
+    # yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
+    name: assistant_agent
+    model: gemini-2.5-flash
+    description: A helper agent that can answer users' various questions.
+    instruction: You are an agent to help answer users' various questions.
+    ```
+
+*   **Agent with Built-in Tools**:
+    ```yaml
+    name: search_agent
+    model: gemini-2.0-flash
+    description: 'an agent whose job it is to perform Google search queries and answer questions about the results.'
+    instruction: You are an agent whose job is to perform Google search queries and answer questions about the results.
+    tools:
+      - name: google_search # Built-in ADK tool
+    ```
+
+*   **Agent with Custom Tools**:
+    ```yaml
+    agent_class: LlmAgent
+    model: gemini-2.5-flash
+    name: prime_agent
+    description: Handles checking if numbers are prime.
+    instruction: |
+      You are responsible for checking whether numbers are prime.
+      When asked to check primes, you must call the check_prime tool with a list of integers.
+      Never attempt to determine prime numbers manually.
+    tools:
+      - name: ma_llm.check_prime # Reference to Python function
+    ```
+
+*   **Multi-Agent System with Sub-Agents**:
+    ```yaml
+    agent_class: LlmAgent
+    model: gemini-2.5-flash
+    name: root_agent
+    description: Learning assistant that provides tutoring in code and math.
+    instruction: |
+      You are a learning assistant that helps students with coding and math questions.
+      
+      You delegate coding questions to the code_tutor_agent and math questions to the math_tutor_agent.
+      
+      Follow these steps:
+      1. If the user asks about programming or coding, delegate to the code_tutor_agent.
+      2. If the user asks about math concepts or problems, delegate to the math_tutor_agent.
+      3. Always provide clear explanations and encourage learning.
+    sub_agents:
+      - config_path: code_tutor_agent.yaml
+      - config_path: math_tutor_agent.yaml
+    ```
+
+#### **Loading Agent Config in Python**
+
+```python
+from google.adk.agents import config_agent_utils
+root_agent = config_agent_utils.from_config("{agent_folder}/root_agent.yaml")
+```
+
+#### **Running Agent Config Agents**
+
+From the agent directory, use any of these commands:
+*   `adk web` - Launch web UI interface
+*   `adk run` - Run in terminal without UI
+*   `adk api_server` - Run as a service for other applications
+
+#### **Deployment Support**
+
+Agent Config agents can be deployed using:
+*   `adk deploy cloud_run` - Deploy to Google Cloud Run
+*   `adk deploy agent_engine` - Deploy to Vertex AI Agent Engine
+
+#### **Key Features & Capabilities**
+
+*   **Supported Built-in Tools**: `google_search`, `load_artifacts`, `url_context`, `exit_loop`, `preload_memory`, `get_user_choice`, `enterprise_web_search`, `load_web_page`
+*   **Custom Tool Integration**: Reference Python functions using fully qualified module paths
+*   **Multi-Agent Orchestration**: Link agents via `config_path` references
+*   **Schema Validation**: Built-in YAML schema for IDE support and validation
+
+#### **Current Limitations** (Experimental Feature)
+
+*   **Model Support**: Only Gemini models currently supported
+*   **Language Support**: Custom tools must be written in Python
+*   **Unsupported Agent Types**: `LangGraphAgent`, `A2aAgent`
+*   **Unsupported Tools**: `AgentTool`, `LongRunningFunctionTool`, `VertexAiSearchTool`, `MCPToolset`, `LangchainTool`, `ExampleTool`
+
+For complete examples and reference, see the [ADK samples repository](https://github.com/search?q=repo%3Agoogle%2Fadk-python+path%3A%2F%5Econtributing%5C%2Fsamples%5C%2F%2F+.yaml&type=code).
+
+---
+
+## 2. Agent Definitions (`LlmAgent`)
+
+The `LlmAgent` is the cornerstone of intelligent behavior, leveraging an LLM for reasoning and decision-making.
+
+### 2.1 Basic `LlmAgent` Setup
+
+```python
+from google.adk.agents import Agent
+
+def get_current_time(city: str) -> dict:
+    """Returns the current time in a specified city."""
+    # Mock implementation
+    if city.lower() == "new york":
+        return {"status": "success", "time": "10:30 AM EST"}
+    return {"status": "error", "message": f"Time for {city} not available."}
+
+my_first_llm_agent = Agent(
+    name="time_teller_agent",
+    model="gemini-2.5-flash", # Essential: The LLM powering the agent
+    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
+    description="Tells the current time in a specified city.", # Crucial for multi-agent delegation
+    tools=[get_current_time] # List of callable functions/tool instances
+)
+```
+
+### 2.2 Advanced `LlmAgent` Configuration
+
+*   **`generate_content_config`**: Controls LLM generation parameters (temperature, token limits, safety).
+    ```python
+    from google.genai import types as genai_types
+    from google.adk.agents import Agent
+
+    gen_config = genai_types.GenerateContentConfig(
+        temperature=0.2,            # Controls randomness (0.0-1.0), lower for more deterministic.
+        top_p=0.9,                  # Nucleus sampling: sample from top_p probability mass.
+        top_k=40,                   # Top-k sampling: sample from top_k most likely tokens.
+        max_output_tokens=1024,     # Max tokens in LLM's response.
+        stop_sequences=["## END"]   # LLM will stop generating if these sequences appear.
+    )
+    agent = Agent(
+        # ... basic config ...
+        generate_content_config=gen_config
+    )
+    ```
+
+*   **`output_key`**: Automatically saves the agent's final text or structured (if `output_schema` is used) response to the `session.state` under this key. Facilitates data flow between agents.
+    ```python
+    agent = Agent(
+        # ... basic config ...
+        output_key="llm_final_response_text"
+    )
+    # After agent runs, session.state['llm_final_response_text'] will contain its output.
+    ```
+
+*   **`input_schema` & `output_schema`**: Define strict JSON input/output formats using Pydantic models.
+    > **Warning**: Using `output_schema` forces the LLM to generate JSON and **disables** its ability to use tools or delegate to other agents.
+
+#### **Example: Defining and Using Structured Output**
+
+This is the most reliable way to make an LLM produce predictable, parseable JSON, which is essential for multi-agent workflows.
+
+1.  **Define the Schema with Pydantic:**
+    ```python
+    from pydantic import BaseModel, Field
+    from typing import Literal
+
+    class SearchQuery(BaseModel):
+        """Model representing a specific search query for web search."""
+        search_query: str = Field(
+            description="A highly specific and targeted query for web search."
+        )
+
+    class Feedback(BaseModel):
+        """Model for providing evaluation feedback on research quality."""
+        grade: Literal["pass", "fail"] = Field(
+            description="Evaluation result. 'pass' if the research is sufficient, 'fail' if it needs revision."
+        )
+        comment: str = Field(
+            description="Detailed explanation of the evaluation, highlighting strengths and/or weaknesses of the research."
+        )
+        follow_up_queries: list[SearchQuery] | None = Field(
+            default=None,
+            description="A list of specific, targeted follow-up search queries needed to fix research gaps. This should be null or empty if the grade is 'pass'."
+        )
+    ```
+    *   **`BaseModel` & `Field`**: Define data types, defaults, and crucial `description` fields. These descriptions are sent to the LLM to guide its output.
+    *   **`Literal`**: Enforces strict enum-like values (`"pass"` or `"fail"`), preventing the LLM from hallucinating unexpected values.
+
+2.  **Assign the Schema to an `LlmAgent`:**
+    ```python
+    research_evaluator = LlmAgent(
+        name="research_evaluator",
+        model="gemini-2.5-pro",
+        instruction="""You are a meticulous quality assurance analyst. Evaluate the research findings in 'section_research_findings' and be very critical.
+        If you find significant gaps, assign a grade of 'fail', write a detailed comment, and generate 5-7 specific follow-up queries.
+        If the research is thorough, grade it 'pass'.
+        Your response must be a single, raw JSON object validating against the 'Feedback' schema.
+        """,
+        output_schema=Feedback, # This forces the LLM to output JSON matching the Feedback model.
+        output_key="research_evaluation", # The resulting JSON object will be saved to state.
+        disallow_transfer_to_peers=True, # Prevents this agent from delegating. Its job is only to evaluate.
+    )
+    ```
+
+*   **`include_contents`**: Controls whether the conversation history is sent to the LLM.
+    *   `'default'` (default): Sends relevant history.
+    *   `'none'`: Sends no history; agent operates purely on current turn's input and `instruction`. Useful for stateless API wrapper agents.
+    ```python
+    agent = Agent(..., include_contents='none')
+    ```
+
+*   **`planner`**: Assign a `BasePlanner` instance to enable multi-step reasoning.
+    *   **`BuiltInPlanner`**: Leverages a model's native "thinking" or planning capabilities (e.g., Gemini).
+        ```python
+        from google.adk.planners import BuiltInPlanner
+        from google.genai.types import ThinkingConfig
+
+        agent = Agent(
+            model="gemini-2.5-flash",
+            planner=BuiltInPlanner(
+                thinking_config=ThinkingConfig(include_thoughts=True)
+            ),
+            # ... tools ...
+        )
+        ```
+    *   **`PlanReActPlanner`**: Instructs the model to follow a structured Plan-Reason-Act output format, useful for models without built-in planning.
+
+*   **`code_executor`**: Assign a `BaseCodeExecutor` to allow the agent to execute code blocks.
+    *   **`BuiltInCodeExecutor`**: The standard, sandboxed code executor provided by ADK for safe execution.
+        ```python
+        from google.adk.code_executors import BuiltInCodeExecutor
+        agent = Agent(
+            name="code_agent",
+            model="gemini-2.5-flash",
+            instruction="Write and execute Python code to solve math problems.",
+            code_executor=BuiltInCodeExecutor() # Corrected from a list to an instance
+        )
+        ```
+
+*   **Callbacks**: Hooks for observing and modifying agent behavior at key lifecycle points (`before_model_callback`, `after_tool_callback`, etc.). (Covered in Callbacks).
+
+### 2.3 LLM Instruction Crafting (`instruction`)
+
+The `instruction` is critical. It guides the LLM's behavior, persona, and tool usage. The following examples demonstrate powerful techniques for creating specialized, reliable agents.
+
+**Best Practices & Examples:**
+
+*   **Be Specific & Concise**: Avoid ambiguity.
+*   **Define Persona & Role**: Give the LLM a clear role.
+*   **Constrain Behavior & Tool Use**: Explicitly state what the LLM *and should not* do.
+*   **Define Output Format**: Tell the LLM *exactly* what its output should look like, especially when not using `output_schema`.
+*   **Dynamic Injection**: Use `{state_key}` to inject runtime data from `session.state` into the prompt.
+*   **Iteration**: Test, observe, and refine instructions.
+
+**Example 1: Constraining Tool Use and Output Format**
+```python
+import datetime
+from google.adk.tools import google_search   
+
+
+plan_generator = LlmAgent(
+    model="gemini-2.5-flash",
+    name="plan_generator",
+    description="Generates a 4-5 line action-oriented research plan.",
+    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."
+    - A bad output is a statement of fact like "The event was in April 2024."
+    **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 and you absolutely cannot create a plan without it.
+    You are explicitly forbidden from researching the *content* or *themes* of the topic.
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    """,
+    tools=[google_search],
+)
+```
+
+**Example 2: Injecting Data from State and Specifying Custom Tags**
+This agent's `instruction` relies on data placed in `session.state` by previous agents.
+```python
+report_composer = LlmAgent(
+    model="gemini-2.5-pro",
+    name="report_composer_with_citations",
+    include_contents="none", # History not needed; all data is injected.
+    description="Transforms research data and a markdown outline into a final, cited report.",
+    instruction="""
+    Transform the provided data into a polished, professional, and meticulously cited research report.
+
+    ---
+    ### INPUT DATA
+    *   Research Plan: `{research_plan}`
+    *   Research Findings: `{section_research_findings}`
+    *   Citation Sources: `{sources}`
+    *   Report Structure: `{report_sections}`
+
+    ---
+    ### CRITICAL: Citation System
+    To cite a source, you MUST insert a special citation tag directly after the claim it supports.
+
+    **The only correct format is:** `<cite source="src-ID_NUMBER" />`
+
+    ---
+    ### Final Instructions
+    Generate a comprehensive report using ONLY the `<cite source="src-ID_NUMBER" />` tag system for all citations.
+    The final report must strictly follow the structure provided in the **Report Structure** markdown outline.
+    Do not include a "References" or "Sources" section; all citations must be in-line.
+    """,
+    output_key="final_cited_report",
+)
+```
+
+### 2.4 Production Wrapper (`App`)
+Wraps the `root_agent` to enable production-grade runtime features that an `Agent` cannot handle alone.
+
+```python
+from google.adk.apps.app import App
+from google.adk.agents.context_cache_config import ContextCacheConfig
+from google.adk.apps.events_compaction_config import EventsCompactionConfig
+from google.adk.apps.resumability_config import ResumabilityConfig
+
+production_app = App(
+    name="my_app",
+    root_agent=my_agent,
+    # 1. Reduce costs/latency for long contexts
+    context_cache_config=ContextCacheConfig(min_tokens=2048, ttl_seconds=600),
+    # 2. Allow resuming crashed workflows from last state
+    resumability_config=ResumabilityConfig(is_resumable=True),
+    # 3. Manage long conversation history automatically
+    events_compaction_config=EventsCompactionConfig(compaction_interval=5, overlap_size=1)
+)
+
+# Usage: Pass 'app' instead of 'agent' to the Runner
+# runner = Runner(app=production_app, ...)
+```
+
+---
+
+## 3. Orchestration with Workflow Agents
+
+Workflow agents (`SequentialAgent`, `ParallelAgent`, `LoopAgent`) provide deterministic control flow, combining LLM capabilities with structured execution. They do **not** use an LLM for their own orchestration logic.
+
+### 3.1 `SequentialAgent`: Linear Execution
+
+Executes `sub_agents` one after another in the order defined. The `InvocationContext` is passed along, allowing state changes to be visible to subsequent agents.
+
+```python
+from google.adk.agents import SequentialAgent, Agent
+
+# Agent 1: Summarizes a document and saves to state
+summarizer = Agent(
+    name="DocumentSummarizer",
+    model="gemini-2.5-flash",
+    instruction="Summarize the provided document in 3 sentences.",
+    output_key="document_summary" # Output saved to session.state['document_summary']
+)
+
+# Agent 2: Generates questions based on the summary from state
+question_generator = Agent(
+    name="QuestionGenerator",
+    model="gemini-2.5-flash",
+    instruction="Generate 3 comprehension questions based on this summary: {document_summary}",
+    # 'document_summary' is dynamically injected from session.state
+)
+
+document_pipeline = SequentialAgent(
+    name="SummaryQuestionPipeline",
+    sub_agents=[summarizer, question_generator], # Order matters!
+    description="Summarizes a document then generates questions."
+)
+```
+
+### 3.2 `ParallelAgent`: Concurrent Execution
+
+Executes `sub_agents` simultaneously. Useful for independent tasks to reduce overall latency. All sub-agents share the same `session.state`.
+
+```python
+from google.adk.agents import ParallelAgent, Agent, SequentialAgent
+
+# Agents to fetch data concurrently
+fetch_stock_price = Agent(name="StockPriceFetcher", ..., output_key="stock_data")
+fetch_news_headlines = Agent(name="NewsFetcher", ..., output_key="news_data")
+fetch_social_sentiment = Agent(name="SentimentAnalyzer", ..., output_key="sentiment_data")
+
+# Agent to merge results (runs after ParallelAgent, usually in a SequentialAgent)
+merger_agent = Agent(
+    name="ReportGenerator",
+    model="gemini-2.5-flash",
+    instruction="Combine stock data: {stock_data}, news: {news_data}, and sentiment: {sentiment_data} into a market report."
+)
+
+# Pipeline to run parallel fetching then sequential merging
+market_analysis_pipeline = SequentialAgent(
+    name="MarketAnalyzer",
+    sub_agents=[
+        ParallelAgent(
+            name="ConcurrentFetch",
+            sub_agents=[fetch_stock_price, fetch_news_headlines, fetch_social_sentiment]
+        ),
+        merger_agent # Runs after all parallel agents complete
+    ]
+)
+```
+*   **Concurrency Caution**: When parallel agents write to the same `state` key, race conditions can occur. Always use distinct `output_key`s or manage concurrent writes explicitly.
+
+### 3.3 `LoopAgent`: Iterative Processes
+
+Repeatedly executes its `sub_agents` (sequentially within each loop iteration) until a condition is met or `max_iterations` is reached.
+
+#### **Termination of `LoopAgent`**
+A `LoopAgent` terminates when:
+1.  `max_iterations` is reached.
+2.  Any `Event` yielded by a sub-agent (or a tool within it) sets `actions.escalate = True`. This provides dynamic, content-driven loop termination.
+
+#### **Example: Iterative Refinement Loop with a Custom `BaseAgent` for Control**
+This example shows a loop that continues until a condition, determined by an evaluation agent, is met.
+
+```python
+from google.adk.agents import LoopAgent, Agent, BaseAgent
+from google.adk.events import Event, EventActions
+from google.adk.agents.invocation_context import InvocationContext
+from typing import AsyncGenerator
+
+# An LLM Agent that evaluates research and produces structured JSON output
+research_evaluator = Agent(
+    name="research_evaluator",
+    # ... configuration from Section 2.2 ...
+    output_schema=Feedback,
+    output_key="research_evaluation",
+)
+
+# An LLM Agent that performs additional searches based on feedback
+enhanced_search_executor = Agent(
+    name="enhanced_search_executor",
+    instruction="Execute the follow-up queries from 'research_evaluation' and combine with existing findings.",
+    # ... other configurations ...
+)
+
+# A custom BaseAgent to check the evaluation and stop the loop
+class EscalationChecker(BaseAgent):
+    """Checks research evaluation and escalates to stop the loop if grade is 'pass'."""
+    async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
+        evaluation = ctx.session.state.get("research_evaluation")
+        if evaluation and evaluation.get("grade") == "pass":
+            # The key to stopping the loop: yield an Event with escalate=True
+            yield Event(author=self.name, actions=EventActions(escalate=True))
+        else:
+            # Let the loop continue
+            yield Event(author=self.name)
+
+# Define the loop
+iterative_refinement_loop = LoopAgent(
+    name="IterativeRefinementLoop",
+    sub_agents=[
+        research_evaluator, # Step 1: Evaluate
+        EscalationChecker(name="EscalationChecker"), # Step 2: Check and maybe stop
+        enhanced_search_executor, # Step 3: Refine (only runs if loop didn't stop)
+    ],
+    max_iterations=5, # Fallback to prevent infinite loops
+    description="Iteratively evaluates and refines research until it passes quality checks."
+)
+```
+
+---
+
+## 4. Multi-Agent Systems & Communication
+
+Building complex applications by composing multiple, specialized agents.
+
+### 4.1 Agent Hierarchy
+
+A hierarchical (tree-like) structure of parent-child relationships defined by the `sub_agents` parameter during `BaseAgent` initialization. An agent can only have one parent.
+
+```python
+# Conceptual Hierarchy
+# Root
+# └── Coordinator (LlmAgent)
+#     ├── SalesAgent (LlmAgent)
+#     └── SupportAgent (LlmAgent)
+#     └── DataPipeline (SequentialAgent)
+#         ├── DataFetcher (LlmAgent)
+#         └── DataProcessor (LlmAgent)
+```
+
+### 4.2 Inter-Agent Communication Mechanisms
+
+1.  **Shared Session State (`session.state`)**: The most common and robust method. Agents read from and write to the same mutable dictionary.
+    *   **Mechanism**: Agent A sets `ctx.session.state['key'] = value`. Agent B later reads `ctx.session.state.get('key')`. `output_key` on `LlmAgent` is a convenient auto-setter.
+    *   **Best for**: Passing intermediate results, shared configurations, and flags in pipelines (Sequential, Loop agents).
+
+2.  **LLM-Driven Delegation (`transfer_to_agent`)**: A `LlmAgent` can dynamically hand over control to another agent based on its reasoning.
+    *   **Mechanism**: The LLM generates a special `transfer_to_agent` function call. The ADK framework intercepts this, routes the next turn to the target agent.
+    *   **Prerequisites**:
+        *   The initiating `LlmAgent` needs `instruction` to guide delegation and `description` of the target agent(s).
+        *   Target agents need clear `description`s to help the LLM decide.
+        *   Target agent must be discoverable within the current agent's hierarchy (direct `sub_agent` or a descendant).
+    *   **Configuration**: Can be enabled/disabled via `disallow_transfer_to_parent` and `disallow_transfer_to_peers` on `LlmAgent`.
+
+3.  **Explicit Invocation (`AgentTool`)**: An `LlmAgent` can treat another `BaseAgent` instance as a callable tool.
+    *   **Mechanism**: Wrap the target agent (`target_agent`) in `AgentTool(agent=target_agent)` and add it to the calling `LlmAgent`'s `tools` list. The `AgentTool` generates a `FunctionDeclaration` for the LLM. When called, `AgentTool` runs the target agent and returns its final response as the tool result.
+    *   **Best for**: Hierarchical task decomposition, where a higher-level agent needs a specific output from a lower-level agent.
+
+**Delegation vs. Agent-as-a-Tool**
+*   **Delegation (`sub_agents`)**: The parent agent *transfers control*. The sub-agent interacts directly with the user for subsequent turns until it finishes.
+*   **Agent-as-a-Tool (`AgentTool`)**: The parent agent *calls* another agent like a function. The parent remains in control, receives the sub-agent's entire interaction as a single tool result, and summarizes it for the user.
+
+```python
+# Delegation: "I'll let the specialist handle this conversation."
+root = Agent(name="root", sub_agents=[specialist])
+
+# Agent-as-a-Tool: "I need the specialist to do a task and give me the results."
+from google.adk.tools import AgentTool
+root = Agent(name="root", tools=[AgentTool(specialist)])
+```
+
+### 4.3 Common Multi-Agent Patterns
+
+*   **Coordinator/Dispatcher**: A central agent routes requests to specialized sub-agents (often via LLM-driven delegation).
+*   **Sequential Pipeline**: `SequentialAgent` orchestrates a fixed sequence of tasks, passing data via shared state.
+*   **Parallel Fan-Out/Gather**: `ParallelAgent` runs concurrent tasks, followed by a final agent that synthesizes results from state.
+*   **Review/Critique (Generator-Critic)**: `SequentialAgent` with a generator followed by a critic, often in a `LoopAgent` for iterative refinement.
+*   **Hierarchical Task Decomposition (Planner/Executor)**: High-level agents break down complex problems, delegating sub-tasks to lower-level agents (often via `AgentTool` and delegation).
+
+#### **Example: Hierarchical Planner/Executor Pattern**
+This pattern combines several mechanisms. A top-level `interactive_planner_agent` uses another agent (`plan_generator`) as a tool to create a plan, then delegates the execution of that plan to a complex `SequentialAgent` (`research_pipeline`).
+
+```python
+from google.adk.agents import LlmAgent, SequentialAgent, LoopAgent
+from google.adk.tools.agent_tool import AgentTool
+
+# Assume plan_generator, section_planner, research_evaluator, etc. are defined.
+
+# The execution pipeline itself is a complex agent.
+research_pipeline = SequentialAgent(
+    name="research_pipeline",
+    description="Executes a pre-approved research plan. It performs iterative research, evaluation, and composes a final, cited report.",
+    sub_agents=[
+        section_planner,
+        section_researcher,
+        LoopAgent(
+            name="iterative_refinement_loop",
+            max_iterations=3,
+            sub_agents=[
+                research_evaluator,
+                EscalationChecker(name="escalation_checker"),
+                enhanced_search_executor,
+            ],
+        ),
+        report_composer,
+    ],
+)
+
+# The top-level agent that interacts with the user.
+interactive_planner_agent = LlmAgent(
+    name="interactive_planner_agent",
+    model="gemini-2.5-flash",
+    description="The primary research assistant. It collaborates with the user to create a research plan, and then executes it upon approval.",
+    instruction="""
+    You are a research planning assistant. Your workflow is:
+    1.  **Plan:** Use the `plan_generator` tool to create a draft research plan.
+    2.  **Refine:** Incorporate user feedback until the plan is approved.
+    3.  **Execute:** Once the user gives EXPLICIT approval (e.g., "looks good, run it"), you MUST delegate the task to the `research_pipeline` agent.
+    Your job is to Plan, Refine, and Delegate. Do not do the research yourself.
+    """,
+    # The planner delegates to the pipeline.
+    sub_agents=[research_pipeline],
+    # The planner uses another agent as a tool.
+    tools=[AgentTool(plan_generator)],
+    output_key="research_plan",
+)
+
+# The root agent of the application is the top-level planner.
+root_agent = interactive_planner_agent
+```
+
+### 4.A. Distributed Communication (A2A Protocol)
+
+The Agent-to-Agent (A2A) Protocol enables agents to communicate over a network, even if they are written in different languages or run as separate services. Use A2A for integrating with third-party agents, building microservice-based agent architectures, or when a strong, formal API contract is needed. For internal code organization, prefer local sub-agents.
+
+*   **Exposing an Agent**: Make an existing ADK agent available to others over A2A.
+    *   **`to_a2a()` Utility**: The simplest method. Wraps your `root_agent` and creates a runnable FastAPI app, auto-generating the required `agent.json` card.
+        ```python
+        from google.adk.a2a.utils.agent_to_a2a import to_a2a
+        # root_agent is your existing ADK Agent instance
+        a2a_app = to_a2a(root_agent, port=8001)
+        # Run with: uvicorn your_module:a2a_app --host localhost --port 8001
+        ```
+    *   **`adk api_server --a2a`**: A CLI command that serves agents from a directory. Requires you to manually create an `agent.json` card for each agent you want to expose.
+
+*   **Consuming a Remote Agent**: Use a remote A2A agent as if it were a local agent.
+    *   **`RemoteA2aAgent`**: This agent acts as a client proxy. You initialize it with the URL to the remote agent's card.
+        ```python
+        from google.adk.a2a.remote_a2a_agent import RemoteA2aAgent
+
+        # This agent can now be used as a sub-agent or tool
+        prime_checker_agent = RemoteA2aAgent(
+            name="prime_agent",
+            description="A remote agent that checks if numbers are prime.",
+            agent_card="http://localhost:8001/a2a/check_prime_agent/.well-known/agent.json"
+        )
+        ```
+
+---
+
+## 5. Building Custom Agents (`BaseAgent`)
+
+For unique orchestration logic that doesn't fit standard workflow agents, inherit directly from `BaseAgent`.
+
+### 5.1 When to Use Custom Agents
+
+*   **Complex Conditional Logic**: `if/else` branching based on multiple state variables.
+*   **Dynamic Agent Selection**: Choosing which sub-agent to run based on runtime evaluation.
+*   **Direct External Integrations**: Calling external APIs or libraries directly within the orchestration flow.
+*   **Custom Loop/Retry Logic**: More sophisticated iteration patterns than `LoopAgent`, such as the `EscalationChecker` example.
+
+### 5.2 Implementing `_run_async_impl`
+
+This is the core asynchronous method you must override.
+
+#### **Example: A Custom Agent for Loop Control**
+This agent reads state, applies simple Python logic, and yields an `Event` with an `escalate` action to control a `LoopAgent`.
+
+```python
+from google.adk.agents import BaseAgent
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events import Event, EventActions
+from typing import AsyncGenerator
+import logging
+
+class EscalationChecker(BaseAgent):
+    """Checks research evaluation and escalates to stop the loop if grade is 'pass'."""
+
+    def __init__(self, name: str):
+        super().__init__(name=name)
+
+    async def _run_async_impl(
+        self, ctx: InvocationContext
+    ) -> AsyncGenerator[Event, None]:
+        # 1. Read from session state.
+        evaluation_result = ctx.session.state.get("research_evaluation")
+
+        # 2. Apply custom Python logic.
+        if evaluation_result and evaluation_result.get("grade") == "pass":
+            logging.info(
+                f"[{self.name}] Research passed. Escalating to stop loop."
+            )
+            # 3. Yield an Event with a control Action.
+            yield Event(author=self.name, actions=EventActions(escalate=True))
+        else:
+            logging.info(
+                f"[{self.name}] Research failed or not found. Loop continues."
+            )
+            # Yielding an event without actions lets the flow continue.
+            yield Event(author=self.name)
+```
+*   **Asynchronous Generator**: `async def ... yield Event`. This allows pausing and resuming execution.
+*   **`ctx: InvocationContext`**: Provides access to all session state (`ctx.session.state`).
+*   **Calling Sub-Agents**: Use `async for event in self.sub_agent_instance.run_async(ctx): yield event`.
+*   **Control Flow**: Use standard Python `if/else`, `for/while` loops for complex logic.
+
+---
+
+## 6. Models: Gemini, LiteLLM, and Vertex AI
+
+ADK's model flexibility allows integrating various LLMs for different needs.
+
+### 6.1 Google Gemini Models (AI Studio & Vertex AI)
+
+*   **Default Integration**: Native support via `google-genai` library.
+*   **AI Studio (Easy Start)**:
+    *   Set `GOOGLE_API_KEY="YOUR_API_KEY"` (environment variable).
+    *   Set `GOOGLE_GENAI_USE_VERTEXAI="False"`.
+    *   Model strings: `"gemini-2.5-flash"`, `"gemini-2.5-pro"`, etc.
+*   **Vertex AI (Production)**:
+    *   Authenticate via `gcloud auth application-default login` (recommended).
+    *   Set `GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`, `GOOGLE_CLOUD_LOCATION="your-region"` (environment variables).
+    *   Set `GOOGLE_GENAI_USE_VERTEXAI="True"`.
+    *   Model strings: `"gemini-2.5-flash"`, `"gemini-2.5-pro"`, or full Vertex AI endpoint resource names for specific deployments.
+
+### 6.2 Other Cloud & Proprietary Models via LiteLLM
+
+`LiteLlm` provides a unified interface to 100+ LLMs (OpenAI, Anthropic, Cohere, etc.).
+
+*   **Installation**: `pip install litellm`
+*   **API Keys**: Set environment variables as required by LiteLLM (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).
+*   **Usage**:
+    ```python
+    from google.adk.models.lite_llm import LiteLlm
+    agent_openai = Agent(model=LiteLlm(model="openai/gpt-4o"), ...)
+    agent_claude = Agent(model=LiteLlm(model="anthropic/claude-3-haiku-20240307"), ...)
+    ```
+
+### 6.3 Open & Local Models via LiteLLM (Ollama, vLLM)
+
+For self-hosting, cost savings, privacy, or offline use.
+
+*   **Ollama Integration**: Run Ollama locally (`ollama run <model>`).
+    ```bash
+    export OLLAMA_API_BASE="http://localhost:11434" # Ensure Ollama server is running
+    ```
+    ```python
+    from google.adk.models.lite_llm import LiteLlm
+    # Use 'ollama_chat' provider for tool-calling capabilities with Ollama models
+    agent_ollama = Agent(model=LiteLlm(model="ollama_chat/llama3:instruct"), ...)
+    ```
+
+*   **Self-Hosted Endpoint (e.g., vLLM)**:
+    ```python
+    from google.adk.models.lite_llm import LiteLlm
+    api_base_url = "https://your-vllm-endpoint.example.com/v1"
+    agent_vllm = Agent(
+        model=LiteLlm(
+            model="your-model-name-on-vllm",
+            api_base=api_base_url,
+            extra_headers={"Authorization": "Bearer YOUR_TOKEN"},
+        ),
+        ...
+    )
+    ```
+
+### 6.4 Customizing LLM API Clients
+
+For `google-genai` (used by Gemini models), you can configure the underlying client.
+
+```python
+import os
+from google.genai import configure as genai_configure
+
+genai_configure.use_defaults(
+    timeout=60, # seconds
+    client_options={"api_key": os.getenv("GOOGLE_API_KEY")},
+)
+```
+
+---
+
+## 7. Tools: The Agent's Capabilities
+
+Tools extend an agent's abilities beyond text generation.
+
+### 7.1 Defining Function Tools: Principles & Best Practices
+
+*   **Signature**: `def my_tool(param1: Type, param2: Type, tool_context: ToolContext) -> dict:`
+*   **Function Name**: Descriptive verb-noun (e.g., `schedule_meeting`).
+*   **Parameters**: Clear names, required type hints, **NO DEFAULT VALUES**.
+*   **Return Type**: **Must** be a `dict` (JSON-serializable), preferably with a `'status'` key.
+*   **Docstring**: **CRITICAL**. Explain purpose, when to use, arguments, and return value structure. **AVOID** mentioning `tool_context`.
+
+    ```python
+    def calculate_compound_interest(
+        principal: float,
+        rate: float,
+        years: int,
+        compounding_frequency: int,
+        tool_context: ToolContext
+    ) -> dict:
+        """Calculates the future value of an investment with compound interest.
+
+        Use this tool to calculate the future value of an investment given a
+        principal amount, interest rate, number of years, and how often the
+        interest is compounded per year.
+
+        Args:
+            principal (float): The initial amount of money invested.
+            rate (float): The annual interest rate (e.g., 0.05 for 5%).
+            years (int): The number of years the money is invested.
+            compounding_frequency (int): The number of times interest is compounded
+                                         per year (e.g., 1 for annually, 12 for monthly).
+            
+        Returns:
+            dict: Contains the calculation result.
+                  - 'status' (str): "success" or "error".
+                  - 'future_value' (float, optional): The calculated future value.
+                  - 'error_message' (str, optional): Description of error, if any.
+        """
+        # ... implementation ...
+    ```
+
+### 7.2 The `ToolContext` Object: Accessing Runtime Information
+
+`ToolContext` is the gateway for tools to interact with the ADK runtime.
+
+*   `tool_context.state`: Read and write to the current `Session`'s `state` dictionary.
+*   `tool_context.actions`: Modify the `EventActions` object (e.g., `tool_context.actions.escalate = True`).
+*   `tool_context.load_artifact(filename)` / `tool_context.save_artifact(filename, part)`: Manage binary data.
+*   `tool_context.search_memory(query)`: Query the long-term `MemoryService`.
+
+### 7.3 All Tool Types & Their Usage
+
+1.  **Custom Function Tools**:
+    *   **`FunctionTool`**: The most common type, wrapping a standard Python function.
+    *   **`LongRunningFunctionTool`**: Wraps an `async` function that `yields` intermediate results, for tasks that provide progress updates.
+    *   **`AgentTool`**: Wraps another `BaseAgent` instance, allowing it to be invoked as a tool by a parent agent.
+
+2.  **Built-in Tools**: Ready-to-use tools provided by ADK.
+    *   `google_search`: Provides Google Search grounding.
+    *   **Code Execution**:
+        *   `BuiltInCodeExecutor`: Local, convenient for development. **Not** for untrusted production use.
+        *   `GkeCodeExecutor`: Production-grade. Executes code in ephemeral, sandboxed pods on Google Kubernetes Engine (GKE) using gVisor for isolation. Requires GKE cluster setup.
+    *   `VertexAiSearchTool`: Provides grounding from your private Vertex AI Search data stores.
+    *   `BigQueryToolset`: A collection of tools for interacting with BigQuery (e.g., `list_datasets`, `execute_sql`).
+    > **Warning**: An agent can only use one type of built-in tool at a time and they cannot be used in sub-agents.
+
+3.  **Third-Party Tool Wrappers**: For seamless integration with other frameworks.
+    *   `LangchainTool`: Wraps a tool from the LangChain ecosystem.
+
+4.  **OpenAPI & Protocol Tools**: For interacting with APIs and services.
+    *   **`OpenAPIToolset`**: Automatically generates a set of `RestApiTool`s from an OpenAPI (Swagger) v3 specification.
+    *   **`MCPToolset`**: Connects to an external Model Context Protocol (MCP) server to dynamically load its tools.
+
+5.  **Google Cloud Tools**: For deep integration with Google Cloud services.
+    *   **`ApiHubToolset`**: Turns any documented API from Apigee API Hub into a tool.
+    *   **`ApplicationIntegrationToolset`**: Turns Application Integration workflows and Integration Connectors (e.g., Salesforce, SAP) into callable tools.
+    *   **Toolbox for Databases**: An open-source MCP server that ADK can connect to for database interactions.
+
+6.  **Dynamic Toolsets (`BaseToolset`)**: Instead of a static list of tools, use a `Toolset` to dynamically determine which tools an agent can use based on the current context (e.g., user permissions).
+    ```python
+    from google.adk.tools.base_toolset import BaseToolset
+
+    class AdminAwareToolset(BaseToolset):
+        async def get_tools(self, context: ReadonlyContext) -> list[BaseTool]:
+            # Check state to see if user is admin
+            if context.state.get('user:role') == 'admin':
+                 return [admin_delete_tool, standard_query_tool]
+            return [standard_query_tool]
+
+    # Usage:
+    agent = Agent(tools=[AdminAwareToolset()])
+    ```
+
+### 7.4 Tool Confirmation (Human-in-the-Loop)
+ADK can pause tool execution to request human or system confirmation before proceeding, essential for sensitive actions.
+
+*   **Boolean Confirmation**: Simple yes/no via `FunctionTool(..., require_confirmation=True)`.
+*   **Dynamic Confirmation**: Pass a function to `require_confirmation` to decide at runtime based on arguments.
+*   **Advanced/Payload Confirmation**: Use `tool_context.request_confirmation()` inside the tool for structured feedback.
+
+```python
+from google.adk.tools import FunctionTool, ToolContext
+
+# 1. Simple Boolean Confirmation
+# Pauses execution until a 'confirmed': True/False event is received.
+sensitive_tool = FunctionTool(delete_database, require_confirmation=True)
+
+# 2. Dynamic Threshold Confirmation
+def needs_approval(amount: float, **kwargs) -> bool:
+    return amount > 10000
+
+transfer_tool = FunctionTool(wire_money, require_confirmation=needs_approval)
+
+# 3. Advanced Payload Confirmation (inside tool definition)
+def book_flight(destination: str, price: float, tool_context: ToolContext):
+    # Pause and ask user to select a seat class before continuing
+    tool_context.request_confirmation(
+        hint="Please confirm booking and select seat class.",
+        payload={"seat_class": ["economy", "business", "first"]} # Expected structure
+    )
+    return {"status": "pending_confirmation"}
+```
+
+---
+
+## 8. Context, State, and Memory Management
+
+Effective context management is crucial for coherent, multi-turn conversations.
+
+### 8.1 The `Session` Object & `SessionService`
+
+*   **`Session`**: The container for a single, ongoing conversation (`id`, `state`, `events`).
+*   **`SessionService`**: Manages the lifecycle of `Session` objects (`create_session`, `get_session`, `append_event`).
+*   **Implementations**: `InMemorySessionService` (dev), `VertexAiSessionService` (prod), `DatabaseSessionService` (self-managed).
+
+### 8.2 `State`: The Conversational Scratchpad
+
+A mutable dictionary within `session.state` for short-term, dynamic data.
+
+*   **Update Mechanism**: Always update via `context.state` (in callbacks/tools) or `LlmAgent.output_key`.
+*   **Prefixes for Scope**:
+    *   **(No prefix)**: Session-specific (e.g., `session.state['booking_step']`).
+    *   `user:`: Persistent for a `user_id` across all their sessions (e.g., `session.state['user:preferred_currency']`).
+    *   `app:`: Persistent for `app_name` across all users and sessions.
+    *   `temp:`: Ephemeral state that only exists for the current **invocation** (one user request -> final agent response cycle). It is discarded afterwards.
+
+### 8.3 `Memory`: Long-Term Knowledge & Retrieval
+
+For knowledge beyond a single conversation.
+
+*   **`BaseMemoryService`**: Defines the interface (`add_session_to_memory`, `search_memory`).
+*   **Implementations**: `InMemoryMemoryService`, `VertexAiRagMemoryService`.
+*   **Usage**: Agents interact via tools (e.g., the built-in `load_memory` tool).
+
+### 8.4 `Artifacts`: Binary Data Management
+
+For named, versioned binary data (files, images).
+
+*   **Representation**: `google.genai.types.Part` (containing a `Blob` with `data: bytes` and `mime_type: str`).
+*   **`BaseArtifactService`**: Manages storage (`save_artifact`, `load_artifact`).
+*   **Implementations**: `InMemoryArtifactService`, `GcsArtifactService`.
+
+---
+
+## 9. Runtime, Events, and Execution Flow
+
+The `Runner` is the central orchestrator of an ADK application.
+
+### 9.1 Runtime Configuration (`RunConfig`)
+Passed to `run` or `run_live` to control execution limits and output formats.
+
+```python
+from google.adk.agents.run_config import RunConfig
+from google.genai import types
+
+config = RunConfig(
+    # Safety limits
+    max_llm_calls=100,  # Prevent infinite agent loops
+    
+    # Streaming & Modality
+    response_modalities=["AUDIO", "TEXT"], # Request specific output formats
+    
+    # Voice configuration (for AUDIO modality)
+    speech_config=types.SpeechConfig(
+        voice_config=types.VoiceConfig(
+            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
+        )
+    ),
+    
+    # Debugging
+    save_input_blobs_as_artifacts=True # Save uploaded files to ArtifactService
+)
+```
+
+### 9.2 The `Runner`: The Orchestrator
+
+*   **Role**: Manages the agent's lifecycle, the event loop, and coordinates with services.
+*   **Entry Point**: `runner.run_async(user_id, session_id, new_message)`.
+
+### 9.3 The Event Loop: Core Execution Flow
+
+1.  User input becomes a `user` `Event`.
+2.  `Runner` calls `agent.run_async(invocation_context)`.
+3.  Agent `yield`s an `Event` (e.g., tool call, text response). Execution pauses.
+4.  `Runner` processes the `Event` (applies state changes, etc.) and yields it to the client.
+5.  Execution resumes. This cycle repeats until the agent is done.
+
+### 9.4 `Event` Object: The Communication Backbone
+
+`Event` objects carry all information and signals.
+
+*   `Event.author`: Source of the event (`'user'`, agent name, `'system'`).
+*   `Event.content`: The primary payload (text, function calls, function responses).
+*   `Event.actions`: Signals side effects (`state_delta`, `transfer_to_agent`, `escalate`).
+*   `Event.is_final_response()`: Helper to identify the complete, displayable message.
+
+### 9.5 Asynchronous Programming (Python Specific)
+
+ADK is built on `asyncio`. Use `async def`, `await`, and `async for` for all I/O-bound operations.
+
+---
+
+## 10. Control Flow with Callbacks
+
+Callbacks are functions that intercept and control agent execution at specific points.
+
+### 10.1 Callback Mechanism: Interception & Control
+
+*   **Definition**: A Python function assigned to an agent's `callback` parameter (e.g., `after_agent_callback=my_func`).
+*   **Context**: Receives a `CallbackContext` (or `ToolContext`) with runtime info.
+*   **Return Value**: **Crucially determines flow.**
+    *   `return None`: Allow the default action to proceed.
+    *   `return <Specific Object>`: **Override** the default action/result.
+
+### 10.2 Types of Callbacks
+
+1.  **Agent Lifecycle**: `before_agent_callback`, `after_agent_callback`.
+2.  **LLM Interaction**: `before_model_callback`, `after_model_callback`.
+3.  **Tool Execution**: `before_tool_callback`, `after_tool_callback`.
+
+### 10.3 Callback Best Practices
+
+*   **Keep Focused**: Each callback for a single purpose.
+*   **Performance**: Avoid blocking I/O or heavy computation.
+*   **Error Handling**: Use `try...except` to prevent crashes.
+
+#### **Example 1: Data Aggregation with `after_agent_callback`**
+This callback runs after an agent, inspects the `session.events` to find structured data from tool calls (like `google_search` results), and saves it to state for later use.
+
+```python
+from google.adk.agents.callback_context import CallbackContext
+
+def collect_research_sources_callback(callback_context: CallbackContext) -> None:
+    """Collects and organizes web research sources from agent events."""
+    session = callback_context._invocation_context.session
+    # Get existing sources from state to append to them.
+    url_to_short_id = callback_context.state.get("url_to_short_id", {})
+    sources = callback_context.state.get("sources", {})
+    id_counter = len(url_to_short_id) + 1
+
+    # Iterate through all events in the session to find grounding metadata.
+    for event in session.events:
+        if not (event.grounding_metadata and event.grounding_metadata.grounding_chunks):
+            continue
+        # ... logic to parse grounding_chunks and grounding_supports ...
+        # (See full implementation in the original code snippet)
+
+    # Save the updated source map back to state.
+    callback_context.state["url_to_short_id"] = url_to_short_id
+    callback_context.state["sources"] = sources
+
+# Used in an agent like this:
+# section_researcher = LlmAgent(..., after_agent_callback=collect_research_sources_callback)
+```
+
+#### **Example 2: Output Transformation with `after_agent_callback`**
+This callback takes an LLM's raw output (containing custom tags), uses Python to format it into markdown, and returns the modified content, overriding the original.
+
+```python
+import re
+from google.adk.agents.callback_context import CallbackContext
+from google.genai import types as genai_types
+
+def citation_replacement_callback(callback_context: CallbackContext) -> genai_types.Content:
+    """Replaces <cite> tags in a report with Markdown-formatted links."""
+    # 1. Get raw report and sources from state.
+    final_report = callback_context.state.get("final_cited_report", "")
+    sources = callback_context.state.get("sources", {})
+
+    # 2. Define a replacer function for regex substitution.
+    def tag_replacer(match: re.Match) -> str:
+        short_id = match.group(1)
+        if not (source_info := sources.get(short_id)):
+            return "" # Remove invalid tags
+        title = source_info.get("title", short_id)
+        return f" [{title}]({source_info['url']})"
+
+    # 3. Use regex to find all <cite> tags and replace them.
+    processed_report = re.sub(
+        r'<cite\s+source\s*=\s*["\']?(src-\d+)["\']?\s*/>',
+        tag_replacer,
+        final_report,
+    )
+    processed_report = re.sub(r"\s+([.,;:])", r"\1", processed_report) # Fix spacing
+
+    # 4. Save the new version to state and return it to override the original agent output.
+    callback_context.state["final_report_with_citations"] = processed_report
+    return genai_types.Content(parts=[genai_types.Part(text=processed_report)])
+
+# Used in an agent like this:
+# report_composer = LlmAgent(..., after_agent_callback=citation_replacement_callback)
+```
+
+### 10.A. Global Control with Plugins
+
+Plugins are stateful, reusable modules for implementing cross-cutting concerns that apply globally to all agents, tools, and model calls managed by a `Runner`. Unlike Callbacks which are configured per-agent, Plugins are registered once on the `Runner`.
+
+*   **Use Cases**: Ideal for universal logging, application-wide policy enforcement, global caching, and collecting metrics.
+*   **Execution Order**: Plugin callbacks run **before** their corresponding agent-level callbacks. If a plugin callback returns a value, the agent-level callback is skipped.
+*   **Defining a Plugin**: Inherit from `BasePlugin` and implement callback methods.
+    ```python
+    from google.adk.plugins import BasePlugin
+    from google.adk.agents.callback_context import CallbackContext
+    from google.adk.models.llm_request import LlmRequest
+
+    class AuditLoggingPlugin(BasePlugin):
+        def __init__(self):
+            super().__init__(name="audit_logger")
+
+        async def before_model_callback(self, callback_context: CallbackContext, llm_request: LlmRequest):
+            # Log every prompt sent to any LLM
+            print(f"[AUDIT] Agent {callback_context.agent_name} calling LLM with: {llm_request.contents[-1]}")
+
+        async def on_tool_error_callback(self, tool, error, **kwargs):
+            # Global error handler for all tools
+            print(f"[ALERT] Tool {tool.name} failed: {error}")
+            # Optionally return a dict to suppress the exception and provide fallback
+            return {"status": "error", "message": "An internal error occurred, handled by plugin."}
+    ```
+*   **Registering a Plugin**:
+    ```python
+    from google.adk.runners import Runner
+    # runner = Runner(agent=root_agent, ..., plugins=[AuditLoggingPlugin()])
+    ```
+*   **Error Handling Callbacks**: Plugins support unique error hooks like `on_model_error_callback` and `on_tool_error_callback` for centralized error management.
+*   **Limitation**: Plugins are not supported by the `adk web` interface.
+
+---
+
+## 11. Authentication for Tools
+
+Enabling agents to securely access protected external resources.
+
+### 11.1 Core Concepts: `AuthScheme` & `AuthCredential`
+
+*   **`AuthScheme`**: Defines *how* an API expects authentication (e.g., `APIKey`, `HTTPBearer`, `OAuth2`, `OpenIdConnectWithConfig`).
+*   **`AuthCredential`**: Holds *initial* information to *start* the auth process (e.g., API key value, OAuth client ID/secret).
+
+### 11.2 Interactive OAuth/OIDC Flows
+
+When a tool requires user interaction (OAuth consent), ADK pauses and signals your `Agent Client` application.
+
+1.  **Detect Auth Request**: `runner.run_async()` yields an event with a special `adk_request_credential` function call.
+2.  **Redirect User**: Extract `auth_uri` from `auth_config` in the event. Your client app redirects the user's browser to this `auth_uri` (appending `redirect_uri`).
+3.  **Handle Callback**: Your client app has a pre-registered `redirect_uri` to receive the user after authorization. It captures the full callback URL (containing `authorization_code`).
+4.  **Send Auth Result to ADK**: Your client prepares a `FunctionResponse` for `adk_request_credential`, setting `auth_config.exchanged_auth_credential.oauth2.auth_response_uri` to the captured callback URL.
+5.  **Resume Execution**: `runner.run_async()` is called again with this `FunctionResponse`. ADK performs the token exchange, stores the access token, and retries the original tool call.
+
+### 11.3 Custom Tool Authentication
+
+If building a `FunctionTool` that needs authentication:
+
+1.  **Check for Cached Creds**: `tool_context.state.get("my_token_cache_key")`.
+2.  **Check for Auth Response**: `tool_context.get_auth_response(my_auth_config)`.
+3.  **Initiate Auth**: If no creds, call `tool_context.request_credential(my_auth_config)` and return a pending status. This triggers the external flow.
+4.  **Cache Credentials**: After obtaining, store in `tool_context.state`.
+5.  **Make API Call**: Use the valid credentials (e.g., `google.oauth2.credentials.Credentials`).
+
+---
+
+## 12. Deployment Strategies
+
+From local dev to production.
+
+### 12.1 Local Development & Testing (`adk web`, `adk run`, `adk api_server`)
+
+*   **`adk web`**: Launches a local web UI for interactive chat, session inspection, and visual tracing.
+    ```bash
+    adk web /path/to/your/project_root
+    ```
+*   **`adk run`**: Command-line interactive chat.
+    ```bash
+    adk run /path/to/your/agent_folder
+    ```
+*   **`adk api_server`**: Launches a local FastAPI server exposing `/run`, `/run_sse`, `/list-apps`, etc., for API testing with `curl` or client libraries.
+    ```bash
+    adk api_server /path/to/your/project_root
+    ```
+
+### 12.2 Vertex AI Agent Engine
+
+Fully managed, scalable service for ADK agents on Google Cloud.
+
+*   **Features**: Auto-scaling, session management, observability integration.
+*   **ADK CLI**: `adk deploy agent_engine --project <id> --region <loc> ... /path/to/agent`
+*   **Deployment**: Use `vertexai.agent_engines.create()`.
+    ```python
+    from vertexai.preview import reasoning_engines # or agent_engines directly in later versions
+    
+    # Wrap your root_agent for deployment
+    app_for_engine = reasoning_engines.AdkApp(agent=root_agent, enable_tracing=True)
+    
+    # Deploy
+    remote_app = agent_engines.create(
+        agent_engine=app_for_engine,
+        requirements=["google-cloud-aiplatform[adk,agent_engines]"],
+        display_name="My Production Agent"
+    )
+    print(remote_app.resource_name) # projects/PROJECT_NUM/locations/REGION/reasoningEngines/ID
+    ```
+*   **Interaction**: Use `remote_app.stream_query()`, `create_session()`, etc.
+
+### 12.3 Cloud Run
+
+Serverless container platform for custom web applications.
+
+*   **ADK CLI**: `adk deploy cloud_run --project <id> --region <loc> ... /path/to/agent`
+*   **Deployment**:
+    1.  Create a `Dockerfile` for your FastAPI app (using `google.adk.cli.fast_api.get_fast_api_app`).
+    2.  Use `gcloud run deploy --source .`.
+    3.  Alternatively, `adk deploy cloud_run` (simpler, opinionated).
+*   **Example `main.py`**:
+    ```python
+    import os
+    from fastapi import FastAPI
+    from google.adk.cli.fast_api import get_fast_api_app
+
+    # Ensure your agent_folder (e.g., 'my_first_agent') is in the same directory as main.py
+    app: FastAPI = get_fast_api_app(
+        agents_dir=os.path.dirname(os.path.abspath(__file__)),
+        session_service_uri="sqlite:///./sessions.db", # In-container SQLite, for simple cases
+        # For production: use a persistent DB (Cloud SQL) or VertexAiSessionService
+        allow_origins=["*"],
+        web=True # Serve ADK UI
+    )
+    # uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080))) # If running directly
+    ```
+
+### 12.4 Google Kubernetes Engine (GKE)
+
+For maximum control, run your containerized agent in a Kubernetes cluster.
+
+*   **ADK CLI**: `adk deploy gke --project <id> --cluster_name <name> ... /path/to/agent`
+*   **Deployment**:
+    1.  Build Docker image (`gcloud builds submit`).
+    2.  Create Kubernetes Deployment and Service YAMLs.
+    3.  Apply with `kubectl apply -f deployment.yaml`.
+    4.  Configure Workload Identity for GCP permissions.
+
+### 12.5 CI/CD Integration
+
+*   Automate testing (`pytest`, `adk eval`) in CI.
+*   Automate container builds and deployments (e.g., Cloud Build, GitHub Actions).
+*   Use environment variables for secrets.
+
+---
+
+## 13. Evaluation and Safety
+
+Critical for robust, production-ready agents.
+
+### 13.1 Agent Evaluation (`adk eval`)
+
+Systematically assess agent performance using predefined test cases.
+
+*   **Evalset File (`.evalset.json`)**: Contains `eval_cases`, each with a `conversation` (user queries, expected tool calls, expected intermediate/final responses) and `session_input` (initial state).
+    ```json
+    {
+      "eval_set_id": "weather_bot_eval",
+      "eval_cases": [
+        {
+          "eval_id": "london_weather_query",
+          "conversation": [
+            {
+              "user_content": {"parts": [{"text": "What's the weather in London?"}]},
+              "final_response": {"parts": [{"text": "The weather in London is cloudy..."}]},
+              "intermediate_data": {
+                "tool_uses": [{"name": "get_weather", "args": {"city": "London"}}]
+              }
+            }
+          ],
+          "session_input": {"app_name": "weather_app", "user_id": "test_user", "state": {}}
+        }
+      ]
+    }
+    ```
+*   **Running Evaluation**:
+    *   `adk web`: Interactive UI for creating/running eval cases.
+    *   `adk eval /path/to/agent_folder /path/to/evalset.json`: CLI execution.
+    *   `pytest`: Integrate `AgentEvaluator.evaluate()` into unit/integration tests.
+*   **Metrics**: `tool_trajectory_avg_score` (tool calls match expected), `response_match_score` (final response similarity using ROUGE). Configurable via `test_config.json`.
+
+### 13.2 Safety & Guardrails
+
+Multi-layered defense against harmful content, misalignment, and unsafe actions.
+
+1.  **Identity and Authorization**:
+    *   **Agent-Auth**: Tool acts with the agent's service account (e.g., `Vertex AI User` role). Simple, but all users share access level. Logs needed for attribution.
+    *   **User-Auth**: Tool acts with the end-user's identity (via OAuth tokens). Reduces risk of abuse.
+2.  **In-Tool Guardrails**: Design tools defensively. Tools can read policies from `tool_context.state` (set deterministically by developer) and validate model-provided arguments before execution.
+    ```python
+    def execute_sql(query: str, tool_context: ToolContext) -> dict:
+        policy = tool_context.state.get("user:sql_policy", {})
+        if not policy.get("allow_writes", False) and ("INSERT" in query.upper() or "DELETE" in query.upper()):
+            return {"status": "error", "message": "Policy: Write operations are not allowed."}
+        # ... execute query ...
+    ```
+3.  **Built-in Gemini Safety Features**:
+    *   **Content Safety Filters**: Automatically block harmful content (CSAM, PII, hate speech, etc.). Configurable thresholds.
+    *   **System Instructions**: Guide model behavior, define prohibited topics, brand tone, disclaimers.
+4.  **Model and Tool Callbacks (LLM as a Guardrail)**: Use callbacks to inspect inputs/outputs.
+    *   `before_model_callback`: Intercept `LlmRequest` before it hits the LLM. Block (return `LlmResponse`) or modify.
+    *   `before_tool_callback`: Intercept tool calls (name, args) before execution. Block (return `dict`) or modify.
+    *   **LLM-based Safety**: Use a cheap/fast LLM (e.g., Gemini Flash) in a callback to classify input/output safety.
+        ```python
+        def safety_checker_callback(context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]:
+            # Use a separate, small LLM to classify safety
+            safety_llm_agent = Agent(name="SafetyChecker", model="gemini-2.5-flash-001", instruction="Classify input as 'safe' or 'unsafe'. Output ONLY the word.")
+            # Run the safety agent (might need a new runner instance or direct model call)
+            # For simplicity, a mock:
+            user_input = llm_request.contents[-1].parts[0].text
+            if "dangerous_phrase" in user_input.lower():
+                context.state["safety_violation"] = True
+                return LlmResponse(content=genai_types.Content(parts=[genai_types.Part(text="I cannot process this request due to safety concerns.")]))
+            return None
+        ```
+5.  **Sandboxed Code Execution**:
+    *   `BuiltInCodeExecutor`: Uses secure, sandboxed execution environments.
+    *   Vertex AI Code Interpreter Extension.
+    *   If custom, ensure hermetic environments (no network, isolated).
+6.  **Network Controls & VPC-SC**: Confine agent activity within secure perimeters (VPC Service Controls) to prevent data exfiltration.
+7.  **Output Escaping in UIs**: Always properly escape LLM-generated content in web UIs to prevent XSS attacks and indirect prompt injections.
+
+**Grounding**: A key safety and reliability feature that connects agent responses to verifiable information.
+*   **Mechanism**: Uses tools like `google_search` or `VertexAiSearchTool` to fetch real-time or private data.
+*   **Benefit**: Reduces model hallucination by basing responses on retrieved facts.
+*   **Requirement**: When using `google_search`, your application UI **must** display the provided search suggestions and citations to comply with terms of service.
+
+---
+
+## 14. Debugging, Logging & Observability
+
+*   **`adk web` UI**: Best first step. Provides visual trace, session history, and state inspection.
+*   **Event Stream Logging**: Iterate `runner.run_async()` events and print relevant fields.
+    ```python
+    async for event in runner.run_async(...):
+        print(f"[{event.author}] Event ID: {event.id}, Invocation: {event.invocation_id}")
+        if event.content and event.content.parts:
+            if event.content.parts[0].text:
+                print(f"  Text: {event.content.parts[0].text[:100]}...")
+            if event.get_function_calls():
+                print(f"  Tool Call: {event.get_function_calls()[0].name} with {event.get_function_calls()[0].args}")
+            if event.get_function_responses():
+                print(f"  Tool Response: {event.get_function_responses()[0].response}")
+        if event.actions:
+            if event.actions.state_delta:
+                print(f"  State Delta: {event.actions.state_delta}")
+            if event.actions.transfer_to_agent:
+                print(f"  TRANSFER TO: {event.actions.transfer_to_agent}")
+        if event.error_message:
+            print(f"  ERROR: {event.error_message}")
+    ```
+*   **Tool/Callback `print` statements**: Simple logging directly within your functions.
+*   **Logging**: Use Python's standard `logging` module. Control verbosity with `adk web --log_level DEBUG` or `adk web -v`.
+*   **One-Line Observability Integrations**: ADK has native hooks for popular tracing platforms.
+    *   **AgentOps**:
+        ```python
+        import agentops
+        agentops.init(api_key="...") # Automatically instruments ADK agents
+        ```
+    *   **Arize Phoenix**:
+        ```python
+        from phoenix.otel import register
+        register(project_name="my_agent", auto_instrument=True)
+        ```
+    *   **Google Cloud Trace**: Enable via flag during deployment: `adk deploy [cloud_run|agent_engine] --trace_to_cloud ...`
+*   **Session History (`session.events`)**: Persisted for detailed post-mortem analysis.
+
+---
+
+## 15. Streaming & Advanced I/O
+
+ADK supports real-time, bidirectional communication for interactive experiences like live voice conversations.
+
+#### Bidirectional Streaming Loop (`run_live`)
+For real-time voice/video, use `run_live` with a `LiveRequestQueue`. This enables low-latency, two-way communication where the user can interrupt the agent.
+
+```python
+import asyncio
+from google.adk.agents import LiveRequestQueue
+from google.adk.agents.run_config import RunConfig
+
+async def start_streaming_session(runner, session, user_id):
+    # 1. Configure modalities (e.g., AUDIO output for voice agents)
+    run_config = RunConfig(response_modalities=["AUDIO"])
+    
+    # 2. Create input queue for client data (audio chunks, text)
+    live_queue = LiveRequestQueue()
+
+    # 3. Start the bidirectional stream
+    live_events = runner.run_live(
+        session=session,
+        live_request_queue=live_queue,
+        run_config=run_config
+    )
+
+    # 4. Process events (simplified loop)
+    try:
+        async for event in live_events:
+            # Handle agent output (text or audio bytes)
+            if event.content and event.content.parts:
+                part = event.content.parts[0]
+                if part.inline_data and part.inline_data.mime_type.startswith("audio/"):
+                    # Send audio bytes to client
+                    await client.send_audio(part.inline_data.data)
+                elif part.text:
+                     # Send text to client
+                     await client.send_text(part.text)
+            
+            # Handle turn signals
+            if event.turn_complete:
+                 pass # Signal client that agent finished speaking
+    finally:
+        live_queue.close()
+
+# To send user input to agent during the stream:
+# await live_queue.send_content(Content(role="user", parts=[Part(text="Hello")]))
+# await live_queue.send_realtime(Blob(mime_type="audio/pcm", data=audio_bytes))
+```
+
+*   **Streaming Tools**: A special type of `FunctionTool` that can stream intermediate results back to the agent.
+    *   **Definition**: Must be an `async` function with a return type of `AsyncGenerator`.
+        ```python
+        from typing import AsyncGenerator
+
+        async def monitor_stock_price(symbol: str) -> AsyncGenerator[str, None]:
+            """Yields stock price updates as they occur."""
+            while True:
+                price = await get_live_price(symbol)
+                yield f"Update for {symbol}: ${price}"
+                await asyncio.sleep(5)
+        ```
+
+*   **Advanced I/O Modalities**: ADK (especially with Gemini Live API models) supports richer interactions.
+    *   **Audio**: Input via `Blob(mime_type="audio/pcm", data=bytes)`, Output via `genai_types.SpeechConfig` in `RunConfig`.
+    *   **Vision (Images/Video)**: Input via `Blob(mime_type="image/jpeg", data=bytes)` or `Blob(mime_type="video/mp4", data=bytes)`. Models like `gemini-2.5-flash-exp` can process these.
+    *   **Multimodal Input in `Content`**:
+        ```python
+        multimodal_content = genai_types.Content(
+            parts=[
+                genai_types.Part(text="Describe this image:"),
+                genai_types.Part(inline_data=genai_types.Blob(mime_type="image/jpeg", data=image_bytes))
+            ]
+        )
+        ```
+
+---
+
+## 16. Performance Optimization
+
+*   **Model Selection**: Choose the smallest model that meets requirements (e.g., `gemini-2.5-flash` for simple tasks).
+*   **Instruction Prompt Engineering**: Concise, clear instructions reduce tokens and improve accuracy.
+*   **Tool Use Optimization**:
+    *   Design efficient tools (fast API calls, optimize database queries).
+    *   Cache tool results (e.g., using `before_tool_callback` or `tool_context.state`).
+*   **State Management**: Store only necessary data in state to avoid large context windows.
+*   **`include_contents='none'`**: For stateless utility agents, saves LLM context window.
+*   **Parallelization**: Use `ParallelAgent` for independent tasks.
+*   **Streaming**: Use `StreamingMode.SSE` or `BIDI` for perceived latency reduction.
+*   **`max_llm_calls`**: Limit LLM calls to prevent runaway agents and control costs.
+
+---
+
+## 17. General Best Practices & Common Pitfalls
+
+*   **Start Simple**: Begin with `LlmAgent`, mock tools, and `InMemorySessionService`. Gradually add complexity.
+*   **Iterative Development**: Build small features, test, debug, refine.
+*   **Modular Design**: Use agents and tools to encapsulate logic.
+*   **Clear Naming**: Descriptive names for agents, tools, state keys.
+*   **Error Handling**: Implement robust `try...except` blocks in tools and callbacks. Guide LLMs on how to handle tool errors.
+*   **Testing**: Write unit tests for tools/callbacks, integration tests for agent flows (`pytest`, `adk eval`).
+*   **Dependency Management**: Use virtual environments (`venv`) and `requirements.txt`.
+*   **Secrets Management**: Never hardcode API keys. Use `.env` for local dev, environment variables or secret managers (Google Cloud Secret Manager) for production.
+*   **Avoid Infinite Loops**: Especially with `LoopAgent` or complex LLM tool-calling chains. Use `max_iterations`, `max_llm_calls`, and strong instructions.
+*   **Handle `None` & `Optional`**: Always check for `None` or `Optional` values when accessing nested properties (e.g., `event.content and event.content.parts and event.content.parts[0].text`).
+*   **Immutability of Events**: Events are immutable records. If you need to change something *before* it's processed, do so in a `before_*` callback and return a *new* modified object.
+*   **Understand `output_key` vs. direct `state` writes**: `output_key` is for the agent's *final conversational* output. Direct `tool_context.state['key'] = value` is for *any other* data you want to save.
+*   **Example Agents**: Find practical examples and reference implementations in the [ADK Samples repository](https://github.com/google/adk-samples).
+
+
+### Testing the output of an agent
+
+The following script demonstrates how to programmatically test an agent's output. This approach is extremely useful when an LLM or coding agent needs to interact with a work-in-progress agent, as well as for automated testing, debugging, or when you need to integrate agent execution into other workflows:
+```python
+import asyncio
+
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from rag_agent.agent import root_agent
+from google.genai import types as genai_types
+
+
+async def main():
+    """Runs the agent with a sample query."""
+    session_service = InMemorySessionService()
+    await session_service.create_session(
+        app_name="rag_agent", user_id="test_user", session_id="test_session"
+    )
+    runner = Runner(
+        agent=root_agent, app_name="rag_agent", session_service=session_service
+    )
+    query = "I want a recipe for pancakes"
+    async for event in runner.run_async(
+        user_id="test_user",
+        session_id="test_session",
+        new_message=genai_types.Content(
+            role="user", 
+            parts=[genai_types.Part.from_text(text=query)]
+        ),
+    ):
+        if event.is_final_response():
+            print(event.content.parts[0].text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 18. Official API & CLI References
+
+For detailed specifications of all classes, methods, and commands, refer to the official reference documentation.
+
+*   [Python API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/python)
+*   [Java API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/java)
+*   [CLI Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/cli)
+*   [REST API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/rest)
+*   [Agent Config YAML Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/agentconfig)
+
+---
+**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: `asia-southeast1`).
+
+**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 asia-southeast1 \
+  --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 asia-southeast1 \
+  --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: `asia-southeast1`).
+*   `--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.

GRADIO_COMPLETE_SETUP.md

@@ -0,0 +1,300 @@
+# 🎉 Gradio Chat UI - Complete Setup
+
+## ✅ What Was Created
+
+Your Gradio chat interface is now ready! Here's everything that was added to your project:
+
+### 🎨 Main Applications
+1. **`gradio_app.py`** - Simple version using AgentEngine directly
+2. **`gradio_app_v2.py`** ⭐ - **Recommended** version with full features
+3. **`run_gradio.py`** - Quick launcher script
+
+### 📚 Documentation
+4. **`GRADIO_README.md`** - Complete feature documentation
+5. **`QUICKSTART_GRADIO.md`** - Step-by-step setup guide
+6. **`GRADIO_SUMMARY.md`** - Project overview and architecture
+7. **`VERSIONS_COMPARISON.md`** - Comparison of both app versions
+
+### 🛠️ Utilities
+8. **`setup_gradio.sh`** - Automated setup script
+9. **`test_gradio_setup.py`** - Configuration verification tool
+
+### 📦 Updated
+10. **`requirements.txt`** - Added Gradio and python-dotenv
+
+---
+
+## 🚀 Get Started in 3 Steps
+
+### Step 1: Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Step 2: Authenticate
+```bash
+gcloud auth application-default login
+```
+
+### Step 3: Run the App
+```bash
+python gradio_app_v2.py
+```
+
+**Open your browser to: http://localhost:7860**
+
+---
+
+## 🎯 What You Can Do
+
+Your Gradio chat UI provides:
+
+### 🤖 Agent Selection
+- **Automatic Discovery**: Lists all agents from Agent Engine
+- **Dropdown Selection**: Easy agent switching
+- **Refresh Button**: Update agent list on-the-fly
+
+### 💬 Chat Interface
+- **Real-time Conversation**: Chat with your RAG agent
+- **Chat History**: View full conversation
+- **Copy Buttons**: Copy responses easily
+- **Session Management**: Maintain context across queries
+
+### 📋 RAG Operations
+Your agents can:
+- **List Corpora** - "List all available corpora"
+- **Query Documents** - "What information do you have about X?"
+- **Create Corpus** - "Create a new corpus called 'docs'"
+- **Add Data** - "Add this file to the corpus: [URL]"
+- **Get Info** - "Show me details about the corpus"
+- **Delete** - "Delete the old-docs corpus"
+
+---
+
+## 📖 Quick Reference
+
+### Launch Commands
+```bash
+# Recommended way
+python gradio_app_v2.py
+
+# Alternative launcher
+python run_gradio.py
+
+# With setup script
+./setup_gradio.sh
+```
+
+### Test Your Setup
+```bash
+python test_gradio_setup.py
+```
+
+### Check Deployed Agents
+```bash
+gcloud agent-engines list --location=YOUR_LOCATION
+```
+
+---
+
+## 🎨 UI Features
+
+### Main Components
+- **Agent Dropdown** - Select which agent to chat with
+- **Session ID Input** - Maintain conversation context
+- **Refresh Button** - Update available agents
+- **Chat History** - View conversation with copy buttons
+- **Message Input** - Type and send messages
+- **Clear Button** - Clear chat history
+- **Examples Accordion** - View capabilities and examples
+
+### Visual Design
+- Modern, clean Gradio interface
+- Emoji indicators for status messages
+- Avatar support (🤖 for agent)
+- Responsive layout
+- Dark/light mode support (via browser)
+
+---
+
+## 📊 Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│         User's Web Browser                  │
+│         http://localhost:7860               │
+└─────────────┬───────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│         Gradio UI (Python)                  │
+│         gradio_app_v2.py                    │
+└─────────────┬───────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│    AgentEnginesServiceClient                │
+│    (Google Cloud AI Platform)               │
+└─────────────┬───────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│    Agent Engine (Cloud Service)             │
+│    Lists & Queries Deployed Agents          │
+└─────────────┬───────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│    Your RAG Agent                           │
+│    (Deployed with ADK)                      │
+└─────────────┬───────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│    Vertex AI RAG Service                    │
+│    Document Corpora & Embeddings            │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+Located in `rag_agent/.env`:
+```bash
+GOOGLE_CLOUD_PROJECT="your-project-id"
+GOOGLE_CLOUD_LOCATION="us-central1"
+GOOGLE_GENAI_USE_VERTEXAI="true"
+```
+
+### Customization Options
+Edit `gradio_app_v2.py` to modify:
+- **Port**: Change `server_port=7860`
+- **Theme**: Use `gr.themes.Glass()` or other themes
+- **Public URL**: Set `share=True`
+- **Authentication**: Add `auth=("user", "pass")`
+
+---
+
+## 🐛 Common Issues
+
+### "No agents found"
+**Cause**: No agents deployed  
+**Fix**: `make deploy`
+
+### Authentication error
+**Cause**: Not authenticated  
+**Fix**: `gcloud auth application-default login`
+
+### Module not found
+**Cause**: Dependencies not installed  
+**Fix**: `pip install -r requirements.txt`
+
+### Wrong location
+**Cause**: Location mismatch  
+**Fix**: Update `GOOGLE_CLOUD_LOCATION` in `.env`
+
+### Port already in use
+**Cause**: Port 7860 occupied  
+**Fix**: Change port in code or stop other process
+
+---
+
+## 📈 Next Steps
+
+### Immediate Actions
+1. ✅ Run `python test_gradio_setup.py` to verify setup
+2. ✅ Launch `python gradio_app_v2.py`
+3. ✅ Select an agent from the dropdown
+4. ✅ Start chatting!
+
+### Enhancements
+- 📤 **Add file upload** for document ingestion
+- 🎨 **Customize theme** to match your brand
+- 📊 **Add analytics** to track usage
+- 🔒 **Enable authentication** for production
+- 🌐 **Deploy to Cloud Run** for public access
+
+### Learning Resources
+- 📚 [Gradio Documentation](https://gradio.app/docs)
+- 🤖 [Vertex AI Agent Engine](https://cloud.google.com/agent-engine/docs)
+- 🔧 [Google ADK](https://github.com/google/genai-adk)
+
+---
+
+## 🎓 Example Conversations
+
+### Example 1: List Corpora
+```
+You: List all available corpora
+🤖: Here are the available corpora:
+    1. tech-docs
+    2. company-handbook
+    3. research-papers
+```
+
+### Example 2: Query Documents
+```
+You: What information do you have about machine learning?
+🤖: Based on the documents in the research-papers corpus,
+    machine learning is a subset of artificial intelligence...
+```
+
+### Example 3: Create Corpus
+```
+You: Create a new corpus called customer-feedback
+🤖: ✅ Successfully created the corpus 'customer-feedback'.
+    You can now add documents to it.
+```
+
+### Example 4: Add Data
+```
+You: Add this file to the corpus: https://drive.google.com/file/d/abc123
+🤖: ✅ Successfully added the document to the corpus.
+    The document is now being processed and will be
+    available for querying shortly.
+```
+
+---
+
+## 🌟 Features Highlight
+
+### For Users
+- ✨ No coding required - just chat!
+- 🔄 Switch between agents easily
+- 📝 Copy responses with one click
+- 💡 Examples built into the UI
+- 🎯 Session-based conversations
+
+### For Developers
+- 🛠️ Easy to customize and extend
+- 📦 Clean, modular code
+- 🔌 Simple integration with Agent Engine
+- 📊 Ready for analytics integration
+- 🚀 Deploy-ready
+
+---
+
+## 🎉 You're All Set!
+
+Your Gradio chat interface is ready to use! Here's your checklist:
+
+- ✅ Gradio app files created
+- ✅ Documentation provided
+- ✅ Setup scripts ready
+- ✅ Configuration verified
+- ✅ Examples included
+
+**Just run:** `python gradio_app_v2.py` and start chatting! 🚀
+
+---
+
+## 📞 Need Help?
+
+1. **Check Documentation**: Read the QUICKSTART_GRADIO.md
+2. **Test Setup**: Run `python test_gradio_setup.py`
+3. **Review Examples**: See GRADIO_README.md for examples
+4. **Compare Versions**: Check VERSIONS_COMPARISON.md
+
+**Happy Chatting with Your RAG Agent! 🤖💬**

GRADIO_README.md

@@ -0,0 +1,118 @@
+# Gradio Chat UI for RAG Agent
+
+This Gradio application provides a user-friendly chat interface to interact with your deployed RAG agents on Google Cloud Agent Engine.
+
+## Features
+
+- 🔍 **Agent Discovery**: Automatically lists all deployed agents from Agent Engine
+- 💬 **Interactive Chat**: Chat with any selected agent in real-time
+- 🔄 **Dynamic Updates**: Refresh agent list without restarting the app
+- 📝 **Chat History**: View full conversation history
+- 🎨 **Modern UI**: Clean and intuitive Gradio interface
+
+## Prerequisites
+
+1. Python 3.10 or higher
+2. Google Cloud Project with Agent Engine enabled
+3. Deployed RAG Agent(s) in Agent Engine
+4. Proper authentication set up (gcloud or service account)
+
+## Installation
+
+1. Install the required dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+2. Set up environment variables in `.env` file (in `rag_agent/` directory):
+```bash
+GOOGLE_CLOUD_PROJECT=your-project-id
+GOOGLE_CLOUD_LOCATION=us-central1  # or your preferred location
+```
+
+3. Authenticate with Google Cloud:
+```bash
+gcloud auth application-default login
+```
+
+## Running the App
+
+From the project root directory:
+
+```bash
+python gradio_app.py
+```
+
+The app will start on `http://localhost:7860`
+
+## Usage
+
+1. **Select an Agent**: Use the dropdown menu to choose from available agents
+2. **Refresh Agents**: Click the refresh button to update the agent list
+3. **Chat**: Type your message and press Send or Enter
+4. **Clear Chat**: Clear the conversation history with the Clear Chat button
+
+## Agent Capabilities
+
+The RAG Agent supports the following operations:
+
+- **Query Documents**: Ask questions and retrieve information from document corpora
+- **List Corpora**: View all available document collections
+- **Create Corpus**: Create new document collections
+- **Add Data**: Add documents (Google Drive URLs, GCS paths) to corpora
+- **Get Corpus Info**: View detailed information about a specific corpus
+- **Delete Document**: Remove specific documents from a corpus
+- **Delete Corpus**: Remove entire document collections
+
+## Example Queries
+
+```
+- "List all available corpora"
+- "What information do you have about [topic]?"
+- "Create a new corpus called 'my-documents'"
+- "Add this Google Drive file to the corpus: https://drive.google.com/..."
+- "Show me details about the 'my-documents' corpus"
+```
+
+## Troubleshooting
+
+### No agents found
+- Ensure you have deployed at least one agent to Agent Engine
+- Check that your `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` are correct
+- Verify you have proper permissions to list agents
+
+### Authentication errors
+- Run `gcloud auth application-default login`
+- Ensure your service account (if using one) has the necessary permissions
+
+### Connection errors
+- Verify your Agent Engine location matches `GOOGLE_CLOUD_LOCATION`
+- Check firewall settings if running in a restricted environment
+
+## Configuration
+
+You can customize the app by modifying `gradio_app.py`:
+
+- Change server port (default: 7860)
+- Modify UI theme
+- Adjust chat history height
+- Enable/disable share link
+
+## Deployment
+
+To make the app publicly accessible:
+
+```bash
+# Enable share link (creates temporary public URL)
+demo.launch(share=True)
+
+# Or deploy to Hugging Face Spaces
+# Follow: https://huggingface.co/docs/hub/spaces-sdks-gradio
+```
+
+## Support
+
+For issues related to:
+- **Agent Engine**: Check Google Cloud Agent Engine documentation
+- **Gradio**: Visit https://gradio.app/docs
+- **This project**: Open an issue in the repository

GRADIO_SUMMARY.md

@@ -0,0 +1,237 @@
+# Gradio Chat UI - Project Summary
+
+## 📁 Files Created
+
+### Main Application Files
+
+1. **`gradio_app.py`** - Original Gradio chat UI
+   - Uses `vertexai.agent_engines._agent_engines.AgentEngine`
+   - Simple agent selection and chat interface
+
+2. **`gradio_app_v2.py`** ⭐ **RECOMMENDED**
+   - Uses `google.cloud.aiplatform_v1beta1.AgentEnginesServiceClient`
+   - More robust agent listing and querying
+   - Better error handling
+   - Session ID support for conversation continuity
+   - Enhanced UI with examples and tips
+
+3. **`run_gradio.py`** - Simple launcher script
+   - Quick way to start the Gradio app
+
+### Setup & Documentation
+
+4. **`setup_gradio.sh`** - Setup script
+   - Checks prerequisites
+   - Installs dependencies
+   - Provides next steps
+
+5. **`GRADIO_README.md`** - Comprehensive documentation
+   - Features overview
+   - Installation guide
+   - Usage examples
+   - Troubleshooting tips
+
+6. **`QUICKSTART_GRADIO.md`** - Quick start guide
+   - Step-by-step setup instructions
+   - Running options
+   - Common issues and solutions
+   - Success checklist
+
+### Updated Files
+
+7. **`requirements.txt`** - Added dependencies
+   - `gradio==5.8.0`
+   - `python-dotenv==1.0.0`
+
+## 🚀 How to Use
+
+### Quick Start (3 steps)
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Authenticate
+gcloud auth application-default login
+
+# 3. Run the app
+python gradio_app_v2.py
+```
+
+Then open http://localhost:7860 in your browser!
+
+### Alternative Methods
+
+```bash
+# Using launcher
+python run_gradio.py
+
+# Using setup script
+./setup_gradio.sh
+```
+
+## ✨ Key Features
+
+### Agent Discovery
+- Automatically lists all deployed agents from Agent Engine
+- Refresh button to update agent list dynamically
+- Clear display names for easy selection
+
+### Chat Interface
+- Real-time conversation with selected agent
+- Chat history with copy functionality
+- Session ID for conversation continuity
+- Modern, clean UI built with Gradio
+
+### RAG Capabilities
+The agents support full RAG operations:
+- 📋 List document corpora
+- 🔍 Query documents
+- ➕ Create new corpora
+- 📄 Add documents
+- ℹ️ Get corpus information
+- 🗑️ Delete documents/corpora
+
+## 📊 Architecture
+
+```
+User Browser
+    ↓
+Gradio Web UI (Port 7860)
+    ↓
+gradio_app_v2.py
+    ↓
+AgentEnginesServiceClient
+    ↓
+Google Cloud Agent Engine
+    ↓
+Deployed RAG Agent
+    ↓
+Vertex AI RAG Service
+    ↓
+Document Corpora
+```
+
+## 🔧 Configuration
+
+### Environment Variables (in `rag_agent/.env`)
+
+```bash
+GOOGLE_CLOUD_PROJECT="your-project-id"
+GOOGLE_CLOUD_LOCATION="us-central1"  # or your region
+GOOGLE_GENAI_USE_VERTEXAI="true"
+```
+
+### Customization Options
+
+In `gradio_app_v2.py`, you can modify:
+
+- **Server Port**: Default is 7860
+  ```python
+  demo.launch(server_port=8080)
+  ```
+
+- **Theme**: Change the UI theme
+  ```python
+  gr.Blocks(theme=gr.themes.Glass())
+  ```
+
+- **Share**: Create public temporary URL
+  ```python
+  demo.launch(share=True)
+  ```
+
+## 🎯 Example Usage
+
+### List Available Corpora
+```
+User: List all available corpora
+Agent: Here are the available corpora:
+       1. tech-docs
+       2. company-handbook
+       3. research-papers
+```
+
+### Query Documents
+```
+User: What information do you have about machine learning?
+Agent: Based on the documents in the 'research-papers' corpus, 
+       here's what I found about machine learning...
+```
+
+### Create Corpus
+```
+User: Create a new corpus called 'customer-feedback'
+Agent: ✅ Successfully created corpus 'customer-feedback'
+```
+
+### Add Data
+```
+User: Add this Google Drive file to the corpus: https://drive.google.com/file/d/abc123
+Agent: ✅ Successfully added the document to the corpus
+```
+
+## 🐛 Common Issues & Solutions
+
+### No Agents Found
+- **Cause**: No agents deployed to Agent Engine
+- **Solution**: Run `make deploy` to deploy an agent
+
+### Authentication Error
+- **Cause**: Not authenticated with Google Cloud
+- **Solution**: Run `gcloud auth application-default login`
+
+### Module Not Found
+- **Cause**: Dependencies not installed
+- **Solution**: Run `pip install -r requirements.txt`
+
+### Wrong Location
+- **Cause**: `GOOGLE_CLOUD_LOCATION` doesn't match agent location
+- **Solution**: Update `.env` file with correct location
+
+## 📈 Next Steps
+
+### Enhancements You Can Add
+
+1. **File Upload**: Add Gradio File component for document upload
+   ```python
+   file_upload = gr.File(label="Upload Document")
+   ```
+
+2. **Multi-modal**: Add image support
+   ```python
+   image_input = gr.Image(label="Upload Image")
+   ```
+
+3. **Analytics**: Track usage and conversations
+   ```python
+   # Log queries to BigQuery or Cloud Logging
+   ```
+
+4. **Authentication**: Add user authentication
+   ```python
+   demo.launch(auth=("username", "password"))
+   ```
+
+5. **Streaming**: Add streaming responses
+   ```python
+   # Use generator pattern for streaming
+   ```
+
+## 📚 Resources
+
+- **Gradio**: https://gradio.app/docs
+- **Vertex AI Agent Engine**: https://cloud.google.com/agent-engine/docs
+- **Google ADK**: https://github.com/google/genai-adk
+
+## 🎉 Summary
+
+You now have a fully functional Gradio chat UI that:
+- ✅ Lists all deployed agents
+- ✅ Allows agent selection via dropdown
+- ✅ Provides real-time chat interface
+- ✅ Supports full RAG operations
+- ✅ Maintains conversation context
+- ✅ Has modern, user-friendly UI
+
+Ready to chat with your RAG agents! 🤖💬

Makefile

@@ -0,0 +1,80 @@
+# ==============================================================================
+# Installation & Setup
+# ==============================================================================
+
+# Install dependencies using uv package manager
+install:
+	@command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.8.13/install.sh | sh; source $HOME/.local/bin/env; }
+	uv sync
+
+# ==============================================================================
+# Playground Targets
+# ==============================================================================
+
+# Launch local dev playground
+playground:
+	@echo "==============================================================================="
+	@echo "| 🚀 Starting your agent playground...                                        |"
+	@echo "|                                                                             |"
+	@echo "| 💡 Try asking: What's the weather in San Francisco?                         |"
+	@echo "|                                                                             |"
+	@echo "| 🔍 IMPORTANT: Select the 'rag_agent' folder to interact with your agent.          |"
+	@echo "==============================================================================="
+	uv run adk web . --port 8501 --reload_agents
+
+# ==============================================================================
+# Backend Deployment Targets
+# ==============================================================================
+
+# Deploy the agent remotely
+deploy:
+	# Export dependencies to requirements file using uv export.
+	(uv export --no-hashes --no-header --no-dev --no-emit-project --no-annotate > rag_agent/app_utils/.requirements.txt 2>/dev/null || \
+	uv export --no-hashes --no-header --no-dev --no-emit-project > rag_agent/app_utils/.requirements.txt) && \
+	uv run -m rag_agent.app_utils.deploy \
+		--source-packages=./rag_agent \
+		--display-name="bitcast_agent_focus" \
+		--entrypoint-module=rag_agent.agent_engine_app \
+		--entrypoint-object=agent_engine \
+		--requirements-file=rag_agent/app_utils/.requirements.txt
+
+# Alias for 'make deploy' for backward compatibility
+backend: deploy
+
+
+# ==============================================================================
+# Infrastructure Setup
+# ==============================================================================
+
+# Set up development environment resources using Terraform
+setup-dev-env:
+	PROJECT_ID=$$(gcloud config get-value project) && \
+	(cd deployment/terraform/dev && terraform init && terraform apply --var-file vars/env.tfvars --var dev_project_id=$$PROJECT_ID --auto-approve)
+
+# ==============================================================================
+# Testing & Code Quality
+# ==============================================================================
+
+# Run unit and integration tests
+test:
+	uv sync --dev
+	uv run pytest tests/unit && uv run pytest tests/integration
+
+# Run code quality checks (codespell, ruff, mypy)
+lint:
+	uv sync --dev --extra lint
+	uv run codespell
+	uv run ruff check . --diff
+	uv run ruff format . --check --diff
+	uv run mypy .
+
+# ==============================================================================
+# Gemini Enterprise Integration
+# ==============================================================================
+
+# Register the deployed agent to Gemini Enterprise
+# Usage: make register-gemini-enterprise (interactive - will prompt for required details)
+# For non-interactive use, set env vars: ID or GEMINI_ENTERPRISE_APP_ID (full GE resource name)
+# Optional env vars: GEMINI_DISPLAY_NAME, GEMINI_DESCRIPTION, GEMINI_TOOL_DESCRIPTION, AGENT_ENGINE_ID
+register-gemini-enterprise:
+	@uvx agent-starter-pack@0.21.0 register-gemini-enterprise

QUICKSTART_GRADIO.md

@@ -0,0 +1,266 @@
+# 🚀 Quick Start Guide - Gradio Chat UI
+
+This guide will help you set up and run the Gradio chat interface for your RAG Agent.
+
+## 📋 Prerequisites
+
+1. **Python 3.10+** installed
+2. **Google Cloud Project** with Agent Engine enabled
+3. **Agent deployed** to Agent Engine (or follow deployment steps below)
+4. **Authentication** set up with Google Cloud
+
+## 🛠️ Setup Instructions
+
+### Step 1: Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+This will install:
+- `gradio` - Web UI framework
+- `google-cloud-aiplatform` - Google Cloud AI Platform SDK
+- `vertexai` - Vertex AI SDK
+- `python-dotenv` - Environment variable management
+- Other required packages
+
+### Step 2: Configure Environment
+
+Make sure your `rag_agent/.env` file has the correct values:
+
+```bash
+GOOGLE_CLOUD_PROJECT="your-project-id"
+GOOGLE_CLOUD_LOCATION="your-location"  # e.g., us-central1, asia-southeast1
+GOOGLE_GENAI_USE_VERTEXAI="true"
+```
+
+### Step 3: Authenticate with Google Cloud
+
+```bash
+gcloud auth application-default login
+```
+
+### Step 4: Deploy Your Agent (if not already deployed)
+
+```bash
+make deploy
+```
+
+Or manually:
+
+```bash
+python -m rag_agent.app_utils.deploy
+```
+
+## ▶️ Running the App
+
+### Option 1: Run directly
+
+```bash
+python gradio_app_v2.py
+```
+
+### Option 2: Use the launcher script
+
+```bash
+python run_gradio.py
+```
+
+### Option 3: Use the setup script
+
+```bash
+./setup_gradio.sh
+```
+
+The app will start on **http://localhost:7860**
+
+## 🎯 Using the Chat Interface
+
+### 1. Select an Agent
+
+- Use the dropdown menu to choose from deployed agents
+- Click "🔄 Refresh" to update the agent list
+
+### 2. Set Session ID (Optional)
+
+- Enter a unique session ID to maintain conversation context
+- Same session ID = continuous conversation
+- Different session ID = new conversation
+
+### 3. Start Chatting
+
+Example queries:
+
+```
+📋 List all available corpora
+```
+
+```
+🔍 What information do you have about machine learning?
+```
+
+```
+➕ Create a new corpus called 'tech-docs'
+```
+
+```
+📄 Add this file to the corpus: https://drive.google.com/file/d/YOUR_FILE_ID
+```
+
+```
+ℹ️ Show me details about the 'tech-docs' corpus
+```
+
+```
+🗑️ Delete the 'old-docs' corpus
+```
+
+## 🔧 Troubleshooting
+
+### Issue: "No agents found"
+
+**Solution:**
+1. Verify your agent is deployed:
+   ```bash
+   gcloud agent-engines list --location=YOUR_LOCATION
+   ```
+2. Check your environment variables are correct
+3. Ensure you have proper permissions
+
+### Issue: Authentication errors
+
+**Solution:**
+```bash
+gcloud auth application-default login
+gcloud config set project YOUR_PROJECT_ID
+```
+
+### Issue: Import errors
+
+**Solution:**
+```bash
+pip install -r requirements.txt --upgrade
+```
+
+### Issue: Connection timeout
+
+**Solution:**
+1. Check your `GOOGLE_CLOUD_LOCATION` matches your agent's location
+2. Verify firewall settings
+3. Try a different location/region
+
+## 📊 Features
+
+### ✅ Available Features
+
+- ✨ **Auto-discovery** of all deployed agents
+- 💬 **Real-time chat** with selected agents
+- 🔄 **Dynamic refresh** of agent list
+- 📝 **Chat history** with copy functionality
+- 🎨 **Modern UI** with Gradio
+- 🔐 **Session management** for conversation continuity
+- 🤖 **Full RAG capabilities** (query, create, delete, etc.)
+
+### 🎨 UI Components
+
+- **Agent Dropdown**: Select from available agents
+- **Session ID**: Maintain conversation context
+- **Chat History**: View full conversation
+- **Message Input**: Type and send messages
+- **Action Buttons**: Send, Clear, Refresh
+- **Examples Accordion**: View capabilities and examples
+
+## 🌐 Deployment Options
+
+### Local Development
+
+Default configuration (localhost only):
+```python
+demo.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    share=False
+)
+```
+
+### Share with Temporary Public URL
+
+```python
+demo.launch(share=True)  # Creates temporary gradio.live URL
+```
+
+### Deploy to Hugging Face Spaces
+
+1. Create a new Space on [Hugging Face](https://huggingface.co/spaces)
+2. Push your code to the Space repository
+3. Add secrets for your Google Cloud credentials
+
+### Deploy to Cloud Run
+
+```bash
+# Create Dockerfile
+# Build and deploy to Cloud Run
+gcloud run deploy gradio-rag-agent \
+  --source . \
+  --region=us-central1 \
+  --allow-unauthenticated
+```
+
+## 📝 Customization
+
+### Change Port
+
+```python
+demo.launch(server_port=8080)
+```
+
+### Change Theme
+
+```python
+with gr.Blocks(theme=gr.themes.Glass()) as demo:
+    # or gr.themes.Monochrome(), gr.themes.Soft()
+```
+
+### Add Custom Features
+
+Edit `gradio_app_v2.py` to add:
+- Custom styling
+- Additional inputs/outputs
+- File upload capabilities
+- Analytics tracking
+
+## 🔒 Security Notes
+
+- Never commit your `.env` file
+- Use service accounts with minimal required permissions
+- Enable authentication for production deployments
+- Review and sanitize user inputs if deploying publicly
+
+## 📚 Additional Resources
+
+- [Gradio Documentation](https://gradio.app/docs)
+- [Vertex AI Agent Engine Docs](https://cloud.google.com/agent-engine/docs)
+- [Google Cloud Authentication](https://cloud.google.com/docs/authentication)
+
+## 🆘 Getting Help
+
+If you encounter issues:
+
+1. Check the console output for error messages
+2. Verify all prerequisites are met
+3. Review the troubleshooting section above
+4. Check Google Cloud logs for agent-related issues
+5. Open an issue in the repository
+
+## 🎉 Success Checklist
+
+- [ ] Dependencies installed
+- [ ] Environment configured
+- [ ] Authenticated with Google Cloud
+- [ ] Agent deployed to Agent Engine
+- [ ] Gradio app running
+- [ ] Can select agent from dropdown
+- [ ] Can send messages and receive responses
+- [ ] Chat history displays correctly
+
+Happy chatting! 🤖💬

VERSIONS_COMPARISON.md

@@ -0,0 +1,205 @@
+# Gradio App Versions Comparison
+
+## 📊 Overview
+
+Two versions of the Gradio chat UI have been created. Here's a comparison to help you choose:
+
+## Version 1: `gradio_app.py`
+
+### Implementation
+- Uses `vertexai.agent_engines._agent_engines.AgentEngine`
+- Direct agent instantiation approach
+
+### Pros
+- ✅ Simpler code structure
+- ✅ Direct AgentEngine object usage
+- ✅ Good for basic use cases
+
+### Cons
+- ❌ Less robust error handling
+- ❌ May have issues with agent listing
+- ❌ No session management
+- ❌ Uses internal/private API (`_agent_engines`)
+
+### Best For
+- Quick prototypes
+- Development/testing
+- Simple single-agent scenarios
+
+## Version 2: `gradio_app_v2.py` ⭐ **RECOMMENDED**
+
+### Implementation
+- Uses `google.cloud.aiplatform_v1beta1.AgentEnginesServiceClient`
+- Official Google Cloud API client
+
+### Pros
+- ✅ More reliable agent listing
+- ✅ Better error handling
+- ✅ Session ID support for conversation continuity
+- ✅ Uses official/public API
+- ✅ Enhanced UI with examples
+- ✅ More informative error messages
+- ✅ Better structured code
+
+### Cons
+- ⚠️ Slightly more complex
+- ⚠️ Requires understanding of request/response patterns
+
+### Best For
+- Production deployments
+- Multi-agent scenarios
+- Long-term maintenance
+- Full-featured applications
+
+## 🔍 Detailed Comparison
+
+| Feature | gradio_app.py | gradio_app_v2.py |
+|---------|---------------|------------------|
+| Agent Listing | Basic | Robust with caching |
+| Error Handling | Basic | Comprehensive |
+| Session Management | ❌ No | ✅ Yes |
+| UI/UX | Simple | Enhanced with examples |
+| API Stability | Internal API | Official API |
+| Code Structure | Simpler | Well-organized |
+| Documentation | Basic | Detailed |
+| Examples | ❌ No | ✅ Yes |
+| Avatar Support | ❌ No | ✅ Yes |
+| Status Messages | Basic | Emoji + detailed |
+
+## 💻 Code Examples
+
+### Version 1 - Agent Querying
+```python
+agent_engine = AgentEngine(name=agent_resource_name)
+response = agent_engine.query(query=message)
+response_text = response.text
+```
+
+### Version 2 - Agent Querying
+```python
+client = aiplatform.AgentEnginesServiceClient(
+    client_options={"api_endpoint": f"{LOCATION}-aiplatform.googleapis.com"}
+)
+
+request = aiplatform.QueryAgentEngineRequest(
+    name=agent_name,
+    query_config=aiplatform.QueryConfig(query=query_text),
+    session_id=session_id,
+)
+
+response = client.query_agent_engine(request=request)
+```
+
+## 🎯 Recommendation
+
+### Use `gradio_app_v2.py` if:
+- ✅ You want a production-ready solution
+- ✅ You need session management
+- ✅ You want better error handling
+- ✅ You prefer using official APIs
+- ✅ You need a more polished UI
+
+### Use `gradio_app.py` if:
+- ✅ You're just testing quickly
+- ✅ You prefer simpler code
+- ✅ You don't need advanced features
+- ✅ You want minimal dependencies
+
+## 🚀 Migration Path
+
+If you start with v1 and want to upgrade to v2:
+
+1. **No code changes needed in your agent** - Both versions work with the same deployed agents
+
+2. **Switch the file you run**:
+   ```bash
+   # From
+   python gradio_app.py
+   
+   # To
+   python gradio_app_v2.py
+   ```
+
+3. **Benefits immediately available**:
+   - Session management
+   - Better error messages
+   - Enhanced UI
+   - More stable agent listing
+
+## 🔧 Technical Differences
+
+### Agent Listing
+
+**Version 1:**
+```python
+for agent in client.agent_engines.list():
+    if agent.api_resource.display_name == display_name
+```
+
+**Version 2:**
+```python
+request = aiplatform.ListAgentEnginesRequest(parent=parent)
+for agent in client.list_agent_engines(request=request):
+    agents.append({
+        "name": agent.name,
+        "display_name": agent.display_name
+    })
+```
+
+### Error Handling
+
+**Version 1:**
+```python
+except Exception as e:
+    error_msg = f"Error communicating with agent: {str(e)}"
+```
+
+**Version 2:**
+```python
+except Exception as e:
+    error_msg = f"❌ Error: {str(e)}"
+    # More context provided to user
+```
+
+## 📈 Feature Roadmap
+
+### Planned for Both Versions
+- File upload support
+- Multi-modal inputs (images, PDFs)
+- Export chat history
+- Custom themes
+
+### Already in V2 Only
+- ✅ Session management
+- ✅ Enhanced error messages
+- ✅ UI examples accordion
+- ✅ Avatar support
+
+## 🎓 Learning Path
+
+1. **Start with V1** to understand basics
+2. **Review V2** to see best practices
+3. **Use V2** for actual deployment
+4. **Customize** based on your needs
+
+## 🏆 Winner: `gradio_app_v2.py`
+
+For most use cases, **Version 2** is the recommended choice due to:
+- Better stability
+- Official API usage
+- Enhanced features
+- Production-ready design
+
+However, both versions are maintained and functional!
+
+## 🤝 Support
+
+Both versions support the same agent capabilities:
+- 📋 List corpora
+- 🔍 Query documents  
+- ➕ Create corpus
+- 📄 Add data
+- ℹ️ Get corpus info
+- 🗑️ Delete document/corpus
+
+Choose based on your needs and preferences! 🚀

deployment/README.md

@@ -0,0 +1,11 @@
+# Deployment
+
+This directory contains the Terraform configurations for provisioning the necessary Google Cloud infrastructure for your agent.
+
+The recommended way to deploy the infrastructure and set up the CI/CD pipeline is by using the `agent-starter-pack setup-cicd` command from the root of your project.
+
+However, for a more hands-on approach, you can always apply the Terraform configurations manually for a do-it-yourself setup.
+
+For detailed information on the deployment process, infrastructure, and CI/CD pipelines, please refer to the official documentation:
+
+**[Agent Starter Pack Deployment Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment.html)**

deployment_metadata.json

@@ -0,0 +1,6 @@
+{
+  "remote_agent_engine_id": "projects/38827506989/locations/asia-southeast1/reasoningEngines/6874287434343907328",
+  "deployment_target": "agent_engine",
+  "is_a2a": false,
+  "deployment_timestamp": "2025-11-22T15:59:29.627181"
+}

gradio_app.py

@@ -0,0 +1,193 @@
+"""
+Gradio Chat UI for RAG Agent
+"""
+
+import os
+import sys
+import gradio as gr
+import vertexai
+from vertexai.agent_engines._agent_engines import AgentEngine
+from google.cloud import aiplatform
+from dotenv import load_dotenv
+
+# Add the project root to the path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Load environment variables from rag_agent/.env
+env_path = os.path.join(os.path.dirname(__file__), "rag_agent", ".env")
+load_dotenv(env_path)
+
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
+LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
+
+# Initialize Vertex AI
+vertexai.init(project=PROJECT_ID, location=LOCATION)
+
+
+def list_available_agents():
+    """List all available agents from Agent Engine."""
+    try:
+        client = aiplatform.gapic.AgentEnginesServiceClient(
+            client_options={"api_endpoint": f"{LOCATION}-aiplatform.googleapis.com"}
+        )
+        parent = f"projects/{PROJECT_ID}/locations/{LOCATION}"
+        
+        agents = []
+        for agent in client.list_agent_engines(parent=parent):
+            agent_info = {
+                "name": agent.name,
+                "display_name": agent.display_name,
+            }
+            agents.append(agent_info)
+        
+        return agents
+    except Exception as e:
+        print(f"Error listing agents: {e}")
+        return []
+
+
+def get_agent_names():
+    """Get list of agent display names for dropdown."""
+    agents = list_available_agents()
+    if not agents:
+        return ["No agents found"]
+    return [agent["display_name"] for agent in agents]
+
+
+def get_agent_by_display_name(display_name):
+    """Get agent resource name by display name."""
+    agents = list_available_agents()
+    for agent in agents:
+        if agent["display_name"] == display_name:
+            return agent["name"]
+    return None
+
+
+def chat_with_agent(message, history, agent_name):
+    """Send message to selected agent and get response."""
+    if not message:
+        return history
+    
+    if agent_name == "No agents found":
+        history.append((message, "Error: No agents available. Please deploy an agent first."))
+        return history
+    
+    try:
+        # Get the agent resource name
+        agent_resource_name = get_agent_by_display_name(agent_name)
+        if not agent_resource_name:
+            history.append((message, f"Error: Could not find agent '{agent_name}'"))
+            return history
+        
+        # Create AgentEngine instance
+        agent_engine = AgentEngine(name=agent_resource_name)
+        
+        # Send query to agent
+        response = agent_engine.query(query=message)
+        
+        # Extract response text
+        if hasattr(response, 'text'):
+            response_text = response.text
+        elif isinstance(response, dict) and 'text' in response:
+            response_text = response['text']
+        else:
+            response_text = str(response)
+        
+        history.append((message, response_text))
+        
+    except Exception as e:
+        error_msg = f"Error communicating with agent: {str(e)}"
+        history.append((message, error_msg))
+    
+    return history
+
+
+def refresh_agents():
+    """Refresh the list of available agents."""
+    return gr.Dropdown(choices=get_agent_names(), value=get_agent_names()[0])
+
+
+# Create Gradio interface
+with gr.Blocks(title="RAG Agent Chat", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🤖 RAG Agent Chat Interface")
+    gr.Markdown("Select an agent and start chatting!")
+    
+    with gr.Row():
+        with gr.Column(scale=3):
+            agent_dropdown = gr.Dropdown(
+                choices=get_agent_names(),
+                value=get_agent_names()[0] if get_agent_names() else "No agents found",
+                label="Select Agent",
+                interactive=True
+            )
+        with gr.Column(scale=1):
+            refresh_btn = gr.Button("🔄 Refresh Agents", size="sm")
+    
+    chatbot = gr.Chatbot(
+        label="Chat History",
+        height=500,
+        show_copy_button=True
+    )
+    
+    with gr.Row():
+        msg = gr.Textbox(
+            label="Your Message",
+            placeholder="Type your message here...",
+            scale=4,
+            lines=2
+        )
+        submit_btn = gr.Button("Send", variant="primary", scale=1)
+    
+    clear_btn = gr.Button("Clear Chat")
+    
+    gr.Markdown("""
+    ### 📝 Agent Capabilities
+    - **Query Documents**: Ask questions and retrieve information from document corpora
+    - **List Corpora**: See all available document collections
+    - **Create Corpus**: Create new document collections
+    - **Add Data**: Add documents to existing corpora
+    - **Get Corpus Info**: View detailed corpus information
+    - **Delete Document/Corpus**: Remove documents or entire corpora
+    """)
+    
+    # Event handlers
+    def submit_message(message, history, agent_name):
+        history = chat_with_agent(message, history, agent_name)
+        return "", history
+    
+    submit_btn.click(
+        submit_message,
+        inputs=[msg, chatbot, agent_dropdown],
+        outputs=[msg, chatbot]
+    )
+    
+    msg.submit(
+        submit_message,
+        inputs=[msg, chatbot, agent_dropdown],
+        outputs=[msg, chatbot]
+    )
+    
+    clear_btn.click(lambda: [], outputs=chatbot)
+    
+    refresh_btn.click(
+        refresh_agents,
+        outputs=agent_dropdown
+    )
+
+
+if __name__ == "__main__":
+    # Check if required environment variables are set
+    if not PROJECT_ID:
+        print("⚠️  Warning: GOOGLE_CLOUD_PROJECT environment variable not set")
+        print("Please set it in your .env file or environment")
+    
+    print(f"🚀 Starting Gradio app...")
+    print(f"📍 Project: {PROJECT_ID}")
+    print(f"📍 Location: {LOCATION}")
+    print(f"🔍 Found {len(get_agent_names())} agent(s)")
+    
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    )

gradio_app_v2.py

@@ -0,0 +1,443 @@
+"""
+Alternative Gradio Chat UI using Agent Engine Client directly
+This version uses the Vertex AI SDK for Python for more reliable agent listing and querying.
+"""
+
+import os
+import sys
+import gradio as gr
+import vertexai
+from dotenv import load_dotenv
+
+# Add the project root to the path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Load environment variables from rag_agent/.env
+env_path = os.path.join(os.path.dirname(__file__), "rag_agent", ".env")
+load_dotenv(env_path)
+
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
+LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")
+
+# Initialize Vertex AI
+vertexai.init(project=PROJECT_ID, location=LOCATION)
+
+# Global state for agents and sessions
+agents_cache = []
+# Store session_id per agent to maintain conversation context
+agent_sessions = {}
+
+
+def list_available_agents():
+    """List all available agents from Agent Engine."""
+    global agents_cache
+    try:
+        client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
+        
+        agents = []
+        for agent in client.agent_engines.list():
+            # Access the underlying api_resource which contains name and display_name
+            agent_info = {
+                "name": agent.api_resource.name,
+                "display_name": agent.api_resource.display_name or agent.api_resource.name.split("/")[-1],
+            }
+            agents.append(agent_info)
+        
+        agents_cache = agents
+        return agents
+    except Exception as e:
+        print(f"Error listing agents: {e}")
+        import traceback
+        traceback.print_exc()
+        return []
+
+
+def get_agent_names():
+    """Get list of agent display names for dropdown."""
+    agents = list_available_agents()
+    if not agents:
+        return ["No agents found - Please deploy an agent first"]
+    return [agent["display_name"] for agent in agents]
+
+
+def get_agent_by_display_name(display_name):
+    """Get agent resource name by display name."""
+    for agent in agents_cache:
+        if agent["display_name"] == display_name:
+            return agent["name"]
+    return None
+
+
+def query_agent(agent_name, query_text, session_id=None):
+    """Query the agent engine."""
+    try:
+        client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
+        adk_app = client.agent_engines.get(name=agent_name)
+        
+        print(f"\n{'='*60}")
+        print(f"DEBUG: Starting query...")
+        print(f"Agent: {agent_name}")
+        print(f"Query: {query_text}")
+        print(f"Session ID: {session_id}")
+        print(f"{'='*60}\n")
+        
+        # Use async_stream_query and wrap it with asyncio.run()
+        import asyncio
+        
+        async def run_query():
+            result_parts = []
+            event_count = 0
+            
+            # Create or get existing session for this agent
+            global agent_sessions
+            if agent_name not in agent_sessions:
+                print("Creating new session for agent...")
+                session = await adk_app.async_create_session(user_id="gradio-user")
+                print("sessionn nnnnn.   ", session)
+                agent_sessions[agent_name] = session["id"]
+                # print(f"Created session: {session.id}")
+            
+            current_session_id = agent_sessions[agent_name]
+            
+            # Build kwargs with session_id and user_id
+            kwargs = {
+                "session_id": current_session_id,
+                "user_id": "gradio-user",
+                "message": query_text,
+            }
+            
+            print(f"Query kwargs: {kwargs}\n")
+            
+            async for event in adk_app.async_stream_query(**kwargs):
+                event_count += 1
+                print(f"\n--- Event #{event_count} ---")
+                print(f"Event type: {type(event)}")
+                print(f"Event: {event}")
+                
+                if isinstance(event, dict):
+                    print(f"Event keys: {list(event.keys())}")
+                    # Extract text from content.parts
+                    content = event.get('content', {})
+                    print(f"Content: {content}")
+                    print(f"Content type: {type(content)}")
+                    
+                    if isinstance(content, dict):
+                        parts = content.get('parts', [])
+                        print(f"Parts: {parts}")
+                        print(f"Parts count: {len(parts)}")
+                        
+                        for i, part in enumerate(parts):
+                            print(f"  Part {i}: {part}")
+                            print(f"  Part {i} type: {type(part)}")
+                            if isinstance(part, dict):
+                                print(f"  Part {i} keys: {list(part.keys())}")
+                                if 'text' in part:
+                                    text = part['text']
+                                    print(f"  ✓ Found text: {text[:100]}...")
+                                    result_parts.append(text)
+                else:
+                    print(f"Event is not a dict!")
+                print(f"--- End Event #{event_count} ---\n")
+            
+            print(f"\n{'='*60}")
+            print(f"DEBUG: Query complete")
+            print(f"Total events: {event_count}")
+            print(f"Total text parts extracted: {len(result_parts)}")
+            print(f"{'='*60}\n")
+            
+            return "\n".join(result_parts) if result_parts else "No response received"
+        
+        # Run the async function
+        return asyncio.run(run_query())
+        
+    except Exception as e:
+        print(f"\n{'='*60}")
+        print(f"ERROR in query_agent:")
+        import traceback
+        traceback.print_exc()
+        print(f"{'='*60}\n")
+        raise Exception(f"Error querying agent: {str(e)}")
+
+
+def chat_with_agent(message, history, agent_name):
+    """Send message to selected agent and get response."""
+    if not message or not message.strip():
+        return history
+    
+    if "No agents found" in agent_name:
+        history.append((message, "❌ Error: No agents available. Please deploy an agent first."))
+        return history
+    
+    try:
+        # Get the agent resource name
+        agent_resource_name = get_agent_by_display_name(agent_name)
+        if not agent_resource_name:
+            history.append((message, f"❌ Error: Could not find agent '{agent_name}'"))
+            return history
+        
+        # Query the agent (session is managed per agent to maintain context)
+        response_text = query_agent(agent_resource_name, message)
+        
+        history.append((message, response_text))
+        
+    except Exception as e:
+        error_msg = f"❌ Error: {str(e)}"
+        history.append((message, error_msg))
+    
+    return history
+
+
+def refresh_agents():
+    """Refresh the list of available agents."""
+    names = get_agent_names()
+    return gr.Dropdown(choices=names, value=names[0])
+
+
+def clear_chat_and_session(agent_name):
+    """Clear chat history and reset session for the agent."""
+    global agent_sessions
+    agent_resource_name = get_agent_by_display_name(agent_name)
+    if agent_resource_name and agent_resource_name in agent_sessions:
+        print(f"Clearing session for agent: {agent_name}")
+        del agent_sessions[agent_resource_name]
+    return []
+
+
+# Create LINE-themed Gradio interface
+line_theme = gr.themes.Base(
+    primary_hue="green",
+    secondary_hue="emerald",
+    neutral_hue="slate",
+    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui", "sans-serif"],
+).set(
+    # LINE green colors
+    button_primary_background_fill="#06C755",
+    button_primary_background_fill_hover="#05B04C",
+    button_primary_text_color="white",
+    button_secondary_background_fill="white",
+    button_secondary_border_color="#06C755",
+    button_secondary_text_color="#06C755",
+    
+    # Light background like LINE
+    body_background_fill="white",
+    body_background_fill_dark="white",
+    background_fill_primary="white",
+    background_fill_primary_dark="white",
+    background_fill_secondary="#F7F7F7",
+    background_fill_secondary_dark="#F7F7F7",
+    
+    # Input styling
+    input_background_fill="white",
+    input_background_fill_dark="white",
+    input_border_color="#E0E0E0",
+    input_border_color_dark="#E0E0E0",
+    
+    # Block styling
+    block_background_fill="white",
+    block_background_fill_dark="white",
+    block_border_color="#E0E0E0",
+    block_border_color_dark="#E0E0E0",
+    block_title_text_weight="600",
+    block_border_width="1px",
+    block_shadow="0 1px 3px rgba(0,0,0,0.05)",
+    
+    # Text colors
+    body_text_color="#111111",
+    body_text_color_dark="#111111",
+    block_title_text_color="#111111",
+    block_title_text_color_dark="#111111",
+    block_label_text_color="#666666",
+    block_label_text_color_dark="#666666",
+)
+
+with gr.Blocks(title="RAG Agent Chat", theme=line_theme, css="""
+    .gradio-container {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif !important;
+        background: white !important;
+    }
+    .chat-message {
+        border-radius: 18px !important;
+        padding: 12px 16px !important;
+    }
+    /* User message styling - light gray bubble on right */
+    .message.user {
+        background-color: #E5E5EA !important;
+        color: #000000 !important;
+        border-radius: 18px !important;
+    }
+    .message.user .message-content {
+        color: #000000 !important;
+    }
+    /* Bot message styling - LINE green bubble on left */
+    .message.bot {
+        background-color: #E8F5E9 !important;
+        color: #000000 !important;
+        border-radius: 18px !important;
+    }
+    .message.bot .message-content {
+        color: #000000 !important;
+    }
+    /* Make sure all text in chat is dark */
+    .message * {
+        color: #000000 !important;
+    }
+    /* Fix code blocks and inline code */
+    .message code {
+        background-color: rgba(0, 0, 0, 0.05) !important;
+        color: #000000 !important;
+        padding: 2px 6px !important;
+        border-radius: 4px !important;
+    }
+    .message pre {
+        background-color: rgba(0, 0, 0, 0.05) !important;
+        color: #000000 !important;
+        padding: 12px !important;
+        border-radius: 8px !important;
+    }
+    .message pre code {
+        background-color: transparent !important;
+    }
+    /* Fix any remaining dark backgrounds */
+    .message p, .message span, .message div {
+        color: #000000 !important;
+    }
+    #component-0, #component-1, #component-2 {
+        background: white !important;
+    }
+    .dark {
+        background: white !important;
+    }
+""") as demo:
+    gr.Markdown("# 💬 RAG Agent Chat")
+    gr.Markdown(f"**Project:** `{PROJECT_ID}` | **Location:** `{LOCATION}`")
+    
+    with gr.Row():
+        with gr.Column(scale=3):
+            agent_dropdown = gr.Dropdown(
+                choices=get_agent_names(),
+                value=get_agent_names()[0] if get_agent_names() else "No agents found",
+                label="Select Agent",
+                interactive=True
+            )
+        with gr.Column(scale=1):
+            refresh_btn = gr.Button("🔄 Refresh", size="sm")
+    
+    chatbot = gr.Chatbot(
+        label="💬 Messages",
+        height=500,
+        show_copy_button=True,
+        avatar_images=(
+            None,  # User avatar (none shows default)
+            "https://em-content.zobj.net/source/apple/391/robot_1f916.png"  # Cute robot emoji as bot avatar
+        ),
+        bubble_full_width=False,
+    )
+    
+    with gr.Row():
+        msg = gr.Textbox(
+            label="",
+            placeholder="💭 Type a message...",
+            scale=5,
+            lines=1,
+            container=False,
+        )
+    
+    with gr.Row():
+        submit_btn = gr.Button("Send", variant="primary", scale=1, size="sm")
+        clear_btn = gr.Button("Clear", variant="secondary", scale=1, size="sm")
+    
+    with gr.Accordion("📚 Agent Capabilities & Examples", open=False):
+        gr.Markdown("""
+        ### What the RAG Agent Can Do:
+        
+        - **📋 List Corpora**: View all available document collections
+          - Example: *"List all available corpora"*
+          - Example: *"What corpora do you have?"*
+        
+        - **🔍 Query Documents**: Ask questions about documents in corpora
+          - Example: *"What information do you have about [topic]?"*
+          - Example: *"Search for information about X in the corpus"*
+        
+        - **➕ Create Corpus**: Create new document collections
+          - Example: *"Create a new corpus called 'company-docs'"*
+        
+        - **📄 Add Data**: Add documents to corpora
+          - Example: *"Add this Google Drive file to the corpus: https://drive.google.com/file/d/..."*
+          - Example: *"Add data from gs://bucket/file.pdf to the corpus"*
+        
+        - **ℹ️ Get Corpus Info**: View detailed information about corpora
+          - Example: *"Show me details about the 'company-docs' corpus"*
+          - Example: *"What files are in the corpus?"*
+        
+        - **🗑️ Delete Document/Corpus**: Remove documents or collections
+          - Example: *"Delete the document with ID XYZ from the corpus"*
+          - Example: *"Delete the 'old-docs' corpus"*
+        """)
+    
+    gr.Markdown("""
+    ---
+    💡 **Tip**: The agent automatically maintains conversation context within each chat session.
+    """)
+    
+    # Event handlers
+    def submit_message(message, history, agent_name):
+        history = chat_with_agent(message, history, agent_name)
+        return "", history
+    
+    submit_btn.click(
+        submit_message,
+        inputs=[msg, chatbot, agent_dropdown],
+        outputs=[msg, chatbot]
+    )
+    
+    msg.submit(
+        submit_message,
+        inputs=[msg, chatbot, agent_dropdown],
+        outputs=[msg, chatbot]
+    )
+    
+    clear_btn.click(
+        clear_chat_and_session,
+        inputs=[agent_dropdown],
+        outputs=chatbot
+    )
+    
+    refresh_btn.click(
+        refresh_agents,
+        outputs=agent_dropdown
+    )
+
+
+if __name__ == "__main__":
+    # Check if required environment variables are set
+    if not PROJECT_ID:
+        print("⚠️  Warning: GOOGLE_CLOUD_PROJECT environment variable not set")
+        print("Please set it in your rag_agent/.env file")
+        sys.exit(1)
+    
+    print("=" * 60)
+    print("🚀 Starting RAG Agent Chat UI (Gradio)")
+    print("=" * 60)
+    print(f"📍 Project ID: {PROJECT_ID}")
+    print(f"📍 Location: {LOCATION}")
+    
+    agents = get_agent_names()
+    print(f"🔍 Found {len([a for a in agents if 'No agents' not in a])} agent(s)")
+    
+    if agents and "No agents found" not in agents[0]:
+        print("\n✅ Available Agents:")
+        for agent in agents:
+            print(f"   • {agent}")
+    else:
+        print("\n⚠��  No agents found. Please deploy an agent first using: make deploy")
+    
+    print("\n" + "=" * 60)
+    print("🌐 Launching Gradio interface...")
+    print("=" * 60 + "\n")
+    
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=True,
+        show_error=True
+    )

notebooks/adk_app_testing.ipynb

@@ -0,0 +1,367 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 🧪 ADK Application Testing\n",
+    "\n",
+    "This notebook demonstrates how to test an ADK (Agent Development Kit) application.\n",
+    "It covers both local and remote testing, both with Agent Engine and Cloud Run.\n",
+    "\n",
+    "> **Note**: This notebook assumes that the agent files are stored in the `app` folder. If your agent files are located in a different directory, please update all relevant file paths and references accordingly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Set Up Your Environment\n",
+    "\n",
+    "> **Note:** For best results, use the same `.venv` created for local development with `uv` to ensure dependency compatibility and avoid environment-related issues."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Uncomment the following lines if you're not using the virtual environment created by uv\n",
+    "# import sys\n",
+    "\n",
+    "# sys.path.append(\"../\")\n",
+    "# !pip install google-cloud-aiplatform a2a-sdk --upgrade"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "\n",
+    "import requests\n",
+    "import vertexai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Initialize Vertex AI Client"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize the Vertex AI client\n",
+    "LOCATION = \"us-central1\"\n",
+    "\n",
+    "client = vertexai.Client(\n",
+    "    location=LOCATION,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## If you are using Agent Engine\n",
+    "See more documentation at [Agent Engine Overview](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Remote Testing"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Set to None to auto-detect from ./deployment_metadata.json, or specify manually\n",
+    "# \"projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID\"\n",
+    "REASONING_ENGINE_ID = None\n",
+    "\n",
+    "if REASONING_ENGINE_ID is None:\n",
+    "    try:\n",
+    "        with open(\"../deployment_metadata.json\") as f:\n",
+    "            metadata = json.load(f)\n",
+    "            REASONING_ENGINE_ID = metadata.get(\"remote_agent_engine_id\")\n",
+    "    except (FileNotFoundError, json.JSONDecodeError):\n",
+    "        pass\n",
+    "\n",
+    "print(f\"Using REASONING_ENGINE_ID: {REASONING_ENGINE_ID}\")\n",
+    "# Get the existing agent engine\n",
+    "remote_agent_engine = client.agent_engines.get(name=REASONING_ENGINE_ID)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "async for event in remote_agent_engine.async_stream_query(\n",
+    "    message=\"hi!\", user_id=\"test\"\n",
+    "):\n",
+    "    print(event)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "remote_agent_engine.register_feedback(\n    feedback={\n        \"score\": 5,\n        \"text\": \"Great response!\",\n        \"user_id\": \"test-user-123\",\n        \"session_id\": \"test-session-123\",\n    }\n)"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Local Testing\n",
+    "\n",
+    "You can import directly the AgentEngineApp class within your environment. \n",
+    "To run the agent locally, follow these steps:\n",
+    "1. Make sure all required packages are installed in your environment\n",
+    "2. The recommended approach is to use the same virtual environment created by the 'uv' tool\n",
+    "3. You can set up this environment by running 'make install' from your agent's root directory\n",
+    "4. Then select this kernel (.venv folder in your project) in your Jupyter notebook to ensure all dependencies are available"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from app.agent_engine_app import agent_engine\n",
+    "\n",
+    "agent_engine.set_up()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "async for event in agent_engine.async_stream_query(message=\"hi!\", user_id=\"test\"):\n",
+    "    print(event)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## If you are using Cloud Run"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Remote Testing\n",
+    "\n",
+    "For more information about authenticating HTTPS requests to Cloud Run services, see:\n",
+    "[Cloud Run Authentication Documentation](https://cloud.google.com/run/docs/triggering/https-request)\n",
+    "\n",
+    "Remote testing involves using a deployed service URL instead of localhost.\n",
+    "\n",
+    "Authentication is handled using GCP identity tokens instead of local credentials."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ID_TOKEN = get_ipython().getoutput(\"gcloud auth print-identity-token -q\")[0]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SERVICE_URL = \"YOUR_SERVICE_URL_HERE\"  # Replace with your Cloud Run service URL"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You'll need to first create a Session"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "user_id = \"test_user_123\"\n",
+    "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
+    "\n",
+    "session_url = f\"{SERVICE_URL}/apps/app/users/{user_id}/sessions\"\n",
+    "headers = {\"Content-Type\": \"application/json\", \"Authorization\": f\"Bearer {ID_TOKEN}\"}\n",
+    "\n",
+    "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then you will be able to send a message"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "message_data = {\n",
+    "    \"app_name\": \"app\",\n",
+    "    \"user_id\": user_id,\n",
+    "    \"session_id\": session_id,\n",
+    "    \"new_message\": {\"role\": \"user\", \"parts\": [{\"text\": \"Hello! Weather in New york?\"}]},\n",
+    "    \"streaming\": True,\n",
+    "}\n",
+    "\n",
+    "message_url = f\"{SERVICE_URL}/run_sse\"\n",
+    "message_response = requests.post(\n",
+    "    message_url, headers=headers, json=message_data, stream=True\n",
+    ")\n",
+    "\n",
+    "print(f\"Message send status code: {message_response.status_code}\")\n",
+    "\n",
+    "# Print streamed response\n",
+    "for line in message_response.iter_lines():\n",
+    "    if line:\n",
+    "        line_str = line.decode(\"utf-8\")\n",
+    "        if line_str.startswith(\"data: \"):\n",
+    "            event_json = line_str[6:]\n",
+    "            event = json.loads(event_json)\n",
+    "            print(f\"Received event: {event}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Local Testing\n",
+    "\n",
+    "> You can run the application locally via the `make local-backend` command."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Create a session\n",
+    " Create a new session with user preferences and state information\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "user_id = \"test_user_123\"\n",
+    "session_data = {\"state\": {\"preferred_language\": \"English\", \"visit_count\": 1}}\n",
+    "\n",
+    "session_url = f\"http://127.0.0.1:8000/apps/app/users/{user_id}/sessions\"\n",
+    "headers = {\"Content-Type\": \"application/json\"}\n",
+    "\n",
+    "session_response = requests.post(session_url, headers=headers, json=session_data)\n",
+    "print(f\"Session creation status code: {session_response.status_code}\")\n",
+    "print(f\"Session creation response: {session_response.json()}\")\n",
+    "session_id = session_response.json()[\"id\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Send a message\n",
+    "Send a message to the backend service and receive a streaming response\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "message_data = {\n",
+    "    \"app_name\": \"app\",\n",
+    "    \"user_id\": user_id,\n",
+    "    \"session_id\": session_id,\n",
+    "    \"new_message\": {\"role\": \"user\", \"parts\": [{\"text\": \"Hello! Weather in New york?\"}]},\n",
+    "    \"streaming\": True,\n",
+    "}\n",
+    "\n",
+    "message_url = \"http://127.0.0.1:8000/run_sse\"\n",
+    "message_response = requests.post(\n",
+    "    message_url, headers=headers, json=message_data, stream=True\n",
+    ")\n",
+    "\n",
+    "print(f\"Message send status code: {message_response.status_code}\")\n",
+    "\n",
+    "# Print streamed response\n",
+    "for line in message_response.iter_lines():\n",
+    "    if line:\n",
+    "        line_str = line.decode(\"utf-8\")\n",
+    "        if line_str.startswith(\"data: \"):\n",
+    "            event_json = line_str[6:]\n",
+    "            event = json.loads(event_json)\n",
+    "            print(f\"Received event: {event}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "myagent-1762384391",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

notebooks/evaluating_adk_agent.ipynb

@@ -0,0 +1,1535 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "ur8xi4C7S06n"
+      },
+      "outputs": [],
+      "source": [
+        "# Copyright 2025 Google LLC\n",
+        "#\n",
+        "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
+        "# you may not use this file except in compliance with the License.\n",
+        "# You may obtain a copy of the License at\n",
+        "#\n",
+        "#     https://www.apache.org/licenses/LICENSE-2.0\n",
+        "#\n",
+        "# Unless required by applicable law or agreed to in writing, software\n",
+        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
+        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
+        "# See the License for the specific language governing permissions and\n",
+        "# limitations under the License."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "JAPoU8Sm5E6e"
+      },
+      "source": [
+        "# Evaluate your ADK agent using Vertex AI Gen AI Evaluation service\n",
+        "\n",
+        "<table align=\"left\">\n",
+        "  <td style=\"text-align: center\">\n",
+        "    <a href=\"https://colab.research.google.com/github/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\">\n",
+        "      <img width=\"32px\" src=\"https://www.gstatic.com/pantheon/images/bigquery/welcome_page/colab-logo.svg\" alt=\"Google Colaboratory logo\"><br> Open in Colab\n",
+        "    </a>\n",
+        "  </td>\n",
+        "  <td style=\"text-align: center\">\n",
+        "    <a href=\"https://console.cloud.google.com/vertex-ai/colab/import/https:%2F%2Fraw.githubusercontent.com%2FGoogleCloudPlatform%2Fgenerative-ai%2Fmain%2Fgemini%2Fevaluation%2Fevaluating_adk_agent.ipynb\">\n",
+        "      <img width=\"32px\" src=\"https://lh3.googleusercontent.com/JmcxdQi-qOpctIvWKgPtrzZdJJK-J3sWE1RsfjZNwshCFgE_9fULcNpuXYTilIR2hjwN\" alt=\"Google Cloud Colab Enterprise logo\"><br> Open in Colab Enterprise\n",
+        "    </a>\n",
+        "  </td>\n",
+        "  <td style=\"text-align: center\">\n",
+        "    <a href=\"https://console.cloud.google.com/vertex-ai/workbench/deploy-notebook?download_url=https://raw.githubusercontent.com/GoogleCloudPlatform/generative-ai/main/gemini/evaluation/evaluating_adk_agent.ipynb\">\n",
+        "      <img src=\"https://www.gstatic.com/images/branding/gcpiconscolors/vertexai/v1/32px.svg\" alt=\"Vertex AI logo\"><br> Open in Vertex AI Workbench\n",
+        "    </a>\n",
+        "  </td>\n",
+        "  <td style=\"text-align: center\">\n",
+        "    <a href=\"https://github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\">\n",
+        "      <img width=\"32px\" src=\"https://www.svgrepo.com/download/217753/github.svg\" alt=\"GitHub logo\"><br> View on GitHub\n",
+        "    </a>\n",
+        "  </td>\n",
+        "</table>\n",
+        "\n",
+        "<div style=\"clear: both;\"></div>\n",
+        "\n",
+        "<b>Share to:</b>\n",
+        "\n",
+        "<a href=\"https://www.linkedin.com/sharing/share-offsite/?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\" target=\"_blank\">\n",
+        "  <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/8/81/LinkedIn_icon.svg\" alt=\"LinkedIn logo\">\n",
+        "</a>\n",
+        "\n",
+        "<a href=\"https://bsky.app/intent/compose?text=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\" target=\"_blank\">\n",
+        "  <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/7/7a/Bluesky_Logo.svg\" alt=\"Bluesky logo\">\n",
+        "</a>\n",
+        "\n",
+        "<a href=\"https://twitter.com/intent/tweet?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\" target=\"_blank\">\n",
+        "  <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/5/5a/X_icon_2.svg\" alt=\"X logo\">\n",
+        "</a>\n",
+        "\n",
+        "<a href=\"https://reddit.com/submit?url=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\" target=\"_blank\">\n",
+        "  <img width=\"20px\" src=\"https://redditinc.com/hubfs/Reddit%20Inc/Brand/Reddit_Logo.png\" alt=\"Reddit logo\">\n",
+        "</a>\n",
+        "\n",
+        "<a href=\"https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/evaluation/evaluating_adk_agent.ipynb\" target=\"_blank\">\n",
+        "  <img width=\"20px\" src=\"https://upload.wikimedia.org/wikipedia/commons/5/51/Facebook_f_logo_%282019%29.svg\" alt=\"Facebook logo\">\n",
+        "</a>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "84f0f73a0f76"
+      },
+      "source": [
+        "| Author(s) |\n",
+        "| --- |\n",
+        "| [Ivan Nardini](https://github.com/inardini) |"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "tvgnzT1CKxrO"
+      },
+      "source": [
+        "## Overview\n",
+        "\n",
+        "Agent Development Kit (ADK in short) is a flexible and modular open source framework for developing and deploying AI agents. While ADK has its own evaluation module, using Vertex AI Gen AI Evaluation provides a toolkit of quality controlled and explainable methods and metrics to evaluate any generative model or application, including agents, and benchmark the evaluation results against your own judgment, using your own evaluation criteria.\n",
+        "\n",
+        "This tutorial shows how to evaluate an ADK agent using Vertex AI Gen AI Evaluation for agent evaluation.\n",
+        "\n",
+        "The steps performed include:\n",
+        "\n",
+        "* Build local agent using ADK\n",
+        "* Prepare Agent Evaluation dataset\n",
+        "* Single tool usage evaluation\n",
+        "* Trajectory evaluation\n",
+        "* Response evaluation"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "61RBz8LLbxCR"
+      },
+      "source": [
+        "## Get started"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "No17Cw5hgx12"
+      },
+      "source": [
+        "### Install Google Gen AI SDK and other required packages\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "tFy3H3aPgx12"
+      },
+      "outputs": [],
+      "source": [
+        "%pip install --upgrade --quiet 'google-adk'\n",
+        "%pip install --upgrade --quiet 'google-cloud-aiplatform[evaluation]'"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "dmWOrTJ3gx13"
+      },
+      "source": [
+        "### Authenticate your notebook environment (Colab only)\n",
+        "\n",
+        "If you're running this notebook on Google Colab, run the cell below to authenticate your environment."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "NyKGtVQjgx13"
+      },
+      "outputs": [],
+      "source": [
+        "import sys\n",
+        "\n",
+        "if \"google.colab\" in sys.modules:\n",
+        "    from google.colab import auth\n",
+        "\n",
+        "    auth.authenticate_user()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DF4l8DTdWgPY"
+      },
+      "source": [
+        "### Set Google Cloud project information\n",
+        "\n",
+        "To get started using Vertex AI, you must have an existing Google Cloud project and [enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).\n",
+        "\n",
+        "Learn more about [setting up a project and a development environment](https://cloud.google.com/vertex-ai/docs/start/cloud-environment)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "Nqwi-5ufWp_B"
+      },
+      "outputs": [],
+      "source": [
+        "# Use the environment variable if the user doesn't provide Project ID.\n",
+        "import os\n",
+        "\n",
+        "import vertexai\n",
+        "\n",
+        "PROJECT_ID = \"[your-project-id]\"  # @param {type: \"string\", placeholder: \"[your-project-id]\", isTemplate: true}\n",
+        "if not PROJECT_ID or PROJECT_ID == \"[your-project-id]\":\n",
+        "    PROJECT_ID = str(os.environ.get(\"GOOGLE_CLOUD_PROJECT\"))\n",
+        "\n",
+        "LOCATION = os.environ.get(\"GOOGLE_CLOUD_REGION\", \"us-central1\")\n",
+        "\n",
+        "BUCKET_NAME = \"[your-bucket-name]\"  # @param {type: \"string\", placeholder: \"[your-bucket-name]\", isTemplate: true}\n",
+        "BUCKET_URI = f\"gs://{BUCKET_NAME}\"\n",
+        "\n",
+        "!gsutil mb -l {LOCATION} {BUCKET_URI}\n",
+        "\n",
+        "os.environ[\"GOOGLE_CLOUD_PROJECT\"] = PROJECT_ID\n",
+        "os.environ[\"GOOGLE_CLOUD_LOCATION\"] = LOCATION\n",
+        "os.environ[\"GOOGLE_GENAI_USE_VERTEXAI\"] = \"True\"\n",
+        "\n",
+        "EXPERIMENT_NAME = \"evaluate-adk-agent\"  # @param {type:\"string\"}\n",
+        "\n",
+        "vertexai.init(project=PROJECT_ID, location=LOCATION, experiment=EXPERIMENT_NAME)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "5303c05f7aa6"
+      },
+      "source": [
+        "## Import libraries\n",
+        "\n",
+        "Import tutorial libraries."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "6fc324893334"
+      },
+      "outputs": [],
+      "source": [
+        "import json\n",
+        "import asyncio\n",
+        "\n",
+        "# General\n",
+        "import random\n",
+        "import string\n",
+        "from typing import Any\n",
+        "\n",
+        "from IPython.display import HTML, Markdown, display\n",
+        "from google.adk.agents import Agent\n",
+        "\n",
+        "# Build agent with adk\n",
+        "from google.adk.events import Event\n",
+        "from google.adk.runners import Runner\n",
+        "from google.adk.sessions import InMemorySessionService\n",
+        "\n",
+        "# Evaluate agent\n",
+        "from google.cloud import aiplatform\n",
+        "from google.genai import types\n",
+        "import pandas as pd\n",
+        "import plotly.graph_objects as go\n",
+        "from vertexai.preview.evaluation import EvalTask\n",
+        "from vertexai.preview.evaluation.metrics import (\n",
+        "    PointwiseMetric,\n",
+        "    PointwiseMetricPromptTemplate,\n",
+        "    TrajectorySingleToolUse,\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "MVnBDX54gz7j"
+      },
+      "source": [
+        "## Define helper functions\n",
+        "\n",
+        "Initiate a set of helper functions to print tutorial results."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "uSgWjMD_g1_v"
+      },
+      "outputs": [],
+      "source": [
+        "def get_id(length: int = 8) -> str:\n",
+        "    \"\"\"Generate a uuid of a specified length (default=8).\"\"\"\n",
+        "    return \"\".join(random.choices(string.ascii_lowercase + string.digits, k=length))\n",
+        "\n",
+        "\n",
+        "def parse_adk_output_to_dictionary(events: list[Event], *, as_json: bool = False):\n",
+        "    \"\"\"\n",
+        "    Parse ADK event output into a structured dictionary format,\n",
+        "    with the predicted trajectory dumped as a JSON string.\n",
+        "\n",
+        "    \"\"\"\n",
+        "\n",
+        "    final_response = \"\"\n",
+        "    trajectory = []\n",
+        "\n",
+        "    for event in events:\n",
+        "        if not getattr(event, \"content\", None) or not getattr(event.content, \"parts\", None):\n",
+        "            continue\n",
+        "        for part in event.content.parts:\n",
+        "            if getattr(part, \"function_call\", None):\n",
+        "                info = {\n",
+        "                    \"tool_name\": part.function_call.name,\n",
+        "                    \"tool_input\": dict(part.function_call.args),\n",
+        "                }\n",
+        "                if info not in trajectory:\n",
+        "                    trajectory.append(info)\n",
+        "            if event.content.role == \"model\" and getattr(part, \"text\", None):\n",
+        "                final_response = part.text.strip()\n",
+        "\n",
+        "    if as_json:\n",
+        "        trajectory_out = json.dumps(trajectory)\n",
+        "    else:\n",
+        "        trajectory_out = trajectory\n",
+        "\n",
+        "    return {\"response\": final_response, \"predicted_trajectory\": trajectory_out}\n",
+        "\n",
+        "\n",
+        "def format_output_as_markdown(output: dict) -> str:\n",
+        "    \"\"\"Convert the output dictionary to a formatted markdown string.\"\"\"\n",
+        "    markdown = \"### AI Response\\n\" + output[\"response\"] + \"\\n\\n\"\n",
+        "    if output[\"predicted_trajectory\"]:\n",
+        "        markdown += \"### Function Calls\\n\"\n",
+        "        for call in output[\"predicted_trajectory\"]:\n",
+        "            markdown += f\"- **Function**: `{call['tool_name']}`\\n\"\n",
+        "            markdown += \"  - **Arguments**\\n\"\n",
+        "            for key, value in call[\"tool_input\"].items():\n",
+        "                markdown += f\"    - `{key}`: `{value}`\\n\"\n",
+        "    return markdown\n",
+        "\n",
+        "\n",
+        "def display_eval_report(eval_result: pd.DataFrame) -> None:\n",
+        "    \"\"\"Display the evaluation results.\"\"\"\n",
+        "    display(Markdown(\"### Summary Metrics\"))\n",
+        "    display(\n",
+        "        pd.DataFrame(\n",
+        "            eval_result.summary_metrics.items(), columns=[\"metric\", \"value\"]\n",
+        "        )\n",
+        "    )\n",
+        "    if getattr(eval_result, \"metrics_table\", None) is not None:\n",
+        "        display(Markdown(\"### Row‑wise Metrics\"))\n",
+        "        display(eval_result.metrics_table.head())\n",
+        "\n",
+        "\n",
+        "def display_drilldown(row: pd.Series) -> None:\n",
+        "    \"\"\"Displays a drill-down view for trajectory data within a row.\"\"\"\n",
+        "\n",
+        "    style = \"white-space: pre-wrap; width: 800px; overflow-x: auto;\"\n",
+        "\n",
+        "    if not (\n",
+        "        isinstance(row[\"predicted_trajectory\"], list)\n",
+        "        and isinstance(row[\"reference_trajectory\"], list)\n",
+        "    ):\n",
+        "        return\n",
+        "\n",
+        "    for predicted_trajectory, reference_trajectory in zip(\n",
+        "        row[\"predicted_trajectory\"], row[\"reference_trajectory\"]\n",
+        "    ):\n",
+        "        display(\n",
+        "            HTML(\n",
+        "                f\"<h3>Tool Names:</h3><div style='{style}'>{predicted_trajectory['tool_name'], reference_trajectory['tool_name']}</div>\"\n",
+        "            )\n",
+        "        )\n",
+        "\n",
+        "        if not (\n",
+        "            isinstance(predicted_trajectory.get(\"tool_input\"), dict)\n",
+        "            and isinstance(reference_trajectory.get(\"tool_input\"), dict)\n",
+        "        ):\n",
+        "            continue\n",
+        "\n",
+        "        for tool_input_key in predicted_trajectory[\"tool_input\"]:\n",
+        "            print(\"Tool Input Key: \", tool_input_key)\n",
+        "\n",
+        "            if tool_input_key in reference_trajectory[\"tool_input\"]:\n",
+        "                print(\n",
+        "                    \"Tool Values: \",\n",
+        "                    predicted_trajectory[\"tool_input\"][tool_input_key],\n",
+        "                    reference_trajectory[\"tool_input\"][tool_input_key],\n",
+        "                )\n",
+        "            else:\n",
+        "                print(\n",
+        "                    \"Tool Values: \",\n",
+        "                    predicted_trajectory[\"tool_input\"][tool_input_key],\n",
+        "                    \"N/A\",\n",
+        "                )\n",
+        "        print(\"\\n\")\n",
+        "    display(HTML(\"<hr>\"))\n",
+        "\n",
+        "\n",
+        "def display_dataframe_rows(\n",
+        "    df: pd.DataFrame,\n",
+        "    columns: list[str] | None = None,\n",
+        "    num_rows: int = 3,\n",
+        "    display_drilldown: bool = False,\n",
+        ") -> None:\n",
+        "    \"\"\"Displays a subset of rows from a DataFrame, optionally including a drill-down view.\"\"\"\n",
+        "\n",
+        "    if columns:\n",
+        "        df = df[columns]\n",
+        "\n",
+        "    base_style = \"font-family: monospace; font-size: 14px; white-space: pre-wrap; width: auto; overflow-x: auto;\"\n",
+        "    header_style = base_style + \"font-weight: bold;\"\n",
+        "\n",
+        "    for _, row in df.head(num_rows).iterrows():\n",
+        "        for column in df.columns:\n",
+        "            display(\n",
+        "                HTML(\n",
+        "                    f\"<span style='{header_style}'>{column.replace('_', ' ').title()}: </span>\"\n",
+        "                )\n",
+        "            )\n",
+        "            display(HTML(f\"<span style='{base_style}'>{row[column]}</span><br>\"))\n",
+        "\n",
+        "        display(HTML(\"<hr>\"))\n",
+        "\n",
+        "        if (\n",
+        "            display_drilldown\n",
+        "            and \"predicted_trajectory\" in df.columns\n",
+        "            and \"reference_trajectory\" in df.columns\n",
+        "        ):\n",
+        "            display_drilldown(row)\n",
+        "\n",
+        "\n",
+        "def plot_bar_plot(\n",
+        "    eval_result: pd.DataFrame, title: str, metrics: list[str] = None\n",
+        ") -> None:\n",
+        "    fig = go.Figure()\n",
+        "    data = []\n",
+        "\n",
+        "    summary_metrics = eval_result.summary_metrics\n",
+        "    if metrics:\n",
+        "        summary_metrics = {\n",
+        "            k: summary_metrics[k]\n",
+        "            for k, v in summary_metrics.items()\n",
+        "            if any(selected_metric in k for selected_metric in metrics)\n",
+        "        }\n",
+        "\n",
+        "    data.append(\n",
+        "        go.Bar(\n",
+        "            x=list(summary_metrics.keys()),\n",
+        "            y=list(summary_metrics.values()),\n",
+        "            name=title,\n",
+        "        )\n",
+        "    )\n",
+        "\n",
+        "    fig = go.Figure(data=data)\n",
+        "\n",
+        "    # Change the bar mode\n",
+        "    fig.update_layout(barmode=\"group\")\n",
+        "    fig.show()\n",
+        "\n",
+        "\n",
+        "def display_radar_plot(eval_results, title: str, metrics=None):\n",
+        "    \"\"\"Plot the radar plot.\"\"\"\n",
+        "    fig = go.Figure()\n",
+        "    summary_metrics = eval_results.summary_metrics\n",
+        "    if metrics:\n",
+        "        summary_metrics = {\n",
+        "            k: summary_metrics[k]\n",
+        "            for k, v in summary_metrics.items()\n",
+        "            if any(selected_metric in k for selected_metric in metrics)\n",
+        "        }\n",
+        "\n",
+        "    min_val = min(summary_metrics.values())\n",
+        "    max_val = max(summary_metrics.values())\n",
+        "\n",
+        "    fig.add_trace(\n",
+        "        go.Scatterpolar(\n",
+        "            r=list(summary_metrics.values()),\n",
+        "            theta=list(summary_metrics.keys()),\n",
+        "            fill=\"toself\",\n",
+        "            name=title,\n",
+        "        )\n",
+        "    )\n",
+        "    fig.update_layout(\n",
+        "        title=title,\n",
+        "        polar=dict(radialaxis=dict(visible=True, range=[min_val, max_val])),\n",
+        "        showlegend=True,\n",
+        "    )\n",
+        "    fig.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "bDaa2Mtsifmq"
+      },
+      "source": [
+        "## Build ADK agent\n",
+        "\n",
+        "Build your application using ADK, including the Gemini model and custom tools that you define."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "KHwShhpOitKp"
+      },
+      "source": [
+        "### Set tools\n",
+        "\n",
+        "To start, set the tools that a customer support agent needs to do their job."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "gA2ZKvfeislw"
+      },
+      "outputs": [],
+      "source": [
+        "def get_product_details(product_name: str):\n",
+        "    \"\"\"Gathers basic details about a product.\"\"\"\n",
+        "    details = {\n",
+        "        \"smartphone\": \"A cutting-edge smartphone with advanced camera features and lightning-fast processing.\",\n",
+        "        \"usb charger\": \"A super fast and light usb charger\",\n",
+        "        \"shoes\": \"High-performance running shoes designed for comfort, support, and speed.\",\n",
+        "        \"headphones\": \"Wireless headphones with advanced noise cancellation technology for immersive audio.\",\n",
+        "        \"speaker\": \"A voice-controlled smart speaker that plays music, sets alarms, and controls smart home devices.\",\n",
+        "    }\n",
+        "    return details.get(product_name, \"Product details not found.\")\n",
+        "\n",
+        "\n",
+        "def get_product_price(product_name: str):\n",
+        "    \"\"\"Gathers price about a product.\"\"\"\n",
+        "    details = {\n",
+        "        \"smartphone\": 500,\n",
+        "        \"usb charger\": 10,\n",
+        "        \"shoes\": 100,\n",
+        "        \"headphones\": 50,\n",
+        "        \"speaker\": 80,\n",
+        "    }\n",
+        "    return details.get(product_name, \"Product price not found.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "l4mk5XPui4Y1"
+      },
+      "source": [
+        "### Set the model\n",
+        "\n",
+        "Choose which Gemini AI model your agent will use. If you're curious about Gemini and its different capabilities, take a look at [the official documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models) for more details."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "BaYeo6K2i-w1"
+      },
+      "outputs": [],
+      "source": [
+        "model = \"gemini-2.0-flash\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "tNlAY9cojEWz"
+      },
+      "source": [
+        "### Assemble the agent\n",
+        "\n",
+        "The Vertex AI Gen AI Evaluation works directly with 'Queryable' agents, and also lets you add your own custom functions with a specific structure (signature).\n",
+        "\n",
+        "In this case, you assemble the agent using a custom function. The function triggers the agent for a given input and parse the agent outcome to extract the response and called tools."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "gD5OB44g4sc3"
+      },
+      "outputs": [],
+      "source": [
+        "async def agent_parsed_outcome(query):\n",
+        "   app_name = \"product_research_app\"\n",
+        "   user_id = \"user_one\"\n",
+        "   session_id = \"session_one\"\n",
+        "   \n",
+        "   product_research_agent = Agent(\n",
+        "       name=\"ProductResearchAgent\",\n",
+        "       model=model,\n",
+        "       description=\"An agent that performs product research.\",\n",
+        "       instruction=f\"\"\"\n",
+        "       Analyze this user request: '{query}'.\n",
+        "       If the request is about price, use get_product_price tool.\n",
+        "       Otherwise, use get_product_details tool to get product information.\n",
+        "       \"\"\",\n",
+        "       tools=[get_product_details, get_product_price],\n",
+        "   )\n",
+        "\n",
+        "   session_service = InMemorySessionService()\n",
+        "   await session_service.create_session(\n",
+        "       app_name=app_name, user_id=user_id, session_id=session_id\n",
+        "   )\n",
+        "\n",
+        "   runner = Runner(\n",
+        "       agent=product_research_agent, app_name=app_name, session_service=session_service\n",
+        "   )\n",
+        "\n",
+        "   content = types.Content(role=\"user\", parts=[types.Part(text=query)])\n",
+        "   events = [event async for event in runner.run_async(user_id=user_id, session_id=session_id, new_message=content)]\n",
+        "   \n",
+        "   return parse_adk_output_to_dictionary(events)\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# --- Sync wrapper for Vertex‑AI evaluation\n",
+        "def agent_parsed_outcome_sync(prompt: str):\n",
+        "    result = asyncio.run(agent_parsed_outcome(prompt))\n",
+        "    result[\"predicted_trajectory\"] = json.dumps(result[\"predicted_trajectory\"])\n",
+        "    return result"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "_HGcs6PVjRj_"
+      },
+      "source": [
+        "### Test the agent\n",
+        "\n",
+        "Query your agent."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "lGb58OJkjUs9"
+      },
+      "outputs": [],
+      "source": [
+        "response = await agent_parsed_outcome(query=\"Get product details for shoes\")\n",
+        "display(Markdown(format_output_as_markdown(response)))"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "2wCFstt8w4Dx"
+      },
+      "outputs": [],
+      "source": [
+        "response = await agent_parsed_outcome(query=\"Get product price for shoes\")\n",
+        "display(Markdown(format_output_as_markdown(response)))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "aOGPePsorpUl"
+      },
+      "source": [
+        "## Evaluating a ADK agent with Vertex AI Gen AI Evaluation\n",
+        "\n",
+        "When working with AI agents, it's important to keep track of their performance and how well they're working. You can look at this in two main ways: **monitoring** and **observability**.\n",
+        "\n",
+        "Monitoring focuses on how well your agent is performing specific tasks:\n",
+        "\n",
+        "* **Single Tool Selection**: Is the agent choosing the right tools for the job?\n",
+        "\n",
+        "* **Multiple Tool Selection (or Trajectory)**: Is the agent making logical choices in the order it uses tools?\n",
+        "\n",
+        "* **Response generation**: Is the agent's output good, and does it make sense based on the tools it used?\n",
+        "\n",
+        "Observability is about understanding the overall health of the agent:\n",
+        "\n",
+        "* **Latency**: How long does it take the agent to respond?\n",
+        "\n",
+        "* **Failure Rate**: How often does the agent fail to produce a response?\n",
+        "\n",
+        "Vertex AI Gen AI Evaluation service helps you to assess all of these aspects both while you are prototyping the agent or after you deploy it in production. It provides [pre-built evaluation criteria and metrics](https://cloud.google.com/vertex-ai/generative-ai/docs/models/determine-eval) so you can see exactly how your agents are doing and identify areas for improvement."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "e43229f3ad4f"
+      },
+      "source": [
+        "### Prepare Agent Evaluation dataset\n",
+        "\n",
+        "To evaluate your AI agent using the Vertex AI Gen AI Evaluation service, you need a specific dataset depending on what aspects you want to evaluate of your agent.  \n",
+        "\n",
+        "This dataset should include the prompts given to the agent. It can also contain the ideal or expected response (ground truth) and the intended sequence of tool calls the agent should take (reference trajectory) representing the sequence of tools you expect agent calls for each given prompt.\n",
+        "\n",
+        "> Optionally, you can provide both generated responses and predicted trajectory (**Bring-Your-Own-Dataset scenario**).\n",
+        "\n",
+        "Below you have an example of dataset you might have with a customer support agent with user prompt and the reference trajectory."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "fFf8uTdUiDt3"
+      },
+      "outputs": [],
+      "source": [
+        "eval_data = {\n",
+        "    \"prompt\": [\n",
+        "        \"Get price for smartphone\",\n",
+        "        \"Get product details and price for headphones\",\n",
+        "        \"Get details for usb charger\",\n",
+        "        \"Get product details and price for shoes\",\n",
+        "        \"Get product details for speaker?\",\n",
+        "    ],\n",
+        "    \"predicted_trajectory\": [\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"smartphone\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"usb charger\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"shoes\"},\n",
+        "            },\n",
+        "            {\"tool_name\": \"get_product_price\", \"tool_input\": {\"product_name\": \"shoes\"}},\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"speaker\"},\n",
+        "            }\n",
+        "        ],\n",
+        "    ],\n",
+        "}\n",
+        "\n",
+        "eval_sample_dataset = pd.DataFrame(eval_data)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "PQEI1EcfvFHb"
+      },
+      "source": [
+        "Print some samples from the dataset."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "EjsonqWWvIvE"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(eval_sample_dataset, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "m4CvBuf1afHG"
+      },
+      "source": [
+        "### Single tool usage evaluation\n",
+        "\n",
+        "After you've set your AI agent and the evaluation dataset, you start evaluating if the agent is choosing the correct single tool for a given task.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "_rS5GGKHd5bx"
+      },
+      "source": [
+        "#### Set single tool usage metrics\n",
+        "\n",
+        "The `trajectory_single_tool_use` metric in Vertex AI Gen AI Evaluation gives you a quick way to evaluate whether your agent is using the tool you expect it to use, regardless of any specific tool order. It's a basic but useful way to start evaluating if the right tool was used at some point during the agent's process.\n",
+        "\n",
+        "To use the `trajectory_single_tool_use` metric, you need to set what tool should have been used for a particular user's request. For example, if a user asks to \"send an email\", you might expect the agent to use an \"send_email\" tool, and you'd specify that tool's name when using this metric.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "xixvq8dwd5by"
+      },
+      "outputs": [],
+      "source": [
+        "single_tool_usage_metrics = [TrajectorySingleToolUse(tool_name=\"get_product_price\")]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "ktKZoT2Qd5by"
+      },
+      "source": [
+        "#### Run an evaluation task\n",
+        "\n",
+        "To run the evaluation, you initiate an `EvalTask` using the pre-defined dataset (`eval_sample_dataset`) and metrics (`single_tool_usage_metrics` in this case) within an experiment. Then, you run the evaluation using agent_parsed_outcome function and assigns a unique identifier to this specific evaluation run, storing and visualizing the evaluation results.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "SRv43fDcd5by"
+      },
+      "outputs": [],
+      "source": [
+        "EXPERIMENT_RUN = f\"single-metric-eval-{get_id()}\"\n",
+        "\n",
+        "single_tool_call_eval_task = EvalTask(\n",
+        "    dataset=eval_sample_dataset,\n",
+        "    metrics=single_tool_usage_metrics,\n",
+        "    experiment=EXPERIMENT_NAME,\n",
+        "    output_uri_prefix=BUCKET_URI + \"/single-metric-eval\",\n",
+        ")\n",
+        "\n",
+        "single_tool_call_eval_result = single_tool_call_eval_task.evaluate(\n",
+        "    runnable=agent_parsed_outcome_sync, experiment_run_name=EXPERIMENT_RUN\n",
+        ")\n",
+        "\n",
+        "display_eval_report(single_tool_call_eval_result)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "6o5BjSTFKVMS"
+      },
+      "source": [
+        "#### Visualize evaluation results\n",
+        "\n",
+        "Use some helper functions to visualize a sample of evaluation result."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "1Jopzw83k14w"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(single_tool_call_eval_result.metrics_table, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "JlujdJpu5Kn6"
+      },
+      "source": [
+        "### Trajectory Evaluation\n",
+        "\n",
+        "After evaluating the agent's ability to select the single most appropriate tool for a given task, you generalize the evaluation by analyzing the tool sequence choices with respect to the user input (trajectory). This assesses whether the agent not only chooses the right tools but also utilizes them in a rational and effective order."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "8s-nHdDJneHM"
+      },
+      "source": [
+        "#### Set trajectory metrics\n",
+        "\n",
+        "To evaluate agent's trajectory, Vertex AI Gen AI Evaluation provides several ground-truth based metrics:\n",
+        "\n",
+        "* `trajectory_exact_match`: identical trajectories (same actions, same order)\n",
+        "\n",
+        "* `trajectory_in_order_match`: reference actions present in predicted trajectory, in order (extras allowed)\n",
+        "\n",
+        "* `trajectory_any_order_match`: all reference actions present in predicted trajectory (order, extras don't matter).\n",
+        "\n",
+        "* `trajectory_precision`: proportion of predicted actions present in reference\n",
+        "\n",
+        "* `trajectory_recall`: proportion of reference actions present in predicted.  \n",
+        "\n",
+        "All metrics score 0 or 1, except `trajectory_precision` and `trajectory_recall` which range from 0 to 1."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "c32WIS95neHN"
+      },
+      "outputs": [],
+      "source": [
+        "trajectory_metrics = [\n",
+        "    \"trajectory_exact_match\",\n",
+        "    \"trajectory_in_order_match\",\n",
+        "    \"trajectory_any_order_match\",\n",
+        "    \"trajectory_precision\",\n",
+        "    \"trajectory_recall\",\n",
+        "]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DF3jhTH3neHN"
+      },
+      "source": [
+        "#### Run an evaluation task\n",
+        "\n",
+        "Submit an evaluation by running `evaluate` method of the new `EvalTask`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "vOdS7TJUneHN"
+      },
+      "outputs": [],
+      "source": [
+        "EXPERIMENT_RUN = f\"trajectory-{get_id()}\"\n",
+        "\n",
+        "trajectory_eval_task = EvalTask(\n",
+        "    dataset=eval_sample_dataset,\n",
+        "    metrics=trajectory_metrics,\n",
+        "    experiment=EXPERIMENT_NAME,\n",
+        "    output_uri_prefix=BUCKET_URI + \"/multiple-metric-eval\",\n",
+        ")\n",
+        "\n",
+        "trajectory_eval_result = trajectory_eval_task.evaluate(\n",
+        "    runnable=agent_parsed_outcome_sync, experiment_run_name=EXPERIMENT_RUN\n",
+        ")\n",
+        "\n",
+        "display_eval_report(trajectory_eval_result)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DBiUI3LyLBtj"
+      },
+      "source": [
+        "#### Visualize evaluation results\n",
+        "\n",
+        "Print and visualize a sample of evaluation results."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "z7-LdM3mLBtk"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(trajectory_eval_result.metrics_table, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "sLVRdN5llA0h"
+      },
+      "outputs": [],
+      "source": [
+        "plot_bar_plot(\n",
+        "    trajectory_eval_result,\n",
+        "    title=\"Trajectory Metrics\",\n",
+        "    metrics=[f\"{metric}/mean\" for metric in trajectory_metrics],\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "T8TipU2akHEd"
+      },
+      "source": [
+        "### Evaluate final response\n",
+        "\n",
+        "Similar to model evaluation, you can evaluate the final response of the agent using Vertex AI Gen AI Evaluation."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DeK-py7ykkDN"
+      },
+      "source": [
+        "#### Set response metrics\n",
+        "\n",
+        "After agent inference, Vertex AI Gen AI Evaluation provides several metrics to evaluate generated responses. You can use computation-based metrics to compare the response to a reference (if needed) and using existing or custom model-based metrics to determine the quality of the final response.\n",
+        "\n",
+        "Check out the [documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/determine-eval) to learn more.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "cyGHGgeVklvz"
+      },
+      "outputs": [],
+      "source": [
+        "response_metrics = [\"safety\", \"coherence\"]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DaBJWcg1kn55"
+      },
+      "source": [
+        "#### Run an evaluation task\n",
+        "\n",
+        "To evaluate agent's generated responses, use the `evaluate` method of the EvalTask class."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "wRb2EC_hknSD"
+      },
+      "outputs": [],
+      "source": [
+        "EXPERIMENT_RUN = f\"response-{get_id()}\"\n",
+        "\n",
+        "response_eval_task = EvalTask(\n",
+        "    dataset=eval_sample_dataset,\n",
+        "    metrics=response_metrics,\n",
+        "    experiment=EXPERIMENT_NAME,\n",
+        "    output_uri_prefix=BUCKET_URI + \"/response-metric-eval\",\n",
+        ")\n",
+        "\n",
+        "response_eval_result = response_eval_task.evaluate(\n",
+        "    runnable=agent_parsed_outcome_sync, experiment_run_name=EXPERIMENT_RUN\n",
+        ")\n",
+        "\n",
+        "display_eval_report(response_eval_result)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "JtewTwiwg9qH"
+      },
+      "source": [
+        "#### Visualize evaluation results\n",
+        "\n",
+        "\n",
+        "Print new evaluation result sample."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "ZODTRuq2lF75"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(response_eval_result.metrics_table, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "ntRBK3Te6PEc"
+      },
+      "source": [
+        "### Evaluate generated response conditioned by tool choosing\n",
+        "\n",
+        "When evaluating AI agents that interact with environments, standard text generation metrics like coherence may not be sufficient. This is because these metrics primarily focus on text structure, while agent responses should be assessed based on their effectiveness within the environment.\n",
+        "\n",
+        "Instead, use custom metrics that assess whether the agent's response logically follows from its tools choices like the one you have in this section."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "4bENwFcd6prX"
+      },
+      "source": [
+        "#### Define a custom metric\n",
+        "\n",
+        "According to the [documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/determine-eval#model-based-metrics), you can define a prompt template for evaluating whether an AI agent's response follows logically from its actions by setting up criteria and a rating system for this evaluation.\n",
+        "\n",
+        "Define a `criteria` to set the evaluation guidelines and a `pointwise_rating_rubric` to provide a scoring system (1 or 0). Then use a `PointwiseMetricPromptTemplate` to create the template using these components.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "txGEHcg76riI"
+      },
+      "outputs": [],
+      "source": [
+        "criteria = {\n",
+        "    \"Follows trajectory\": (\n",
+        "        \"Evaluate whether the agent's response logically follows from the \"\n",
+        "        \"sequence of actions it took. Consider these sub-points:\\n\"\n",
+        "        \"  - Does the response reflect the information gathered during the trajectory?\\n\"\n",
+        "        \"  - Is the response consistent with the goals and constraints of the task?\\n\"\n",
+        "        \"  - Are there any unexpected or illogical jumps in reasoning?\\n\"\n",
+        "        \"Provide specific examples from the trajectory and response to support your evaluation.\"\n",
+        "    )\n",
+        "}\n",
+        "\n",
+        "pointwise_rating_rubric = {\n",
+        "    \"1\": \"Follows trajectory\",\n",
+        "    \"0\": \"Does not follow trajectory\",\n",
+        "}\n",
+        "\n",
+        "response_follows_trajectory_prompt_template = PointwiseMetricPromptTemplate(\n",
+        "    criteria=criteria,\n",
+        "    rating_rubric=pointwise_rating_rubric,\n",
+        "    input_variables=[\"prompt\", \"predicted_trajectory\"],\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "8MJqXu0kikxd"
+      },
+      "source": [
+        "Print the prompt_data of this template containing the combined criteria and rubric information ready for use in an evaluation."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "5EL7iEDMikNQ"
+      },
+      "outputs": [],
+      "source": [
+        "print(response_follows_trajectory_prompt_template.prompt_data)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "e1djVp7Fi4Yy"
+      },
+      "source": [
+        "After you define the evaluation prompt template, set up the associated metric to evaluate how well a response follows a specific trajectory. The `PointwiseMetric` creates a metric where `response_follows_trajectory` is the metric's name and `response_follows_trajectory_prompt_template` provides instructions or context for evaluation you set up before.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "Nx1xbZD87iMj"
+      },
+      "outputs": [],
+      "source": [
+        "response_follows_trajectory_metric = PointwiseMetric(\n",
+        "    metric=\"response_follows_trajectory\",\n",
+        "    metric_prompt_template=response_follows_trajectory_prompt_template,\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "1pmxLwTe7Ywv"
+      },
+      "source": [
+        "#### Set response metrics\n",
+        "\n",
+        "Set new generated response evaluation metrics by including the custom metric.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "wrsbVFDd7Ywv"
+      },
+      "outputs": [],
+      "source": [
+        "response_tool_metrics = [\n",
+        "    \"trajectory_exact_match\",\n",
+        "    \"trajectory_in_order_match\",\n",
+        "    \"safety\",\n",
+        "    response_follows_trajectory_metric,\n",
+        "]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "Lo-Sza807Ywv"
+      },
+      "source": [
+        "#### Run an evaluation task\n",
+        "\n",
+        "Run a new agent's evaluation."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "_dkb4gSn7Ywv"
+      },
+      "outputs": [],
+      "source": [
+        "EXPERIMENT_RUN = f\"response-over-tools-{get_id()}\"\n",
+        "\n",
+        "response_eval_tool_task = EvalTask(\n",
+        "    dataset=eval_sample_dataset,\n",
+        "    metrics=response_tool_metrics,\n",
+        "    experiment=EXPERIMENT_NAME,\n",
+        "    output_uri_prefix=BUCKET_URI + \"/reasoning-metric-eval\",\n",
+        ")\n",
+        "\n",
+        "response_eval_tool_result = response_eval_tool_task.evaluate(\n",
+        "    # Uncomment the line below if you are providing the agent with an unparsed dataset\n",
+        "    #runnable=agent_parsed_outcome_sync, \n",
+        "    experiment_run_name=EXPERIMENT_RUN\n",
+        ")\n",
+        "\n",
+        "display_eval_report(response_eval_tool_result)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "AtOfIFi2j88g"
+      },
+      "source": [
+        "#### Visualize evaluation results\n",
+        "\n",
+        "Visualize evaluation result sample."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "GH2YvXgLlLH7"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(response_eval_tool_result.metrics_table, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "tdVhCURXMdLG"
+      },
+      "outputs": [],
+      "source": [
+        "plot_bar_plot(\n",
+        "    response_eval_tool_result,\n",
+        "    title=\"Response Metrics\",\n",
+        "    metrics=[f\"{metric}/mean\" for metric in response_tool_metrics],\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "4nuUDP3a2eTB"
+      },
+      "source": [
+        "## Bonus: Bring-Your-Own-Dataset (BYOD) and evaluate a LangGraph agent using Vertex AI Gen AI Evaluation\n",
+        "\n",
+        "In Bring Your Own Dataset (BYOD) [scenarios](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-dataset), you provide both the predicted trajectory and the generated response from the agent.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "DRLKlmWd27PK"
+      },
+      "source": [
+        "### Bring your own evaluation dataset\n",
+        "\n",
+        "Define the evaluation dataset with the predicted trajectory and the generated response."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "y9hBgsg324Ej"
+      },
+      "outputs": [],
+      "source": [
+        "byod_eval_data = {\n",
+        "    \"prompt\": [\n",
+        "        \"Get price for smartphone\",\n",
+        "        \"Get product details and price for headphones\",\n",
+        "        \"Get details for usb charger\",\n",
+        "        \"Get product details and price for shoes\",\n",
+        "        \"Get product details for speaker?\",\n",
+        "    ],\n",
+        "    \"reference_trajectory\": [\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"smartphone\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"usb charger\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"shoes\"},\n",
+        "            },\n",
+        "            {\"tool_name\": \"get_product_price\", \"tool_input\": {\"product_name\": \"shoes\"}},\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"speaker\"},\n",
+        "            }\n",
+        "        ],\n",
+        "    ],\n",
+        "    \"predicted_trajectory\": [\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"smartphone\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_price\",\n",
+        "                \"tool_input\": {\"product_name\": \"headphones\"},\n",
+        "            },\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"usb charger\"},\n",
+        "            }\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"shoes\"},\n",
+        "            },\n",
+        "            {\"tool_name\": \"get_product_price\", \"tool_input\": {\"product_name\": \"shoes\"}},\n",
+        "        ],\n",
+        "        [\n",
+        "            {\n",
+        "                \"tool_name\": \"get_product_details\",\n",
+        "                \"tool_input\": {\"product_name\": \"speaker\"},\n",
+        "            }\n",
+        "        ],\n",
+        "    ],\n",
+        "    \"response\": [\n",
+        "        \"500\",\n",
+        "        \"50\",\n",
+        "        \"A super fast and light usb charger\",\n",
+        "        \"100\",\n",
+        "        \"A voice-controlled smart speaker that plays music, sets alarms, and controls smart home devices.\",\n",
+        "    ],\n",
+        "}\n",
+        "\n",
+        "byod_eval_sample_dataset = pd.DataFrame(byod_eval_data)\n",
+        "byod_eval_sample_dataset[\"predicted_trajectory\"] = byod_eval_sample_dataset[\n",
+        "    \"predicted_trajectory\"\n",
+        "].apply(json.dumps)\n",
+        "byod_eval_sample_dataset[\"reference_trajectory\"] = byod_eval_sample_dataset[\n",
+        "    \"reference_trajectory\"\n",
+        "].apply(json.dumps)\n",
+        "byod_eval_sample_dataset[\"response\"] = byod_eval_sample_dataset[\"response\"].apply(json.dumps)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "oEYmU2eJ7q-1"
+      },
+      "source": [
+        "### Run an evaluation task\n",
+        "\n",
+        "Run a new agent's evaluation using your own dataset and the same setting of the latest evaluation."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "wBD-4wpB7q-3"
+      },
+      "outputs": [],
+      "source": [
+        "EXPERIMENT_RUN_NAME = f\"response-over-tools-byod-{get_id()}\"\n",
+        "\n",
+        "byod_response_eval_tool_task = EvalTask(\n",
+        "    dataset=byod_eval_sample_dataset,\n",
+        "    metrics=response_tool_metrics,\n",
+        "    experiment=EXPERIMENT_NAME,\n",
+        "    output_uri_prefix=BUCKET_URI + \"/byod-eval\",\n",
+        ")\n",
+        "\n",
+        "byod_response_eval_tool_result = byod_response_eval_tool_task.evaluate(\n",
+        "    experiment_run_name=EXPERIMENT_RUN_NAME\n",
+        ")\n",
+        "\n",
+        "display_eval_report(byod_response_eval_tool_result)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "9eU3LG6r7q-3"
+      },
+      "source": [
+        "### Visualize evaluation results\n",
+        "\n",
+        "Visualize evaluation result sample."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "pQFzmd2I7q-3"
+      },
+      "outputs": [],
+      "source": [
+        "display_dataframe_rows(byod_response_eval_tool_result.metrics_table, num_rows=3)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "84HiPDOkPseW"
+      },
+      "outputs": [],
+      "source": [
+        "display_radar_plot(\n",
+        "    byod_response_eval_tool_result,\n",
+        "    title=\"ADK agent evaluation\",\n",
+        "    metrics=[f\"{metric}/mean\" for metric in response_tool_metrics],\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "fIppkS2jq_Dn"
+      },
+      "source": [
+        "## Cleaning up\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "Ox2I3UfRlTOd"
+      },
+      "outputs": [],
+      "source": [
+        "delete_experiment = True\n",
+        "\n",
+        "if delete_experiment:\n",
+        "    try:\n",
+        "        experiment = aiplatform.Experiment(EXPERIMENT_NAME)\n",
+        "        experiment.delete(delete_backing_tensorboard_runs=True)\n",
+        "    except Exception as e:\n",
+        "        print(e)"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "evaluating_adk_agent.ipynb",
+      "toc_visible": true
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "adk-rag-agent"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Your Name", email = "your@email.com"},
+]
+dependencies = [
+    "google-adk>=1.15.0,<2.0.0",
+    "opentelemetry-instrumentation-google-genai>=0.1.0,<1.0.0",
+    "gcsfs>=2024.11.0",
+    "google-cloud-logging>=3.12.0,<4.0.0",
+    "google-cloud-aiplatform[evaluation,agent-engines]>=1.118.0,<2.0.0",
+    "protobuf>=6.31.1,<7.0.0",
+    "gradio>=5.49.1",
+]
+requires-python = ">=3.10,<3.14"
+
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4,<9.0.0",
+    "pytest-asyncio>=0.23.8,<1.0.0",
+    "nest-asyncio>=1.6.0,<2.0.0",
+]
+
+[project.optional-dependencies]
+jupyter = [
+    "jupyter>=1.0.0,<2.0.0",
+]
+lint = [
+    "ruff>=0.4.6,<1.0.0",
+    "mypy>=1.15.0,<2.0.0",
+    "codespell>=2.2.0,<3.0.0",
+    "types-pyyaml>=6.0.12.20240917,<7.0.0",
+    "types-requests>=2.32.0.20240914,<3.0.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "W",   # pycodestyle warnings
+    "I",   # isort
+    "C",  # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "UP", # pyupgrade
+    "RUF", # ruff specific rules
+]
+ignore = ["E501", "C901", "B006"] # ignore line too long, too complex
+
+[tool.ruff.lint.isort]
+known-first-party = ["rag_agent", "frontend"]
+
+[tool.mypy]
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+disallow_subclassing_any = true
+warn_incomplete_stub = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+follow_imports = "silent"
+ignore_missing_imports = true
+explicit_package_bases = true
+disable_error_code = ["misc", "no-untyped-call", "no-any-return"]
+
+exclude = [".venv"]
+
+[tool.codespell]
+ignore-words-list = "rouge"
+skip = "./locust_env/*,uv.lock,.venv,./frontend,**/*.ipynb"
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.pytest.ini_options]
+pythonpath = "."
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rag_agent","frontend"]

rag_agent/.env.example

@@ -1,3 +0,0 @@
-GOOGLE_CLOUD_PROJECT="adk-rag-yt"
-GOOGLE_CLOUD_LOCATION="us-central1"
-GOOGLE_GENAI_USE_VERTEXAI="True"

rag_agent/agent.py

@@ -11,105 +11,53 @@ from .tools.rag_query import rag_query
 root_agent = Agent(
     name="RagAgent",
     # Using Gemini 2.5 Flash for best performance with RAG operations
-    model="gemini-2.5-flash-preview-04-17",
+    model="gemini-2.5-flash",
     description="Vertex AI RAG Agent",
     tools=[
         rag_query,
-        list_corpora,
-        create_corpus,
-        add_data,
-        get_corpus_info,
-        delete_corpus,
-        delete_document,
     ],
-    instruction="""
-    # 🧠 Vertex AI RAG Agent
+    instruction=
+f"""
+<Character>
+Characteristics: {"ผู้หญิง เรียบร้อย สุขุม ใจดี เฟรนลี่"}
+Language: {"ไทย"}
+Name: {"แคส"}
+you're and expert of the company {"บริษัท ไทย บิทแคสต์ จำกัด (Thai Bitcast Company Limited)"}
+You are a helpful assistant agent capable of answering user questions by retrieving relevant information.
+</Character>
 
-    You are a helpful RAG (Retrieval Augmented Generation) agent that can interact with Vertex AI's document corpora.
-    You can retrieve information from corpora, list available corpora, create new corpora, add new documents to corpora, 
-    get detailed information about specific corpora, delete specific documents from corpora, 
-    and delete entire corpora when they're no longer needed.
-    
-    ## Your Capabilities
-    
-    1. **Query Documents**: You can answer questions by retrieving relevant information from document corpora.
-    2. **List Corpora**: You can list all available document corpora to help users understand what data is available.
-    3. **Create Corpus**: You can create new document corpora for organizing information.
-    4. **Add New Data**: You can add new documents (Google Drive URLs, etc.) to existing corpora.
-    5. **Get Corpus Info**: You can provide detailed information about a specific corpus, including file metadata and statistics.
-    6. **Delete Document**: You can delete a specific document from a corpus when it's no longer needed.
-    7. **Delete Corpus**: You can delete an entire corpus and all its associated files when it's no longer needed.
-    
-    ## How to Approach User Requests
-    
-    When a user asks a question:
-    1. First, determine if they want to manage corpora (list/create/add data/get info/delete) or query existing information.
-    2. If they're asking a knowledge question, use the `rag_query` tool to search the corpus.
-    3. If they're asking about available corpora, use the `list_corpora` tool.
-    4. If they want to create a new corpus, use the `create_corpus` tool.
-    5. If they want to add data, ensure you know which corpus to add to, then use the `add_data` tool.
-    6. If they want information about a specific corpus, use the `get_corpus_info` tool.
-    7. If they want to delete a specific document, use the `delete_document` tool with confirmation.
-    8. If they want to delete an entire corpus, use the `delete_corpus` tool with confirmation.
-    
-    ## Using Tools
-    
-    You have seven specialized tools at your disposal:
-    
-    1. `rag_query`: Query a corpus to answer questions
-       - Parameters:
-         - corpus_name: The name of the corpus to query (required, but can be empty to use current corpus)
-         - query: The text question to ask
-    
-    2. `list_corpora`: List all available corpora
-       - When this tool is called, it returns the full resource names that should be used with other tools
-    
-    3. `create_corpus`: Create a new corpus
-       - Parameters:
-         - corpus_name: The name for the new corpus
-    
-    4. `add_data`: Add new data to a corpus
-       - Parameters:
-         - corpus_name: The name of the corpus to add data to (required, but can be empty to use current corpus)
-         - paths: List of Google Drive or GCS URLs
-    
-    5. `get_corpus_info`: Get detailed information about a specific corpus
-       - Parameters:
-         - corpus_name: The name of the corpus to get information about
-         
-    6. `delete_document`: Delete a specific document from a corpus
-       - Parameters:
-         - corpus_name: The name of the corpus containing the document
-         - document_id: The ID of the document to delete (can be obtained from get_corpus_info results)
-         - confirm: Boolean flag that must be set to True to confirm deletion
-         
-    7. `delete_corpus`: Delete an entire corpus and all its associated files
-       - Parameters:
-         - corpus_name: The name of the corpus to delete
-         - confirm: Boolean flag that must be set to True to confirm deletion
-    
-    ## INTERNAL: Technical Implementation Details
-    
-    This section is NOT user-facing information - don't repeat these details to users:
-    
-    - The system tracks a "current corpus" in the state. When a corpus is created or used, it becomes the current corpus.
-    - For rag_query and add_data, you can provide an empty string for corpus_name to use the current corpus.
-    - If no current corpus is set and an empty corpus_name is provided, the tools will prompt the user to specify one.
-    - Whenever possible, use the full resource name returned by the list_corpora tool when calling other tools.
-    - Using the full resource name instead of just the display name will ensure more reliable operation.
-    - Do not tell users to use full resource names in your responses - just use them internally in your tool calls.
-    
-    ## Communication Guidelines
-    
-    - Be clear and concise in your responses.
-    - If querying a corpus, explain which corpus you're using to answer the question.
-    - If managing corpora, explain what actions you've taken.
-    - When new data is added, confirm what was added and to which corpus.
-    - When corpus information is displayed, organize it clearly for the user.
-    - When deleting a document or corpus, always ask for confirmation before proceeding.
-    - If an error occurs, explain what went wrong and suggest next steps.
-    - When listing corpora, just provide the display names and basic information - don't tell users about resource names.
-    
-    Remember, your primary goal is to help users access and manage information through RAG capabilities.
-    """,
+The assistant can answer user queries by retrieving information from Vertex AI’s document corpora using the `rag_query` tool.
+
+<Tool>
+Use the `rag_query` tool when the user asks about the company's business, products, or services.
+
+rag_query parameters:
+    - query: str  
+    - type: str
+
+Guidelines:
+• query: You must simplify and reframe the user's question into a concise query appropriate for the tool.  
+• type: Must be one of the following — "business", "product", or "service".
+
+Type selection rules:
+• business — Use this when the user asks general business questions or requests an overview of the company, such as:
+    - “เกี่ยวกับอะไร”
+    - “ขายสินค้าอะไรบ้าง”
+
+• product — Use this when the user is looking for a specific product or describing product requirements, such as:
+    - “มีสินค้าลักษณะนี้ไหม”
+
+• service — Use this when the user is looking for company services, such as:
+    - “มีบริการนี้ไหม”
+</Tool>
+
+<Response_Handling>
+After retrieving data, you must verify the relevance and accuracy of the information before responding to the user.
+Do not generate or infer any information that is not explicitly provided in the retrieved data.
+</Response_Handling>
+"""
+,
 )
+
+from google.adk.apps.app import App
+app = App(root_agent=root_agent, name="rag_agent")

rag_agent/agent_engine_app.py

@@ -0,0 +1,61 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# mypy: disable-error-code="attr-defined,arg-type"
+import logging
+import os
+from typing import Any
+
+import vertexai
+from google.adk.artifacts import GcsArtifactService, InMemoryArtifactService
+from google.cloud import logging as google_cloud_logging
+from vertexai.agent_engines.templates.adk import AdkApp
+
+from rag_agent.agent import app as adk_app
+from rag_agent.app_utils.telemetry import setup_telemetry
+from rag_agent.app_utils.typing import Feedback
+
+
+class AgentEngineApp(AdkApp):
+    def set_up(self) -> None:
+        """Initialize the agent engine app with logging and telemetry."""
+        vertexai.init()
+        setup_telemetry()
+        super().set_up()
+        logging.basicConfig(level=logging.INFO)
+        logging_client = google_cloud_logging.Client()
+        self.logger = logging_client.logger(__name__)
+        if gemini_location:
+            os.environ["GOOGLE_CLOUD_LOCATION"] = gemini_location
+
+    def register_feedback(self, feedback: dict[str, Any]) -> None:
+        """Collect and log feedback."""
+        feedback_obj = Feedback.model_validate(feedback)
+        self.logger.log_struct(feedback_obj.model_dump(), severity="INFO")
+
+    def register_operations(self) -> dict[str, list[str]]:
+        """Registers the operations of the Agent."""
+        operations = super().register_operations()
+        operations[""] = operations.get("", []) + ["register_feedback"]
+        return operations
+
+
+gemini_location = os.environ.get("GOOGLE_CLOUD_LOCATION")
+logs_bucket_name = os.environ.get("LOGS_BUCKET_NAME")
+agent_engine = AgentEngineApp(
+    app=adk_app,
+    artifact_service_builder=lambda: GcsArtifactService(bucket_name=logs_bucket_name)
+    if logs_bucket_name
+    else InMemoryArtifactService(),
+)

rag_agent/app_utils/.requirements.txt

@@ -0,0 +1,175 @@
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.13.2
+aiosignal==1.4.0
+aiosqlite==0.21.0
+alembic==1.17.2
+annotated-types==0.7.0
+anyio==4.11.0
+async-timeout==5.0.1 ; python_full_version < '3.11'
+attrs==25.4.0
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+authlib==1.6.5
+brotli==1.2.0
+cachetools==6.2.2
+certifi==2025.11.12
+cffi==2.0.0 ; platform_python_implementation != 'PyPy'
+charset-normalizer==3.4.4
+click==8.3.1
+cloudpickle==3.1.2
+colorama==0.4.6 ; sys_platform == 'win32'
+cryptography==46.0.3
+decorator==5.2.1
+distro==1.9.0
+docstring-parser==0.17.0
+exceptiongroup==1.3.0 ; python_full_version < '3.11'
+fastapi==0.118.3
+fastuuid==0.14.0
+ffmpy==1.0.0
+filelock==3.20.0
+frozenlist==1.8.0
+fsspec==2025.10.0
+gcsfs==2025.10.0
+google-adk==1.19.0
+google-api-core==2.28.1
+google-api-python-client==2.187.0
+google-auth==2.43.0
+google-auth-httplib2==0.2.1
+google-auth-oauthlib==1.2.2
+google-cloud-aiplatform==1.128.0
+google-cloud-appengine-logging==1.7.0
+google-cloud-audit-log==0.4.0
+google-cloud-bigquery==3.38.0
+google-cloud-bigquery-storage==2.34.0
+google-cloud-bigtable==2.34.0
+google-cloud-core==2.5.0
+google-cloud-discoveryengine==0.13.12
+google-cloud-logging==3.12.1
+google-cloud-monitoring==2.28.0
+google-cloud-resource-manager==1.15.0
+google-cloud-secret-manager==2.25.0
+google-cloud-spanner==3.59.0
+google-cloud-speech==2.34.0
+google-cloud-storage==3.6.0
+google-cloud-trace==1.17.0
+google-crc32c==1.7.1
+google-genai==1.51.0
+google-resumable-media==2.8.0
+googleapis-common-protos==1.72.0
+gradio==5.49.1
+gradio-client==1.13.3
+graphviz==0.21
+greenlet==3.2.4 ; platform_machine == 'AMD64' or platform_machine == 'WIN32' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'ppc64le' or platform_machine == 'win32' or platform_machine == 'x86_64'
+groovy==0.1.2
+grpc-google-iam-v1==0.14.3
+grpc-interceptor==0.15.4
+grpcio==1.76.0
+grpcio-status==1.76.0
+h11==0.16.0
+hf-xet==1.2.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+httpcore==1.0.9
+httplib2==0.31.0
+httpx==0.28.1
+httpx-sse==0.4.3
+huggingface-hub==1.1.4
+idna==3.11
+importlib-metadata==8.7.0
+jinja2==3.1.6
+jiter==0.12.0
+joblib==1.5.2
+jsonschema==4.25.1
+jsonschema-specifications==2025.9.1
+litellm==1.80.0
+mako==1.3.10
+markdown-it-py==4.0.0
+markupsafe==3.0.3
+mcp==1.21.2
+mdurl==0.1.2
+multidict==6.7.0
+numpy==2.2.6 ; python_full_version < '3.11'
+numpy==2.3.5 ; python_full_version >= '3.11'
+oauthlib==3.3.1
+openai==2.8.1
+opentelemetry-api==1.37.0
+opentelemetry-exporter-gcp-logging==1.11.0a0
+opentelemetry-exporter-gcp-monitoring==1.11.0a0
+opentelemetry-exporter-gcp-trace==1.11.0
+opentelemetry-exporter-otlp-proto-common==1.37.0
+opentelemetry-exporter-otlp-proto-http==1.37.0
+opentelemetry-instrumentation==0.58b0
+opentelemetry-instrumentation-google-genai==0.4b0
+opentelemetry-proto==1.37.0
+opentelemetry-resourcedetector-gcp==1.11.0a0
+opentelemetry-sdk==1.37.0
+opentelemetry-semantic-conventions==0.58b0
+opentelemetry-util-genai==0.2b0
+orjson==3.11.4
+packaging==25.0
+pandas==2.3.3
+pillow==11.3.0
+propcache==0.4.1
+proto-plus==1.26.1
+protobuf==6.33.1
+pyarrow==22.0.0
+pyasn1==0.6.1
+pyasn1-modules==0.4.2
+pycparser==2.23 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+pydantic==2.11.10
+pydantic-core==2.33.2
+pydantic-settings==2.12.0
+pydub==0.25.1
+pygments==2.19.2
+pyjwt==2.10.1
+pyparsing==3.2.5
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.1
+python-multipart==0.0.20
+pytz==2025.2
+pywin32==311 ; sys_platform == 'win32'
+pyyaml==6.0.3
+referencing==0.37.0
+regex==2025.11.3
+requests==2.32.5
+requests-oauthlib==2.0.0
+rich==14.2.0
+rpds-py==0.29.0
+rsa==4.9.1
+ruamel-yaml==0.18.16
+ruamel-yaml-clib==0.2.15 ; platform_python_implementation == 'CPython'
+ruff==0.14.5
+safehttpx==0.1.7
+scikit-learn==1.5.2 ; python_full_version < '3.11'
+scikit-learn==1.7.2 ; python_full_version >= '3.11'
+scipy==1.15.3 ; python_full_version < '3.11'
+scipy==1.16.3 ; python_full_version >= '3.11'
+semantic-version==2.10.0
+shapely==2.1.2
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+sqlalchemy==2.0.44
+sqlalchemy-spanner==1.17.1
+sqlparse==0.5.3
+sse-starlette==3.0.3
+starlette==0.48.0
+tenacity==9.1.2
+threadpoolctl==3.6.0
+tiktoken==0.12.0
+tokenizers==0.22.1
+tomli==2.3.0 ; python_full_version < '3.11'
+tomlkit==0.13.3
+tqdm==4.67.1
+typer==0.20.0
+typer-slim==0.20.0
+typing-extensions==4.15.0
+typing-inspection==0.4.2
+tzdata==2025.2
+tzlocal==5.3.1
+uritemplate==4.2.0
+urllib3==2.5.0
+uvicorn==0.38.0
+watchdog==6.0.0
+websockets==15.0.1
+wrapt==1.17.3
+yarl==1.22.0
+zipp==3.23.0

rag_agent/app_utils/deploy.py

@@ -0,0 +1,338 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import datetime
+import importlib
+import inspect
+import json
+import logging
+import warnings
+from typing import Any
+
+import click
+import google.auth
+import vertexai
+from vertexai._genai import _agent_engines_utils
+from vertexai._genai.types import AgentEngine, AgentEngineConfig
+
+# Suppress google-cloud-storage version compatibility warning
+warnings.filterwarnings(
+    "ignore", category=FutureWarning, module="google.cloud.aiplatform"
+)
+
+
+def generate_class_methods_from_agent(agent_instance: Any) -> list[dict[str, Any]]:
+    """Generate method specifications with schemas from agent's register_operations().
+
+    See: https://docs.cloud.google.com/agent-builder/agent-engine/use/custom#supported-operations
+    """
+    registered_operations = _agent_engines_utils._get_registered_operations(
+        agent=agent_instance
+    )
+    class_methods_spec = _agent_engines_utils._generate_class_methods_spec_or_raise(
+        agent=agent_instance,
+        operations=registered_operations,
+    )
+    class_methods_list = [
+        _agent_engines_utils._to_dict(method_spec) for method_spec in class_methods_spec
+    ]
+    return class_methods_list
+
+
+def parse_key_value_pairs(kv_string: str | None) -> dict[str, str]:
+    """Parse key-value pairs from a comma-separated KEY=VALUE string."""
+    result = {}
+    if kv_string:
+        for pair in kv_string.split(","):
+            if "=" in pair:
+                key, value = pair.split("=", 1)
+                result[key.strip()] = value.strip()
+            else:
+                logging.warning(f"Skipping malformed key-value pair: {pair}")
+    return result
+
+
+def write_deployment_metadata(
+    remote_agent: Any,
+    metadata_file: str = "deployment_metadata.json",
+) -> None:
+    """Write deployment metadata to file."""
+    metadata = {
+        "remote_agent_engine_id": remote_agent.api_resource.name,
+        "deployment_target": "agent_engine",
+        "is_a2a": False,
+        "deployment_timestamp": datetime.datetime.now().isoformat(),
+    }
+
+    with open(metadata_file, "w") as f:
+        json.dump(metadata, f, indent=2)
+
+    logging.info(f"Agent Engine ID written to {metadata_file}")
+
+
+def print_deployment_success(
+    remote_agent: Any,
+    location: str,
+    project: str,
+) -> None:
+    """Print deployment success message with console URL."""
+    # Extract agent engine ID and project number for console URL
+    resource_name_parts = remote_agent.api_resource.name.split("/")
+    agent_engine_id = resource_name_parts[-1]
+    project_number = resource_name_parts[1]
+    print("\n✅ Deployment successful!")
+    service_account = remote_agent.api_resource.spec.service_account
+    if service_account:
+        print(f"Service Account: {service_account}")
+    else:
+        default_sa = (
+            f"service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
+        )
+        print(f"Service Account: {default_sa}")
+    playground_url = f"https://console.cloud.google.com/vertex-ai/agents/locations/{location}/agent-engines/{agent_engine_id}/playground?project={project}"
+    print(f"\n📊 Open Console Playground: {playground_url}\n")
+
+
+@click.command()
+@click.option(
+    "--project",
+    default=None,
+    help="GCP project ID (defaults to application default credentials)",
+)
+@click.option(
+    "--location",
+    default="asia-southeast1",
+    help="GCP region (defaults to asia-southeast1)",
+)
+@click.option(
+    "--display-name",
+    default="adk-rag-agent",
+    help="Display name for the agent engine",
+)
+@click.option(
+    "--description",
+    default="",
+    help="Description of the agent",
+)
+@click.option(
+    "--source-packages",
+    multiple=True,
+    default=["./rag_agent"],
+    help="Source packages to deploy. Can be specified multiple times (e.g., --source-packages=./app --source-packages=./lib)",
+)
+@click.option(
+    "--entrypoint-module",
+    default="rag_agent.agent_engine_app",
+    help="Python module path for the agent entrypoint (required)",
+)
+@click.option(
+    "--entrypoint-object",
+    default="agent_engine",
+    help="Name of the agent instance at module level (required)",
+)
+@click.option(
+    "--requirements-file",
+    default="rag_agent/app_utils/.requirements.txt",
+    help="Path to requirements.txt file",
+)
+@click.option(
+    "--set-env-vars",
+    default=None,
+    help="Comma-separated list of environment variables in KEY=VALUE format",
+)
+@click.option(
+    "--labels",
+    default=None,
+    help="Comma-separated list of labels in KEY=VALUE format",
+)
+@click.option(
+    "--service-account",
+    default=None,
+    help="Service account email to use for the agent engine",
+)
+@click.option(
+    "--min-instances",
+    type=int,
+    default=1,
+    help="Minimum number of instances (default: 1)",
+)
+@click.option(
+    "--max-instances",
+    type=int,
+    default=10,
+    help="Maximum number of instances (default: 10)",
+)
+@click.option(
+    "--cpu",
+    default="4",
+    help="CPU limit (default: 4)",
+)
+@click.option(
+    "--memory",
+    default="8Gi",
+    help="Memory limit (default: 8Gi)",
+)
+@click.option(
+    "--container-concurrency",
+    type=int,
+    default=9,
+    help="Container concurrency (default: 9)",
+)
+@click.option(
+    "--num-workers",
+    type=int,
+    default=1,
+    help="Number of worker processes (default: 1)",
+)
+def deploy_agent_engine_app(
+    project: str | None,
+    location: str,
+    display_name: str,
+    description: str,
+    source_packages: tuple[str, ...],
+    entrypoint_module: str,
+    entrypoint_object: str,
+    requirements_file: str,
+    set_env_vars: str | None,
+    labels: str | None,
+    service_account: str | None,
+    min_instances: int,
+    max_instances: int,
+    cpu: str,
+    memory: str,
+    container_concurrency: int,
+    num_workers: int,
+) -> AgentEngine:
+    """Deploy the agent engine app to Vertex AI."""
+
+    logging.basicConfig(level=logging.INFO)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+
+    # Parse environment variables and labels if provided
+    env_vars = parse_key_value_pairs(set_env_vars)
+    labels_dict = parse_key_value_pairs(labels)
+
+    # Set GOOGLE_CLOUD_REGION to match deployment location
+    env_vars["GOOGLE_CLOUD_REGION"] = location
+
+    # Add NUM_WORKERS from CLI argument (can be overridden via --set-env-vars)
+    if "NUM_WORKERS" not in env_vars:
+        env_vars["NUM_WORKERS"] = str(num_workers)
+
+    # Enable telemetry by default for Agent Engine
+    if "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY" not in env_vars:
+        env_vars["GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"] = "true"
+    if "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT" not in env_vars:
+        env_vars["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"
+
+    if not project:
+        _, project = google.auth.default()
+
+    print("""
+    ╔═══════════════════════════════════════════════════════════╗
+    ║                                                           ║
+    ║   🤖 DEPLOYING AGENT TO VERTEX AI AGENT ENGINE 🤖         ║
+    ║                                                           ║
+    ╚═══════════════════════════════════════════════════════════╝
+    """)
+
+    # Log deployment parameters
+    click.echo("\n📋 Deployment Parameters:")
+    click.echo(f"  Project: {project}")
+    click.echo(f"  Location: {location}")
+    click.echo(f"  Display Name: {display_name}")
+    click.echo(f"  Min Instances: {min_instances}")
+    click.echo(f"  Max Instances: {max_instances}")
+    click.echo(f"  CPU: {cpu}")
+    click.echo(f"  Memory: {memory}")
+    click.echo(f"  Container Concurrency: {container_concurrency}")
+    if service_account:
+        click.echo(f"  Service Account: {service_account}")
+    if env_vars:
+        click.echo("\n🌍 Environment Variables:")
+        for key, value in sorted(env_vars.items()):
+            click.echo(f"  {key}: {value}")
+
+    source_packages_list = list(source_packages)
+
+    # Initialize vertexai client
+    client = vertexai.Client(
+        project=project,
+        location=location,
+    )
+    vertexai.init(project=project, location=location)
+
+    # Add agent garden labels if configured
+
+    # Dynamically import the agent instance to generate class_methods
+    logging.info(f"Importing {entrypoint_module}.{entrypoint_object}")
+    module = importlib.import_module(entrypoint_module)
+    agent_instance = getattr(module, entrypoint_object)
+
+    # If the agent_instance is a coroutine, await it to get the actual instance
+    if inspect.iscoroutine(agent_instance):
+        logging.info(f"Detected coroutine, awaiting {entrypoint_object}...")
+        agent_instance = asyncio.run(agent_instance)
+    # Generate class methods spec from register_operations
+    class_methods_list = generate_class_methods_from_agent(agent_instance)
+
+    config = AgentEngineConfig(
+        display_name=display_name,
+        description=description,
+        source_packages=source_packages_list,
+        entrypoint_module=entrypoint_module,
+        entrypoint_object=entrypoint_object,
+        class_methods=class_methods_list,
+        env_vars=env_vars,
+        service_account=service_account,
+        requirements_file=requirements_file,
+        labels=labels_dict,
+        min_instances=min_instances,
+        max_instances=max_instances,
+        resource_limits={"cpu": cpu, "memory": memory},
+        container_concurrency=container_concurrency,
+        agent_framework="google-adk",
+    )
+
+    # Check if an agent with this name already exists
+    existing_agents = list(client.agent_engines.list())
+    matching_agents = [
+        agent
+        for agent in existing_agents
+        if agent.api_resource.display_name == display_name
+    ]
+
+    # Deploy the agent (create or update)
+    if matching_agents:
+        click.echo(f"\n📝 Updating existing agent: {display_name}")
+    else:
+        click.echo(f"\n🚀 Creating new agent: {display_name}")
+
+    click.echo("🚀 Deploying to Vertex AI Agent Engine (this can take 3-5 minutes)...")
+    if matching_agents:
+        remote_agent = client.agent_engines.update(
+            name=matching_agents[0].api_resource.name, config=config
+        )
+    else:
+        remote_agent = client.agent_engines.create(config=config)
+
+    write_deployment_metadata(remote_agent)
+    print_deployment_success(remote_agent, location, project)
+
+    return remote_agent
+
+
+if __name__ == "__main__":
+    deploy_agent_engine_app()

rag_agent/app_utils/gcs.py

@@ -0,0 +1,42 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+import google.cloud.storage as storage
+from google.api_core import exceptions
+
+
+def create_bucket_if_not_exists(bucket_name: str, project: str, location: str) -> None:
+    """Creates a new bucket if it doesn't already exist.
+
+    Args:
+        bucket_name: Name of the bucket to create
+        project: Google Cloud project ID
+        location: Location to create the bucket in (defaults to asia-southeast1)
+    """
+    storage_client = storage.Client(project=project)
+
+    if bucket_name.startswith("gs://"):
+        bucket_name = bucket_name[5:]
+    try:
+        storage_client.get_bucket(bucket_name)
+        logging.info(f"Bucket {bucket_name} already exists")
+    except exceptions.NotFound:
+        bucket = storage_client.create_bucket(
+            bucket_name,
+            location=location,
+            project=project,
+        )
+        logging.info(f"Created bucket {bucket.name} in {bucket.location}")

rag_agent/app_utils/telemetry.py

@@ -0,0 +1,45 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import logging
+import os
+
+
+def setup_telemetry() -> str | None:
+    """Configure OpenTelemetry and GenAI telemetry with GCS upload."""
+    os.environ.setdefault("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY", "true")
+
+    bucket = os.environ.get("LOGS_BUCKET_NAME")
+    capture_content = os.environ.get(
+        "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "false"
+    )
+    if bucket and capture_content != "false":
+        logging.info("Setting up GenAI telemetry with GCS upload...")
+        os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "NO_CONTENT"
+        os.environ.setdefault("OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT", "jsonl")
+        os.environ.setdefault("OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK", "upload")
+        os.environ.setdefault(
+            "OTEL_SEMCONV_STABILITY_OPT_IN", "gen_ai_latest_experimental"
+        )
+        commit_sha = os.environ.get("COMMIT_SHA", "dev")
+        os.environ.setdefault(
+            "OTEL_RESOURCE_ATTRIBUTES",
+            f"service.namespace=adk-rag-agent,service.version={commit_sha}",
+        )
+        path = os.environ.get("GENAI_TELEMETRY_PATH", "completions")
+        os.environ.setdefault(
+            "OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH",
+            f"gs://{bucket}/{path}",
+        )
+
+    return bucket

rag_agent/app_utils/typing.py

@@ -0,0 +1,33 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import uuid
+from typing import (
+    Literal,
+)
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+
+class Feedback(BaseModel):
+    """Represents feedback for a conversation."""
+
+    score: int | float
+    text: str | None = ""
+    log_type: Literal["feedback"] = "feedback"
+    service_name: Literal["adk-rag-agent"] = "adk-rag-agent"
+    user_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))

rag_agent/config.py

@@ -20,7 +20,9 @@ LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION")
 # RAG settings
 DEFAULT_CHUNK_SIZE = 512
 DEFAULT_CHUNK_OVERLAP = 100
-DEFAULT_TOP_K = 3
+DEFAULT_BUSINESS_TOP_K = 1
+DEFAULT_PRODUCT_TOP_K = 3
+DEFAULT_SERVICE_TOP_K = 3
 DEFAULT_DISTANCE_THRESHOLD = 0.5
 DEFAULT_EMBEDDING_MODEL = "publishers/google/models/text-embedding-005"
 DEFAULT_EMBEDDING_REQUESTS_PER_MIN = 1000

rag_agent/tools/rag_query.py

@@ -2,111 +2,105 @@
 Tool for querying Vertex AI RAG corpora and retrieving relevant information.
 """
 
-import logging
-
-from google.adk.tools.tool_context import ToolContext
 from vertexai import rag
 
 from ..config import (
     DEFAULT_DISTANCE_THRESHOLD,
-    DEFAULT_TOP_K,
+    DEFAULT_BUSINESS_TOP_K,
+    DEFAULT_PRODUCT_TOP_K,
+    DEFAULT_SERVICE_TOP_K
 )
-from .utils import check_corpus_exists, get_corpus_resource_name
-
 
 def rag_query(
-    corpus_name: str,
     query: str,
-    tool_context: ToolContext,
+    type: str,
 ) -> dict:
     """
-    Query a Vertex AI RAG corpus with a user question and return relevant information.
+    Executes a RAG retrieval query against a predefined Vertex AI corpus.
+
+    The query is routed to one of three document groups—business, product, or
+    service—based on the specified type. The function retrieves the top matching
+    contexts and returns them in a simplified dictionary format.
 
     Args:
-        corpus_name (str): The name of the corpus to query. If empty, the current corpus will be used.
-                          Preferably use the resource_name from list_corpora results.
-        query (str): The text query to search for in the corpus
-        tool_context (ToolContext): The tool context
+        query: The user's question to retrieve information for.
+        type: Query category. One of {"business", "product", "service"}.
 
     Returns:
-        dict: The query results and status
-    """
-    try:
-
-        # Check if the corpus exists
-        if not check_corpus_exists(corpus_name, tool_context):
-            return {
-                "status": "error",
-                "message": f"Corpus '{corpus_name}' does not exist. Please create it first using the create_corpus tool.",
-                "query": query,
-                "corpus_name": corpus_name,
-            }
-
-        # Get the corpus resource name
-        corpus_resource_name = get_corpus_resource_name(corpus_name)
+        A dictionary containing processed retrieval results, including text,
+        source metadata, and relevance scores.
 
-        # Configure retrieval parameters
-        rag_retrieval_config = rag.RagRetrievalConfig(
-            top_k=DEFAULT_TOP_K,
-            filter=rag.Filter(vector_distance_threshold=DEFAULT_DISTANCE_THRESHOLD),
+    Raises:
+        ValueError: If `type` is not a valid category.
+    """
+    corpus = rag.get_corpus("projects/38827506989/locations/asia-southeast1/ragCorpora/3458764513820540928")
+    if type == "business":
+        response = rag.retrieval_query(
+            rag_resources=[
+                rag.RagResource(
+                    rag_corpus=corpus.name,
+                    rag_file_ids=["5572399974328298423"]
+                )
+            ],
+            rag_retrieval_config=rag.RagRetrievalConfig(
+                top_k = DEFAULT_BUSINESS_TOP_K,
+                filter=rag.Filter(
+                    vector_distance_threshold = DEFAULT_DISTANCE_THRESHOLD,
+                ),
+            ),
+            text=query,
         )
-
-        # Perform the query
-        print("Performing retrieval query...")
+        print(response)
+    elif type == "product":
         response = rag.retrieval_query(
             rag_resources=[
                 rag.RagResource(
-                    rag_corpus=corpus_resource_name,
+                    rag_corpus=corpus.name,
+                    rag_file_ids=["5572400164943779227"]
                 )
             ],
+            rag_retrieval_config=rag.RagRetrievalConfig(
+                top_k = DEFAULT_PRODUCT_TOP_K,
+                filter=rag.Filter(
+                    vector_distance_threshold = DEFAULT_DISTANCE_THRESHOLD,
+                ),
+            ),
             text=query,
-            rag_retrieval_config=rag_retrieval_config,
         )
+        print(response)
+    elif type == "service":
+        response = rag.retrieval_query(
+            rag_resources=[
+                rag.RagResource(
+                    rag_corpus=corpus.name,
+                    rag_file_ids=["5572400273133586357"]
+                )
+            ],
+            rag_retrieval_config=rag.RagRetrievalConfig(
+                top_k = DEFAULT_SERVICE_TOP_K,
+                filter=rag.Filter(
+                    vector_distance_threshold = DEFAULT_DISTANCE_THRESHOLD,
+                ),
+            ),
+            text=query,
+        )
+        print(response)
 
-        # Process the response into a more usable format
-        results = []
-        if hasattr(response, "contexts") and response.contexts:
-            for ctx_group in response.contexts.contexts:
-                result = {
-                    "source_uri": (
-                        ctx_group.source_uri if hasattr(ctx_group, "source_uri") else ""
-                    ),
-                    "source_name": (
-                        ctx_group.source_display_name
-                        if hasattr(ctx_group, "source_display_name")
-                        else ""
-                    ),
-                    "text": ctx_group.text if hasattr(ctx_group, "text") else "",
-                    "score": ctx_group.score if hasattr(ctx_group, "score") else 0.0,
-                }
-                results.append(result)
-
-        # If we didn't find any results
-        if not results:
-            return {
-                "status": "warning",
-                "message": f"No results found in corpus '{corpus_name}' for query: '{query}'",
-                "query": query,
-                "corpus_name": corpus_name,
-                "results": [],
-                "results_count": 0,
+    results = []
+    if hasattr(response, "contexts") and response.contexts:
+        for ctx_group in response.contexts.contexts:
+            result = {
+                "source_uri": (
+                    ctx_group.source_uri if hasattr(ctx_group, "source_uri") else ""
+                ),
+                "source_name": (
+                    ctx_group.source_display_name
+                    if hasattr(ctx_group, "source_display_name")
+                    else ""
+                ),
+                "text": ctx_group.text if hasattr(ctx_group, "text") else "",
+                "score": ctx_group.score if hasattr(ctx_group, "score") else 0.0,
             }
-
-        return {
-            "status": "success",
-            "message": f"Successfully queried corpus '{corpus_name}'",
-            "query": query,
-            "corpus_name": corpus_name,
-            "results": results,
-            "results_count": len(results),
-        }
-
-    except Exception as e:
-        error_msg = f"Error querying corpus: {str(e)}"
-        logging.error(error_msg)
-        return {
-            "status": "error",
-            "message": error_msg,
-            "query": query,
-            "corpus_name": corpus_name,
-        }
+            results.append(result)
+    print(results)
+    return results

requirements.txt

@@ -3,3 +3,5 @@ google-cloud-storage==2.19.0
 google-genai==1.14.0
 gitpython==3.1.40
 google-adk==0.5.0
+gradio==5.8.0
+python-dotenv==1.0.0

run_gradio.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""
+Quick launcher for Gradio RAG Agent Chat UI
+"""
+
+import sys
+import os
+
+# Add the parent directory to the path to import rag_agent modules if needed
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Import and run the gradio app
+if __name__ == "__main__":
+    from gradio_app import demo
+    
+    print("=" * 50)
+    print("🤖 RAG Agent Chat Interface")
+    print("=" * 50)
+    print("\n📖 Starting Gradio interface...")
+    print("🌐 Open your browser and navigate to the URL shown below\n")
+    
+    demo.launch()

setup_gradio.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Setup script for Gradio RAG Agent Chat UI
+
+echo "🚀 Setting up Gradio RAG Agent Chat UI..."
+echo ""
+
+# Check if Python is installed
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 is not installed. Please install Python 3.10 or higher."
+    exit 1
+fi
+
+echo "✅ Python 3 found: $(python3 --version)"
+echo ""
+
+# Check if .env file exists
+if [ ! -f "rag_agent/.env" ]; then
+    echo "⚠️  Warning: rag_agent/.env file not found"
+    echo "Please create it with the following content:"
+    echo ""
+    echo "GOOGLE_CLOUD_PROJECT=your-project-id"
+    echo "GOOGLE_CLOUD_LOCATION=us-central1"
+    echo "GOOGLE_GENAI_USE_VERTEXAI=true"
+    echo ""
+    exit 1
+fi
+
+echo "✅ Environment file found"
+echo ""
+
+# Install requirements
+echo "📦 Installing Python dependencies..."
+pip install -r requirements.txt
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "✅ Installation complete!"
+    echo ""
+    echo "📋 Next steps:"
+    echo "1. Authenticate with Google Cloud:"
+    echo "   gcloud auth application-default login"
+    echo ""
+    echo "2. Deploy your agent (if not already deployed):"
+    echo "   make deploy"
+    echo ""
+    echo "3. Run the Gradio app:"
+    echo "   python gradio_app.py"
+    echo ""
+    echo "   OR"
+    echo ""
+    echo "   python run_gradio.py"
+    echo ""
+else
+    echo "❌ Installation failed. Please check the error messages above."
+    exit 1
+fi

starter_pack_README.md

@@ -0,0 +1,108 @@
+# adk-rag-agent
+
+
+Agent generated with [`googleCloudPlatform/agent-starter-pack`](https://github.com/GoogleCloudPlatform/agent-starter-pack) version `0.21.0`
+
+## Project Structure
+
+This project is organized as follows:
+
+```
+adk-rag-agent/
+├── rag_agent/                 # Core application code
+│   ├── agent.py         # Main agent logic
+│   ├── agent_engine_app.py # Agent Engine application logic
+│   └── app_utils/       # App utilities and helpers
+├── .cloudbuild/         # CI/CD pipeline configurations for Google Cloud Build
+├── deployment/          # Infrastructure and deployment scripts
+├── notebooks/           # Jupyter notebooks for prototyping and evaluation
+├── tests/               # Unit, integration, and load tests
+├── Makefile             # Makefile for common commands
+├── GEMINI.md            # AI-assisted development guide
+└── pyproject.toml       # Project dependencies and configuration
+```
+
+## Requirements
+
+Before you begin, ensure you have:
+- **uv**: Python package manager (used for all dependency management in this project) - [Install](https://docs.astral.sh/uv/getting-started/installation/) ([add packages](https://docs.astral.sh/uv/concepts/dependencies/) with `uv add <package>`)
+- **Google Cloud SDK**: For GCP services - [Install](https://cloud.google.com/sdk/docs/install)
+- **Terraform**: For infrastructure deployment - [Install](https://developer.hashicorp.com/terraform/downloads)
+- **make**: Build automation tool - [Install](https://www.gnu.org/software/make/) (pre-installed on most Unix-based systems)
+
+
+## Quick Start (Local Testing)
+
+Install required packages and launch the local development environment:
+
+```bash
+make install && make playground
+```
+
+## Commands
+
+| Command              | Description                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| `make install`       | Install all required dependencies using uv                                                  |
+| `make playground`    | Launch local development environment for testing agent |
+| `make deploy`        | Deploy agent to Agent Engine |
+| `make register-gemini-enterprise` | Register deployed agent to Gemini Enterprise ([docs](https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise.html)) |
+| `make test`          | Run unit and integration tests                                                              |
+| `make lint`          | Run code quality checks (codespell, ruff, mypy)                                             |
+| `make setup-dev-env` | Set up development environment resources using Terraform                         |
+
+For full command options and usage, refer to the [Makefile](Makefile).
+
+
+## Usage
+
+This template follows a "bring your own agent" approach - you focus on your business logic, and the template handles everything else (UI, infrastructure, deployment, monitoring).
+
+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 agent into the app by editing `rag_agent/agent.py`.
+3. **Test:** Explore your agent functionality using the local playground with `make playground`. The playground automatically reloads your agent on code changes.
+4. **Deploy:** Set up and initiate the CI/CD pipelines, customizing tests as necessary. Refer to the [deployment section](#deployment) for comprehensive instructions. For streamlined infrastructure deployment, simply run `uvx agent-starter-pack setup-cicd`. Check out the [`agent-starter-pack setup-cicd` CLI command](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd.html). Currently supports GitHub with both Google Cloud Build and GitHub Actions as CI/CD runners.
+5. **Monitor:** Track performance and gather insights using BigQuery telemetry data, Cloud Logging, and Cloud Trace to iterate on your application.
+
+The project includes a `GEMINI.md` file that provides context for AI tools like Gemini CLI when asking questions about your template.
+
+
+## Deployment
+
+> **Note:** For a streamlined one-command deployment of the entire CI/CD pipeline and infrastructure using Terraform, you can use the [`agent-starter-pack setup-cicd` CLI command](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd.html). Currently supports GitHub with both Google Cloud Build and GitHub Actions as CI/CD runners.
+
+### Dev Environment
+
+You can test deployment towards a Dev Environment using the following command:
+
+```bash
+gcloud config set project <your-dev-project-id>
+make deploy
+```
+
+
+The repository includes a Terraform configuration for the setup of the Dev Google Cloud project.
+See [deployment/README.md](deployment/README.md) for instructions.
+
+### Production Deployment
+
+The repository includes a Terraform configuration for the setup of a production Google Cloud project. Refer to [deployment/README.md](deployment/README.md) for detailed instructions on how to deploy the infrastructure and application.
+
+
+## Monitoring and Observability
+
+The application uses [OpenTelemetry GenAI instrumentation](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for comprehensive observability. Telemetry data is automatically captured and exported to:
+
+- **Google Cloud Storage**: GenAI telemetry in JSONL format for efficient querying
+- **BigQuery**: External tables and linked datasets provide immediate access to telemetry data via SQL queries
+- **Cloud Logging**: Dedicated logging bucket with 10-year retention for GenAI operation logs
+
+**Query your telemetry data:**
+
+```bash
+# Example: Query recent completions
+bq query --use_legacy_sql=false \
+  "SELECT * FROM \`adk-rag-agent_telemetry.completions\` LIMIT 10"
+```
+
+For detailed setup instructions, example queries, testing in dev, and optional dashboard visualization, see the [starter pack observability guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html).

test.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "03b6eee8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Testing endpoint: https://asia-southeast1-aiplatform.googleapis.com/v1/projects/angular-stacker-473507-t1/locations/asia-southeast1/reasoningEngines/734755242331078656:query\n",
+      "Payload: {\n",
+      "  \"input\": {\n",
+      "    \"query\": \"List all available RAG corpora\"\n",
+      "  }\n",
+      "}\n",
+      "\n",
+      "Sending request...\n",
+      "\n",
+      "Status Code: 400\n",
+      "Response Headers: {'Vary': 'Origin, X-Origin, Referer', 'Content-Type': 'application/json; charset=UTF-8', 'Content-Encoding': 'gzip', 'Date': 'Thu, 20 Nov 2025 16:23:57 GMT', 'Server': 'scaffolding on HTTPServer2', 'X-XSS-Protection': '0', 'X-Frame-Options': 'SAMEORIGIN', 'X-Content-Type-Options': 'nosniff', 'Alt-Svc': 'h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000', 'Transfer-Encoding': 'chunked'}\n",
+      "\n",
+      "Response Body:\n",
+      "{\n",
+      "  \"error\": {\n",
+      "    \"code\": 400,\n",
+      "    \"message\": \"Reasoning Engine Execution failed.\\nPlease refer to our documentation (https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/use) for checking logs and other troubleshooting tips.\\nError Details: {\\\"detail\\\":\\\"Agent Engine Error: Default method `query` not found. Available methods are: ['async_delete_session', 'async_search_memory', 'async_add_session_to_memory', 'list_sessions', 'register_feedback', 'async_list_sessions', 'get_session', 'async_get_session', 'delete_session', 'create_session', 'async_create_session'].\\\"}\",\n",
+      "    \"status\": \"FAILED_PRECONDITION\"\n",
+      "  }\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "import requests\n",
+    "import subprocess\n",
+    "import json\n",
+    "\n",
+    "# Get access token\n",
+    "def get_access_token():\n",
+    "    result = subprocess.run(\n",
+    "        ['gcloud', 'auth', 'print-access-token'],\n",
+    "        capture_output=True,\n",
+    "        text=True\n",
+    "    )\n",
+    "    return result.stdout.strip()\n",
+    "\n",
+    "# Test the Reasoning Engine endpoint\n",
+    "def test_reasoning_engine():\n",
+    "    url = \"https://asia-southeast1-aiplatform.googleapis.com/v1/projects/angular-stacker-473507-t1/locations/asia-southeast1/reasoningEngines/734755242331078656:query\"\n",
+    "    \n",
+    "    token = get_access_token()\n",
+    "    \n",
+    "    headers = {\n",
+    "        \"Authorization\": f\"Bearer {token}\",\n",
+    "        \"Content-Type\": \"application/json\"\n",
+    "    }\n",
+    "    \n",
+    "    # Test payload - adjust based on your agent's expected input\n",
+    "    payload = {\n",
+    "        \"input\": {\n",
+    "            \"query\": \"List all available RAG corpora\"\n",
+    "        }\n",
+    "    }\n",
+    "    \n",
+    "    print(f\"Testing endpoint: {url}\")\n",
+    "    print(f\"Payload: {json.dumps(payload, indent=2)}\")\n",
+    "    print(\"\\nSending request...\")\n",
+    "    \n",
+    "    response = requests.post(url, headers=headers, json=payload)\n",
+    "    \n",
+    "    print(f\"\\nStatus Code: {response.status_code}\")\n",
+    "    print(f\"Response Headers: {dict(response.headers)}\")\n",
+    "    print(f\"\\nResponse Body:\")\n",
+    "    print(json.dumps(response.json(), indent=2))\n",
+    "    \n",
+    "    return response\n",
+    "\n",
+    "if __name__ == \"__main__\":\n",
+    "    try:\n",
+    "        response = test_reasoning_engine()\n",
+    "    except Exception as e:\n",
+    "        print(f\"Error: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2878a9fc",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "adk-rag-agent",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

test_gradio_setup.py

@@ -0,0 +1,110 @@
+"""
+Simple test script to verify the Gradio setup
+Run this before launching the full app to check configuration
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+
+print("=" * 60)
+print("🧪 Gradio Setup Verification")
+print("=" * 60)
+
+# Test 1: Check environment file
+print("\n1️⃣  Checking environment file...")
+env_path = os.path.join(os.path.dirname(__file__), "rag_agent", ".env")
+if os.path.exists(env_path):
+    print(f"   ✅ Found .env file at: {env_path}")
+    load_dotenv(env_path)
+else:
+    print(f"   ❌ .env file not found at: {env_path}")
+    sys.exit(1)
+
+# Test 2: Check environment variables
+print("\n2️⃣  Checking environment variables...")
+PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
+LOCATION = os.environ.get("GOOGLE_CLOUD_LOCATION")
+
+if PROJECT_ID:
+    print(f"   ✅ GOOGLE_CLOUD_PROJECT: {PROJECT_ID}")
+else:
+    print("   ❌ GOOGLE_CLOUD_PROJECT not set")
+    sys.exit(1)
+
+if LOCATION:
+    print(f"   ✅ GOOGLE_CLOUD_LOCATION: {LOCATION}")
+else:
+    print("   ⚠️  GOOGLE_CLOUD_LOCATION not set, defaulting to 'us-central1'")
+    LOCATION = "us-central1"
+
+# Test 3: Check Python packages
+print("\n3️⃣  Checking required packages...")
+required_packages = {
+    "gradio": "Gradio UI framework",
+    "vertexai": "Vertex AI SDK",
+    "google.cloud.aiplatform_v1beta1": "AI Platform Client",
+    "dotenv": "Environment loader"
+}
+
+all_packages_ok = True
+for package, description in required_packages.items():
+    try:
+        __import__(package.replace("-", "_"))
+        print(f"   ✅ {package}: {description}")
+    except ImportError:
+        print(f"   ❌ {package}: NOT INSTALLED - {description}")
+        all_packages_ok = False
+
+if not all_packages_ok:
+    print("\n   ⚠️  Missing packages. Install with:")
+    print("   pip install -r requirements.txt")
+    sys.exit(1)
+
+# Test 4: Check Google Cloud authentication
+print("\n4️⃣  Checking Google Cloud authentication...")
+try:
+    from google.auth import default
+    credentials, project = default()
+    print(f"   ✅ Authenticated with project: {project}")
+except Exception as e:
+    print(f"   ❌ Authentication error: {e}")
+    print("   Run: gcloud auth application-default login")
+    sys.exit(1)
+
+# Test 5: Try to list agents
+print("\n5️⃣  Testing Agent Engine connection...")
+try:
+    from google.cloud import aiplatform_v1beta1 as aiplatform
+    
+    client = aiplatform.AgentEnginesServiceClient(
+        client_options={"api_endpoint": f"{LOCATION}-aiplatform.googleapis.com"}
+    )
+    parent = f"projects/{PROJECT_ID}/locations/{LOCATION}"
+    request = aiplatform.ListAgentEnginesRequest(parent=parent)
+    
+    agents = list(client.list_agent_engines(request=request))
+    
+    if agents:
+        print(f"   ✅ Successfully connected! Found {len(agents)} agent(s):")
+        for agent in agents:
+            display_name = agent.display_name or agent.name.split("/")[-1]
+            print(f"      • {display_name}")
+    else:
+        print("   ⚠️  Connected, but no agents found")
+        print("   Deploy an agent with: make deploy")
+        
+except Exception as e:
+    print(f"   ❌ Connection error: {e}")
+    print("   Check your project ID and location")
+    sys.exit(1)
+
+# All tests passed
+print("\n" + "=" * 60)
+print("✅ All checks passed! Ready to launch Gradio app")
+print("=" * 60)
+print("\nRun the app with:")
+print("  python gradio_app_v2.py")
+print("\nOr:")
+print("  python run_gradio.py")
+print()