This tutorial was written by Stanimira Vlaeva and MongoDB Champion Abirami Sukumaran from Google.
An agent is an autonomous program that talks to an AI model to perform a goal-based operation using the tools and context it has, and is capable of autonomous decision making grounded in truth! AI agents can use tools to gather context, interact with external systems, and perform actions. They can define their own execution flow (planning) and remember previous interactions to inform their responses (memory). Therefore, AI agents are best suited for complex tasks that require reasoning, planning, and decision-making.
Lately, I’ve been curious about AI agents but never had a good use case for building one—until I started thinking: “What if I could build an agent to make this weekly chore a little easier?” I believe that we must use AI to automate these mundane tasks, ultimately augmenting the human experience, instead of using AI to “create” art that’s been plagiarized from a human. This idea of AI augmenting human experiences through a kind of a symbiosis is not a new idea—it was envisioned by the early computer pioneers.
Use case
Speaking of mundane tasks… grocery shopping! Every Sunday evening, I find myself scrolling through the product pages of my online supermarket, searching for items while trying to remember what I need to buy. It’s not difficult—it’s just... boring. It’s another chore that takes up time I could spend on something more interesting. Shopping online makes the task a bit more manageable, but I still have to do it every week.
I wanted something that would feel like chatting with a friend who knows my shopping habits. When I say, "I need ingredients for that pasta recipe I made last month," it should understand what I'm talking about. When I ask, "What's a good substitute for that expensive cheese I bought last time?" it should be able to suggest alternatives based on my preferences.
This project combines several technologies I've been excited to explore:
Google's Agent Development Kit (ADK) for creating a natural, conversational interface
Gemini 2.0 Flash to power the agent's understanding of my queries
MongoDB Atlas Vector Search to find similar products and analyze my shopping patterns
This agent has two main capabilities that make my weekly grocery shopping much easier:
It can search for products using semantic similarity, so I don't have to remember exact product names.
It can add items to my cart, keeping track of what I've selected.
In summary, in this use case, we are going to build a single agent that performs two tasks: vector search for grocery items and addition of items to cart.
Let me show you how this was built, and maybe you'll find inspiration to create your own AI agent for a task you'd like to automate!
Google’s Agent Development Kit (ADK)
Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and is built for compatibility with other frameworks. ADK was designed to make agent development feel more like software development, to make it easier for developers to create, deploy, and orchestrate agentic architectures that range from simple tasks to complex workflows.
Agents
In the Agent Development Kit, an agent is a self-contained execution unit designed to act autonomously to achieve specific goals. Agents can perform tasks, interact with users, utilize external tools, and coordinate with other agents.
Multi-agent system
When your application has multiple agents working together autonomously and together as required to cater to its larger purpose, with each of its agents being independently knowledgeable and responsible for a specific focus area, then your application becomes a multi-agent system. Agents are autonomous programs that can make decisions generatively and based on instructions and information made available to them, and are responsible for the specific area of focus for which they are created.
ADK supports building sophisticated applications by composing multiple, distinct agent instances into a multi-agent system (MAS). In ADK, a multi-agent system is an application where different agents, often forming a hierarchy, collaborate or coordinate to achieve a larger goal. Structuring your application this way offers significant advantages, including enhanced modularity, specialization, reusability, maintainability, and the ability to define structured control flows using dedicated workflow agents.
Large language model
Behind the scenes, the agent uses a large language model (LLM) to support the various autonomous activities that the agent is responsible for. Your agent's ability to understand user requests and generate responses is powered by a large language model.
The Agent Development Kit is designed for flexibility, allowing you to integrate various LLMs into your agents. Java ADK currently supports Gemini and Anthropic models. More model support is coming soon. We are going to use Gemini 2.0 Flash as the model that powers our grocery agent.
MongoDB Atlas Vector Search
First, talking about Vector Search, instead of relying on simple keyword matching, vector search transforms text into numerical representations (embeddings). This allows us to search based on the meaning of the query, not just the specific words used, and ensures that we identify contextually relevant matches from a dataset of varied type and structure in a more performance efficient manner.
With Vector Search built into MongoDB Atlas, you can store and search operational data alongside vectors, enabling RAG to access the most relevant data and provide accurate insights.
Let’s get going!
Setting up MongoDB Atlas
Before we dive into the agent code, let's set up our MongoDB Atlas database and configure Vector Search.
Create a MongoDB Atlas cluster
If you don't already have one, create a new MongoDB Atlas cluster.
Go to MongoDB Atlas and sign up for a free account.
Click "Build a Database" and choose the free tier (Shared, M0).
Select your preferred cloud provider and region, then click "Create."
Create a database user with a username and password.
Add your IP address to the IP Access List (or allow access from anywhere for development).
Once the cluster is created, click "Connect" and choose "Connect your application" to get your connection string. Use this string for the CONNECTION_STRING environment variable in the next steps.
Load sample data
For this project, we'll need some sample grocery product data.
Clone the repo and navigate to the project directory containing dataset.csv. The repository provides a dataset.csv file. You can load this data into an Atlas collection named products within a database of your choice (e.g., grocery_db) using the mongosh shell or the Atlas UI.
Run the following command, replacing the connection string with your Atlas connection string and updating the database and collection names if needed:
mongoimport --uri "$CONNECTION_STRING" --db "$DATABASE_NAME" --collection "$COLLECTION_NAME" --type csv --headerline --file mongodb-groceries-agent/dataset.csv This will ensure your dataset is loaded in the MongoDB database.
Generate text embeddings
Create a Google Cloud project
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.
Also, if you are reading this, you can get some credits to help you get started with Google Cloud and to use ADK, use this to redeem credits.
You can follow the instructions to redeem it. Please note that this link is valid only till June 30, 2025 for redemption.
-
Enable Vertex AI API.
- Follow the steps in the documentation under the “Before you begin” section to enable Vertex AI API in your project.
- Enable Vertex AI from the console directly using the link from your active Google Cloud project.
Text embeddings
This is our way of converting product descriptions to numerical format, to loosely explain the concept, in order to find contextual matches for our searches. Text embeddings are dense vector representations of text. For example, the gemini-embedding-001 model generates 3072-dimensional vectors for a given piece of text. These dense vector embeddings are created using deep-learning methods similar to those used by large language models.
In this demo, we are going to use the text-embedding-004 / text-embedding-005 model which produces output of 768-dimensional vectors.
Load the embeddings for each project by running the following script from the repo:
python mongodb-groceries-agent/create-embeddings.py This will process all products in the collection and add/update the embedding field required for semantic search.
Build a MongoDB Atlas Vector Search index
Open your MongoDB Atlas cluster that you created earlier.
From the left-hand side menu, navigate to “Search and Atlas Search.”
The free tier cluster you created has a limit of three vector indexes. For this project, we’ll just need one—on the vector embeddings in inventory collection.
Click Create Search Index and use the following configuration:
Search Type: Vector Search
Index Name: inventory_vector_index
Database and Collection: grocery_story and inventory
Configuration Method: JSON Editor
Proceed with the Next button and paste the following configuration in the JSON editor:
{ "fields": [ { "numDimensions": 768, "path": "embedding", "similarity": "cosine", "type": "vector" } ] } Here’s a detailed description of the configuration:
numDimensions: 768
Number of values in the vector (its length).path: "embedding"
The document field where the vector is stored.similarity: "cosine"
The method used to compare vectors. Cosine similarity measures how similar two vectors are based on their direction.type: "vector"
Specifies that this field is for vector data (not text or numbers).
Set up ADK
Since we have already established we are are using Gemini 2.0 Flash for implementing this use case, let’s get started with ADK setup:
1: Activate Cloud Shell and make sure you see your active Google Cloud project. You can toggle between Cloud Shell Terminal (for running cloud commands) and Editor (for building projects) by clicking on the corresponding button from the Cloud Shell console that comes up.
2: Go to Cloud Shell Terminal. Create and activate a virtual environment by running the following commands one by one:
python -m venv .venv source .venv/bin/activate 3: Install ADK
pip install google-adk 4: From Cloud Shell Terminal’s root directory, clone the repository and navigate into the project folder:
git clone https://github.com/mongodb-developer/MongoDB-ADK-Agents cd MongoDB-ADK-Agents 5: From Cloud Shell Editor, copy your requirements.txt from the outer folder to the one inside it: “mongodb-groceries-agent”.
6: Navigate into that folder.
cd mongodb-groceries-agent 7: Install ADK and other dependencies using the requirements.txt file we have in the cloned project folder:
Note: This requirements.txt is heavily loaded with dependencies to scale for future agents in the project. Feel free to remove all the unused dependencies from the file. The important ones are google-adk and pymongo.
pip install -r requirements.txt 8: Set up environment variables
Create a .env file in the project folder from your Cloud Shell editor. This is needed to set up your environment variables like Google Cloud Project, Vertex AI usage flag, location and other details:
GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>> GOOGLE_CLOUD_PROJECT = <<your project id>> DATABASE_NAME=grocery_store COLLECTION_NAME=inventory CONNECTION_STRING="mongodb+srv://<user>:<password>@<cluster-url>/" Make sure you replace the placeholders with your values.
We are all set with the agent. Let’s understand the agent code.
Understanding the agent
In this implementation, we have the “grocery_shopping_agent” in the agent.py file:
This agent, like all others defined with ADK, requires only three main components: Model, Instruction and Tools!
root_agent = Agent( model="gemini-2.0-flash", name="grocery_shopping_agent", instruction=""" Start the Conversation with the user being a positive and friendly agent. Introduce yourself as the "Online Groceries Agent" and ask user how can you help them today. You are a customer agent for an ecommerce company and you are here to help the user with their shopping needs. Additional instructions: 1. Ask for details only if you don't understand the query and are not able to search. 2. You can use multiple tools in parallel by calling functions in parallel. """ , tools=[ find_similar_products, add_to_cart ] ) As you can see in the snippet above, we are using gemini-2.0-flash for the model, instruction that sets up the guidelines for the agent’s functioning and tools that carry out the important activities of the agent.
Let’s delve into the tools:
Tools
In this agent, we have employed two tools: finding similar products and adding to the cart.
Finding contextually similar products using MongoDB Vector Search
This is the contextually relevant match-finding part of the agent that we implement with MongoDB Vector Search and it searches for products with name and description that are semantically similar to a requested search text. It returns three similar products along with their project IDs.
The generate_embeddings part of the tool invokes Vertex AI’s text-embedding-004 model to return the text embeddings for the user’s search text at runtime.
def generate_embeddings(query): vertexai.init(project=PROJECT_ID, location=PROJECT_LOCATION) model = TextEmbeddingModel.from_pretrained("text-embedding-004") embeddings = model.get_embeddings([query]) return embeddings[0].values You will use the “inventory_vector_index” search index that you built earlier to perform vector search:
pipeline = [ { "$vectorSearch": { "index": "inventory_vector_index", "path": "embedding", "queryVector": vector_embeddings, "numCandidates": 100, "limit": 10 }, }, { "$project": { "_id": 0, "sale_price": 0, "market_price": 0, "embedding": 0, } } ] documents = client[DATABASE_NAME][COLLECTION_NAME].aggregate(pipeline).to_list() This query uses the $vectorSearch stage to:
Compare vector embeddings of the user’s search text against vector embeddings of the products in the database in the “embedding” field of our collection.
Consider up to the 100 most similar products and return the top 10 results.
To learn more about this pipeline stage, see Run Vector Search Queries.
To learn more about Vector Search in MongoDB, refer to the documentation.
Adding items to cart
This tool adds a product to the user's cart in MongoDB by taking in the product and user name as input.
client = pymongo.MongoClient(CONNECTION_STRING, tlsCAFile=certifi.where()) products_collection = client[DATABASE_NAME][COLLECTION_NAME] product = products_collection.find_one({"product": product}) cart_collection = client[DATABASE_NAME]["carts"] cart_collection.update_one({"username": username}, {"$addToSet": {"products": product}}, upsert=True) The code snippet above takes the product name and the user name and updates the record in the collection.
Agent in action
We can run the agent from the terminal or from the web user interface. Let’s start with the terminal. Run the following command from the Cloud Shell Terminal from within the root project folder.
adk run mongodb-groceries-agent This command triggers a conversation between the agent and the user.
Talk to the agent from the web UI by running the following command from outside the agent folder:
adk web 
If you add a product through the agent and check the carts collection, you’ll be able to see it as a new MongoDB document:
That’s it! You have successfully created and interacted with your agent using ADK, MongoDB Atlas, and Gemini.
Conclusion
In this tutorial, we've demonstrated how to build a simple yet powerful AI agent for grocery shopping using Google's Agent Development Kit and MongoDB Atlas Vector Search. This example showcases the potential of AI agents to automate mundane tasks autonomously with the context provided and also demonstrates the ability to scale with impact using Google’s ADK.
By combining the natural language understanding of Gemini with the semantic search capabilities of MongoDB Atlas, we've created an agent that can understand our needs and help us with our weekly grocery shopping in a more intuitive and efficient way. This is just the beginning! You can further enhance this agent by:
Integrating with a real e-commerce platform to actually place orders.
Adding memory to the agent to remember previous interactions and preferences.
Creating a multi-agent system with separate agents for recipe recommendations, price comparisons, and more.
The possibilities are endless! Explore the source repository for more advanced examples and start building your own AI agents to automate the tasks you find tedious, freeing up your time for more engaging and creative endeavors.
Top comments (0)