Loading repository data…
luuisotorres / repository
AI Agent built with Google ADK that leverages Google Maps MCP Server to answer real-world location questions with tool usage and traceable execution via Opik.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
This project demonstrates the creation of an AI Agent using the Google Agent Development Kit (ADK), OpenAI's GPT-4o model, the Google Maps MCP Server, and Opik for observability with Comet.ml.
The primary goal of this project is to deepen my understanding of Agent Development principles, the application of the Model Context Protocol in practice, and how to integrate its tools and services into an AI Agent for enhanced abilities beyond the training data.
This project is largely inspired by Santiago Valdarrama's tutorial on YouTube:
Selected from shared topics, language and repository description—not editorial ratings.
dyingpotato890 /
Frame.AI is a collaborative AI agent system built with Google's ADK to perform intelligent, modular video segmentation.
77/100 healthdivyahmohta /
A production-grade **multi-agent observability system** built with [Google ADK](https://github.com/google/adk-python) that orchestrates specialized AI agents to monitor, query, and troubleshoot infrastructure across Prometheus, Grafana, Kubernetes, and synthetic monitoring systems.
59/100 healthRohit10jr /
The Google Agent Development Kit (ADK) is a Python framework designed to simplify the development of AI Agents powered by LLMs. It provides access to tools, memory, agent orchestration and LLMs from providers like OpenAI, Anthropic, Cohere and many others through integration with the LiteLlm library. The ADK also includes a web UI for interacting with and debugging agents.
Opik is an open-source observability solution for LLM applications, built by Comet. It allows you to trace, visualize, and debug the interactions within your AI Agents, including LLM calls, tool usage, and other operations. In this project, Opik is configured to send traces to CometML, providing a rich UI to inspect agent behavior.
The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs and connect them to different data sources and tools. It defines a schema for tool descriptions, invocations, and responses. This allows for interoperability between different LLM systems and tool providers.
The Google Maps MCP Server is a Node.js application that exposes Google Maps Platform APIs as MCP tools. This allows an ADK Agent to easily leverage Google Maps features to deliver more relevant, context-aware responses.
MCPToolset can automatically start this server using npx if it's not already running, as configured in this project.maps_directions: Get driving, walking, or cycling directions.maps_geocode: Convert addresses to geographic coordinates.maps_reverse_geocode: Convert geographic coordinates to addresses.maps_elevation: Get elevation for a given coordinate.maps_search_places: Search for places (e.g., restaurants, landmarks).maps_place_details: Get detailed information about a specific place.maps_distance_matrix: Calculate travel time and distance between multiple origins and destinations..
├── assets
│ └── screenshots
│ ├── interface.png
│ ├── maps_direction_tool_input_output.png
│ ├── maps_direction_tool_opik.png
│ ├── maps_direction_tool.png
│ ├── maps_directions_tool_events.png
│ ├── maps_elevation_tool.png
│ ├── maps_place_details_event.png
│ ├── maps_reverse_geocode_event.png
│ ├── opik_overall_input_output.png
| ├── adk.png
| ├── mcp.png
│ └── opik_traces.png
├── examples
│ └── agent_conversation.yaml
├── LICENSE
├── mcp_agent
│ ├── __init__.py
│ └── agent.py
├── pyproject.toml
├── README.md
└── uv.lock
Clone the repository:
git clone https://github.com/luuisotorres/mcp-ai-agent.git
cd mcp-ai-agent
Create and sync the virtual environment using UV:
uv venv # Create a virtual environment (e.g., .venv)
uv sync # Install dependencies from pyproject.toml
source .venv/bin/activate # Or `.\.venv\Scripts\activate` on Windows
Set up environment variables: Copy the example environment file and fill in your credentials:
cp .env.example .env
Then, edit .env with your actual API keys.
GOOGLE_MAPS_PLATFORM_API_KEY="your-google-maps-api-key"
OPENAI_API_KEY="your-openai-api-key"
COMET_API_KEY="your-comet-api-key"
COMET_WORKSPACE="your-comet-workspace"
COMET_PROJECT_NAME="your-comet-project-name"
The .env file should contain:
GOOGLE_MAPS_PLATFORM_API_KEY: Your Google Maps Platform API key.
OPENAI_API_KEY: Your OpenAI API key.
LiteLlm model to use OpenAI's GPT models.COMET_API_KEY: Your CometML API Key.
COMET_WORKSPACE: Your CometML workspace.COMET_PROJECT_NAME: The CometML project name where traces will be stored.Once the setup is complete, run the ADK web UI:
uv run adk web
This command will:
http://127.0.0.1:8000 to interact with your agent.MCPToolset in agent.py is configured to start the Google Maps MCP server via npx automatically when the agent needs to use its tools.Upon running uv run adk web and navigating to http://127.0.0.1:8000 (or the port shown in your terminal), you'll see the ADK Web UI. You can select your Agent, in this case mcp_agent, and start a conversation.
(Screenshot 1: The initial ADK Web UI screen with the chat input.) Caption: The main interface of the ADK Web UI where you can type messages to your agent.
The agent can understand requests for directions, place details, elevation, and more, using the tools from the Google Maps MCP Server.
Example: Getting Directions The agent responds to "How do I drive from São Paulo to Campinas?" with turn-by-turn directions.
(Screenshot 2: Agent using the maps_directions tool.)
Caption: The agent successfully uses the maps_directions tool to provide driving directions in the chat interface.
Example: Getting Place Details The agent can fetch reviews and other information for landmarks.
(Screenshot 3: Agent using maps_place_details for Eiffel Tower reviews.)
Caption: Agent fetching and displaying reviews for the Eiffel Tower, showcasing the maps_place_details tool usage and output.
Example: Getting Elevation The agent can provide elevation for given coordinates.
(Screenshot 4: Agent using maps_elevation tool.)
Caption: Agent providing the elevation for specified coordinates using the maps_elevation tool.
The ADK Web UI provides an "Events" (or "Trace") tab where you can inspect the flow of the conversation. This includes the function calls made by the agent and the responses received from tools.
Example: maps_reverse_geocode Event
Shows the agent invoking the maps_reverse_geocode tool.
(Screenshot 5: Event view for maps_reverse_geocode.)
Caption: Event view detailing a functionCall for maps_reverse_geocode with args and Metadata.
Example: maps_directions Event Flow
Illustrates the sequence of events when the maps_directions tool is called.
(Screenshot 6: Event view for maps_directions tool.)
Caption: The "Events" tab in the ADK UI, showing the invocation details for the maps_directions tool.
Opik integrates with CometML to provide detailed traces of your agent's execution, offering insights into LLM calls, tool usage, and overall performance.
Overall Traces in Opik A list of all captured interactions for the project.
(Screenshot 7: Overview of traces in CometML for the mcp-ai-agent project.)
Caption: The CometML UI showing a list of traces captured by Opik for different agent interactions.
Detailed Opik Trace for maps_direction_tool
A specific trace showing the LLM call and the maps_direction_tool invocation.
(Screenshot 8: Detailed view of a single trace involving the maps_directions tool.)
*Caption: A detailed view of an Opik trace in CometML, showing the sequence of operations for a maps_directions re
This project is a conversational AI agent built using Google's Agent Developer Kit to validate HSN codes and return related details from a master file.
ksmin23 /
A lightweight Model Context Protocol (MCP) server that exposes Google Cloud's Vertex AI Search for Commerce as a tool for AI agents. This allows agents to easily search a product catalog using natural language queries. Built with Python and FastMCP.
38/100 health