diff --git a/looker-mcp-sample/README.md b/looker-mcp-sample/README.md index 976fad2..d13b680 100644 --- a/looker-mcp-sample/README.md +++ b/looker-mcp-sample/README.md @@ -2,6 +2,8 @@ A step-by-step guide to building a basic AI agent utilizing the Google Agent Development Kit (ADK) and Model Context Protocol (MCP) to interact with Looker connection. +## Phase 1: Basic Looker Agent Setup + --- ## 1. Secure Looker API Credentials @@ -136,4 +138,78 @@ adk web 1. Open the local connection URL in your browser. 2. Ask the agent: *"What tools do you have available to you?"* 3. Verify the agent lists `get_connections`. -4. (Optional) To expand capabilities, add another Looker specific tool under the `tools` key in `tools.yaml`, restart the server using `adk web`, and test again. \ No newline at end of file +4. (Optional) To expand capabilities, add another Looker specific tool under the `tools` key in `tools.yaml`, restart the server using `adk web`, and test again. + +--- + +## Phase 2: Analytics & Orchestration + +In this phase, we add the **BigQuery Agent Analytics Plugin** to track performance and wrap the agent in an **App class** for better orchestration. + +### 1. Google Cloud Configuration + +To use BigQuery analytics, you must configure your Google Cloud environment: + +1. **Enable the BigQuery API:** Go to the Google Cloud Console and enable the BigQuery API for your project. +2. **Assign IAM Roles:** Ensure your user account or service account has the following roles: + * `bigquery.jobuser` (`roles/bigquery.jobUser`): To run the jobs that log data. + * `bigquery.dataeditor` (`roles/bigquery.dataEditor`): To create the analytics dataset and tables. +3. **Local Authentication:** Run the following command to authenticate your local terminal with Google Cloud: + ```bash + gcloud auth application-default login + ``` +4. **Install Cloud Dependencies:** + ```bash + pip install google-cloud-bigquery + ``` +5. **Environment Variable:** Add your Project ID to your `.env` file: + ```bash + GOOGLE_CLOUD_PROJECT="your-google-cloud-project-id" + ``` + +### 2. Update `agent.py` with Analytics and the App Class + +Modify your `agent.py` to import the plugin and the `App` class, then wrap your `root_agent`. + +```python +import os +from dotenv import load_dotenv +from mcp import StdioServerParameters +from google.adk.agents import LlmAgent +from google.adk.tools import MCPToolset +from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams +# New imports for Phase 2 +from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin +from google.adk.apps import App + +load_dotenv() + +# ... (Keep looker_server and looker_toolset setup from Phase 1) ... + +root_agent = LlmAgent( + model='gemini-1.5-flash', + name='looker_pro', + description='Looker assistant', + instruction='You are a helpful assistant that helps manipulate Looker with MCP tools.', + tools=[looker_toolset], +) + +# --- NEW IN PHASE 2 --- + +# 1. Initialize the BigQuery Analytics Plugin +# This will automatically create a dataset (e.g., 'looker_agent_analytics') to log interactions. +analytics_plugin = BigQueryAgentAnalyticsPlugin( + project_id=os.getenv("GOOGLE_CLOUD_PROJECT"), + dataset_id="looker_agent_analytics", +) + +# 2. Wrap your agent in an App +app = App( + name="LookerAgentApp", + root_agent=root_agent, + plugins=[analytics_plugin], +) +``` + +### What is the `App` Class? +The `App` class is the top-level orchestrator in the Google ADK. While an `LlmAgent` handles the logic of a single assistant, the `App` manages the entire application lifecycle. It acts as a central hub that automatically hooks your plugins (like BigQuery analytics) into the agent's execution flow. This ensures that every prompt and response is logged without you having to write custom logging code inside your agent's tools or logic. \ No newline at end of file diff --git a/looker-mcp-sample/basic_looker_agent/.env.example b/looker-mcp-sample/basic_looker_agent/.env.example index b4d6ab2..8c99a0d 100644 --- a/looker-mcp-sample/basic_looker_agent/.env.example +++ b/looker-mcp-sample/basic_looker_agent/.env.example @@ -1,4 +1,6 @@ +GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_API_KEY=your_google_api_key_here LOOKER_BASE_URL=https://your-instance.looker.com LOOKER_CLIENT_ID=your_client_id -LOOKER_CLIENT_SECRET=your_client_secret \ No newline at end of file +LOOKER_CLIENT_SECRET=your_client_secret +GOOGLE_CLOUD_PROJECT=your_google_cloud_project \ No newline at end of file diff --git a/looker-mcp-sample/basic_looker_agent/agent.py b/looker-mcp-sample/basic_looker_agent/agent.py index b28f5ca..eb66faa 100644 --- a/looker-mcp-sample/basic_looker_agent/agent.py +++ b/looker-mcp-sample/basic_looker_agent/agent.py @@ -4,20 +4,32 @@ from google.adk.agents import LlmAgent from google.adk.tools import ToolContext, MCPToolset from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams +from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin +from google.adk.apps import App # ===================================================================== -# 1. ENVIRONMENT CONFIGURATION & VARIABLE LOADING +# ENVIRONMENT CONFIGURATION & VARIABLE LOADING # ===================================================================== # Load configuration settings from the local `.env` file. -load_dotenv() +load_dotenv(dotenv_path=".env") looker_client_id = os.getenv("LOOKER_CLIENT_ID") looker_client_secret = os.getenv("LOOKER_CLIENT_SECRET") looker_base_url = os.getenv("LOOKER_BASE_URL") # ===================================================================== -# 2. CONFIGURING THE DATABASE/TOOL MCP SERVER (STDIO CONNECTION) +# CONFIGURING DATA COLLECTION FOR THE AGENTS +# ===================================================================== +# Configure the BigQuery Agent Analytics Plugin. + +plugin = BigQueryAgentAnalyticsPlugin( + project_id=os.getenv("GOOGLE_CLOUD_PROJECT"), + dataset_id="basic_looker_agent_analytics", +) + +# ===================================================================== +# CONFIGURING THE DATABASE/TOOL MCP SERVER (STDIO CONNECTION) # ===================================================================== # Define standard I/O parameters for launching the `toolbox` server. @@ -25,9 +37,9 @@ command="../toolbox", args=["--stdio", "--tools-file", "../tools.yaml"], env={ - "LOOKER_BASE_URL": looker_base_url, + "LOOKER_BASE_URL":looker_base_url, "LOOKER_CLIENT_ID": looker_client_id, - "LOOKER_CLIENT_SECRET": looker_client_secret + "LOOKER_CLIENT_SECRET": looker_client_secret, }, ) @@ -52,15 +64,28 @@ ) # ===================================================================== -# 3. INITIALIZING THE ADK AGENT WITH GEMINI 3.5 FLASH +# INITIALIZING THE ADK AGENT WITH GEMINI 3.5 FLASH +# INITIALIZING THE ADK AGENT # ===================================================================== # Initialize the core Looker agent (`LlmAgent`). # - We use the highly capable `gemini-3.5-flash` model. +# - We use the model specified in the environment or default to gemini-1.5-flash. # - We equip it with the `looker_toolset` configured above. root_agent = LlmAgent( - model='gemini-2.0-flash', + model='gemini-2.5-flash', name='looker_pro', description='A helpful assistant that connects to the Looker resources via mcp-toolbox-for-databases', instruction='You are a helpful assistant that helps write, edit, and improve high quality LookML files and manipulate Looker with MCP tools', tools=[looker_toolset], ) + +# ===================================================================== +# CONFIGURE TOP LEVEL APP WORKFLOW MANAGEMENT +# ===================================================================== +# Wrap the agents in a top level container to manage lifecycle, configuration, and state for a collection of agents grouped by a root agent + +app = App( + name="LlmAgentDemo", + root_agent=root_agent, + plugins=[plugin], +) \ No newline at end of file