
Adkgemma3
Build AI Agent using Google ADK , MCP and Gemma 3 model
GitHub Stats
Stars
19
Forks
11
Release Date
5/1/2025
about 2 months ago
Detailed Description
YouTube Search Assistant with ADK, MCP and Gemma 3
A practical implementation demonstrating YouTube search functionality using Google's Agent Development Kit (ADK), Model Context Protocol (MCP), and the Gemma 3 model via Ollama.
!ADK Gemma3 Demo
!ADK Gemma Web Demo
📚 Table of Contents
- 🔍 Introduction
- 🏗️ Architecture
- 🧩 Core Components
- 📊 Architecture Diagram
- 🔄 Data Flow
- ✨ Technology Highlights
- 🚀 Features
- 🧠 Core Concepts
- ADK - Agent Development Kit
- MCP - Model Context Protocol
- Agents in ADK
- Tools with MCP
- Ollama Integration
- 📋 Requirements
- 🚦 Getting Started
-
- Installation Steps
-
- Setup
-
- Usage
-
- 🔄 How It Works
- 📁 Project Structure
- ⚠️ Troubleshooting
- 📦 Repository
- 👨💻 Author
- 📄 License
🔍 Introduction
This project showcases how to leverage Google's ADK (Agent Development Kit) and MCP (Model Context Protocol) to build an agent powered by Gemma 3, Google's latest large language model. It demonstrates how to:
- Connect to locally-hosted Gemma 3 via Ollama
- Implement YouTube search functionality using MCP
- Create a conversational agent that can format and present search results
🏗️ Architecture
🧩 Core Components
- Google ADK - Provides the agent framework
- Model Context Protocol (MCP) - Standardizes tool communication
- Gemma 3 (12B) - Powers the language understanding and generation
- Ollama - Hosts the Gemma model locally
- MCP YouTube Search - Provides YouTube search capabilities
- Python 3.9+ - Base runtime environment
📊 Architecture Diagram
!YouTube Search Assistant Architecture
🔄 Data Flow
- User submits a query through the interface
- ADK Agent Framework processes the query and determines intent
- If a YouTube search is needed:
- The request is routed to the MCP Tool Registry
- The MCP YouTube Search tool receives the query
- SERP API is called to fetch YouTube results
- Results are returned through the MCP standardized format
- Gemma 3 model (via Ollama and LiteLlm):
- Receives the search results
- Generates a natural language response
- Formats the search results into readable bullet points
- The formatted response is returned to the user interface
✨ Technology Highlights
- Google ADK Manages conversation flow and tool orchestration.
- Model Context Protocol (MCP) Enables standardized communication between models and tools.
- Gemma 3 via Ollama Delivers high-quality text generation with tool-calling capabilities.
- LiteLlm Integration Connects ADK to Ollama-hosted models seamlessly.
- SERP API Provides access to YouTube data through search API.
🚀 Features
- 🔍 Search for YouTube videos using natural language queries
- 🤖 Powered by Gemma 3 running on Ollama
- 📋 Formats search results in a clean, easy-to-read format
- 🛠️ Built with Google's Agent Development Kit (ADK)
- 🔄 Integrates MCP (Model Context Protocol) for seamless tool communication
🧠 Core Concepts
ADK - Agent Development Kit
Agent Development Kit (ADK) is an open-source, code-first Python toolkit for building intelligent AI agents.
MCP - Model Context Protocol
Model Context Protocol (MCP) is a standard for communication between models and tools. It allows for:
- Consistent tool invocation patterns
- Structured data exchange
- Tool composition and chaining
- Language-agnostic tool definitions
Agents in ADK
An Agent in ADK acts as the orchestrator for AI interactions. In this project, we use LlmAgent, which is a core component in ADK acting as the "thinking" part of your application that:
- Leverages a Large Language Model (LLM) for reasoning and understanding
- Manages conversation history and context
- Coordinates tool usage based on user queries
Tools with MCP
Tools in this project are implemented using the MCP (Model Context Protocol) framework, which:
- Defines a standard interface for tool interaction
- Makes tools easily discoverable by the LLM
- Structures input/output formats
- Facilitates tool composition
The MCP YouTube Search tool provides a standardized way for the agent to interact with YouTube search functionality.
Ollama Integration
Ollama provides a way to run Gemma 3 and other large language models locally. Google ADK connects to Ollama through:
- LiteLlm - A wrapper that standardizes communication with different LLM providers
- Custom configurations to optimize model performance
📋 Requirements
- Python 3.9+
- Ollama installed with Gemma 3 model
- A SERP API key for YouTube search
🚦 Getting Started
1. Installation Steps
Clone this repository:
git clone https://github.com/arjunprabhulal/adk-mcp-gemma3.git
cd adk-mcp-gemma3
2. Setup
Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
Install dependencies:
pip install -r requirements.txt
Set up your SERP API key:
Create a .env
file in the root directory with your SERP API key:
SERP_API_KEY=your_serp_api_key_here
Pull the Gemma 3 model:
ollama pull gemma3:12b
3. Usage
Option 1: Web-based UI (Recommended for debugging)
Run the agent using ADK's browser-based developer UI:
# Navigate to the parent directory
cd adk-mcp-gemma3
# Start the web interface
adk web
You should see output similar to this:
!ADK Web Command Output
Then open the URL provided (usually http://localhost:8000
) in your browser.
- Select "search" from the dropdown menu in the top-left corner
- Type your query in the chat interface
- You can inspect tool calls, model responses, and see detailed execution flow
Option 2: Command Line
Run the agent directly:
python -m search
You can now interact with the agent by asking it to find YouTube videos.
Example queries:
- "Find videos about Google Cloud Next 25"
- "Search for YouTube tutorials on Python programming"
- "Look for videos about machine learning for beginners"
🔄 How It Works
The implementation follows these steps:
-
Agent Initialization:
- Creates an LlmAgent with a reference to the Ollama-hosted Gemma 3 model
- Configures the agent with appropriate instructions
- Adds the YouTube search tool to the agent's capabilities
-
Tool Definition:
- Defines a YouTube search function through MCP
- MCP provides a standardized way for the model to interact with the tool
- The tool connects to SERP API for YouTube search functionality
-
Query Processing:
- User query is passed to the agent
- Gemma 3 decides whether to use the YouTube search tool based on the query
- If needed, the model formulates an appropriate search query
- Results are processed and formatted by the model
-
Response Generation:
- The agent processes all information and formats the search results
- Output is returned to the user as a clean, bulleted list
- Each result includes title, link, channel, description, and metadata
📁 Project Structure
adk_mcp_gemma3/
├── Images/
│ ├── adk-gemma3.gif # Demo gif of the application
│ └── adk-gemma-web.gif # Web interface demo
├── search/
│ ├── __init__.py # Package initialization
│ └── agent.py # Agent implementation with ADK
├── .gitignore # Git ignore file
├── README.md # Project documentation
├── LICENSE # MIT license
└── requirements.txt # Dependencies
⚠️ Troubleshooting
-
Model Loading Issues:
- Ensure Ollama is running:
ollama list
should show the gemma3:12b model. - If the model fails to load, try:
ollama pull gemma3:12b
again.
- Ensure Ollama is running:
-
API Key Issues:
- Verify your SERP API key is correctly set in the .env file.
- Test the API key independently to ensure it's valid.
-
Memory Constraints:
- The 12B model requires significant RAM/VRAM.
- Consider using a smaller model like gemma3:7b if experiencing memory issues.
-
Function Calling Problems:
- If the model doesn't use tools properly, try making the tool description more explicit.
- Ensure your query clearly requires external information.
-
LiteLLM/Ollama KeyError Bug:
- There's a known issue with Ollama's JSON format responses and LiteLLM's parsing that can cause a KeyError: 'name' error.
- This happens when Ollama returns JSON format that isn't specifically a tool call format.
- Error looks like:
KeyError: 'name'
inlitellm/llms/ollama/completion/transformation.py
- A fix has been submitted in PR #9966 for the LiteLLM package but is still pending approval and merging.
- This bug might cause your application to crash or enter an infinite loop when using function calling with Ollama models.
- Temporary workarounds:
- Manually patch your local LiteLLM installation with the changes from PR #9966
- Avoid using
format=json
in Ollama requests if possible - Wait for the PR to be merged and update to the next LiteLLM release that includes the fix
📦 Repository
This project is available on GitHub at arjunprabhulal/adk-mcp-gemma3.
For another related project on ADK with function calling, check out arjunprabhulal/adk-gemma3-function-calling.
👨💻 Author
Created by Arjun Prabhulal. For more articles on AI/ML and Generative AI, follow Arjun Prabhulal on Medium.
📄 License
This project is released under a free and open license. Anyone is free to use, modify, distribute, or build upon this code for any purpose, including commercial applications, without restriction.
Star History
Star History
About the Project
This app has not been claimed by its owner yet.
Claim OwnershipReceive Updates
Security Updates
Get notified about trust rating changes
to receive email notifications.