This agent sample efficiently provides tailored product recommendations within the ecosystem of a specific brand, merchant, or online marketplace. It enhances the shopping experience within its own context by using targeted data and offering relevant suggestions.

The personalized-shopping agent has the following capabilities:

• Navigates specific websites to gather product information and understand available options.

• Identifies suitable products using text and image-based search applied to a specific catalog.

• Compares product features or within a defined brand or marketplace scope.

• Recommends products based on user behavior and profile data.

The agent’s default configuration allows you to simulate interactions with a focused shopper. It demonstrates how an agent navigates a specific retail environment.

The key features of the personalized-shopping agent include:

• Environment: The agent can interact in an e-commerce web environment with 1.18M of products.

• Memory: The agent maintains a conversational memory with all the previous-turns information in its context window.

• Tools:

  Search: The agent has access to a search-retrieval engine, where it can perform key-word search for the related products.

  Click: The agent has access to the product website and it can navigate the website by clicking buttons.

• Evaluation: The agent uses tool_trajectory_avg_score and response_match_score to measure user satisfaction.

  The evaluation code is located under eval/test_eval.py.

  The unittest for tools is located under tests/test_tools.py.

1. Prerequisites:

• Python 3.10+

• uv for dependency management

• Install uv:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Clone this repo and install dependencies:

  cd adk-samples/python/agents/personalized-shopping
  uv sync

2. Installation:

• To run the agent, first download the JSON files containing the product information, which are necessary to initialize the web environment the agent will interact with.

  cd personalized_shopping/shared_libraries
  mkdir data
  cd data
  
  # Download items_shuffle_1000 (4.5MB)
  gdown https://drive.google.com/uc?id=1EgHdxQ_YxqIQlvvq5iKlCrkEKR6-j0Ib;
  
  # Download items_ins_v2_1000 (147KB)
  gdown https://drive.google.com/uc?id=1IduG0xl544V_A_jv3tHXC0kyFi7PnyBu;
  
  # Download items_shuffle (5.1GB)
  gdown https://drive.google.com/uc?id=1A2whVgOO0euk5O13n2iYDM0bQRkkRduB;
  
  # Download items_ins_v2 (178MB)
  gdown https://drive.google.com/uc?id=1s2j6NgHljiZzQNL3veZaAiyW_qDEgBNi;
  
  # Download items_human_ins (4.9MB)
  gdown https://drive.google.com/uc?id=14Kb5SPBk_jfdLZ_CDBNitW98QLDlKR5O

• Then you need to index the product data so that they can be used by the search engine:

  # Convert items.json => required doc format
  cd ../search_engine
  mkdir -p resources_100 resources_1k resources_10k resources_50k
  uv run python convert_product_file_format.py
  
  # Index the products
  mkdir -p indexes
  bash run_indexing.sh
  cd ../../

3. Configuration:

• Update the .env.example file with your cloud project name and region, then rename it to .env.

• Authenticate your GCloud account.

  gcloud auth application-default login

• Option 1: You may talk to the agent using the CLI:

  adk run personalized_shopping

• Option 2: You may run the agent on a web interface. This will start a web server on your machine. You may go to the URL printed on the screen and interact with the agent in a chatbot interface.

  cd personalized-shopping
  adk web

  Please select the personalized_shopping option from the dropdown list located at the top left of the screen. Now you can start talking to the agent!

Note: The first run may take some time as the system loads approximately 50,000 product entries into the web environment for the search engine. :)

The user can look for product recommendations with both text-based search and image-based search. Here're two quick examples of how a user might interact with the agent.

• Session file: text_search_floral_dress.session.json

• Session file: image_search_denim_skirt.session.json (The input image file for this session is example_product.png)

The evaluation assesses the agent's performance on tasks defined in the evalset. Each example in the evalset includes a query, expected tool use, and a reference answer. The judgment criteria are specified in test_config.json.

The evaluation of the agent can be run from the personalized-shopping directory using the pytest module:

uv sync --dev
uv run pytest eval

You can add more eval prompts by adding your dataset into the eval/eval_data folder.

To run unittest for tools, you can run the following command from the personalized-shopping directory:

uv run pytest tests

• The personalized shopping agent sample can be deployed to Agent Runtime. In order to inherit all dependencies of your agent you can build the wheel file of the agent and run the deployment.

1. Build Personalized Shopping Agent WHL File

   cd agents/personalized-shopping
   uv build --wheel --out-dir deployment

2. Deploy the Agent to Agents Engine

   cd agents/personalized-shopping/deployment
   uv run python deploy.py

   Note: This process could take more than 10 minutes to finish, please be patient.

When the deployment finishes, it will print a line like this:

Created remote agent: projects/<PROJECT_NUMBER>/locations/<PROJECT_LOCATION>/reasoningEngines/<AGENT_ENGINE_ID>

You may interact with the deployed agent programmatically in Python:

import dotenv
dotenv.load_dotenv()  # May skip if you have exported environment variables.
from vertexai import agent_engines

agent_engine_id = "AGENT_ENGINE_ID" #Remember to update the ID here.
user_input = "Hello, can you help me find a summer dress? I want something flowy and floral."

agent_engine = agent_engines.get(agent_engine_id)
session = agent_engine.create_session(user_id="new_user")
for event in agent_engine.stream_query(
    user_id=session["user_id"], session_id=session["id"], message=user_input
):
    for part in event["content"]["parts"]:
        print(part["text"])

To delete the deployed agent, you may run the following command:

uv run python deployment/deploy.py --delete --resource_id=${AGENT_ENGINE_ID}

You can also use the Google Agents CLI to create a production-ready version of this agent with additional deployment options.

Install the CLI (one-time):

uvx google-agents-cli setup

Create the project from this sample (replace my-personalized-shopping with your project name):

agents-cli create my-personalized-shopping -a adk@personalized-shopping

The Google Agents CLI will prompt you to select deployment options and provides additional production-ready features including automated CI/CD deployment scripts.

This agent sample uses the webshop environment from princeton-nlp/WebShop, which includes 1.18 million real-world products and 12,087 crowd-sourced text instructions.

By default, the agent loads only 50,000 products into the environment to prevent out-of-memory (OOM) issues. You can adjust this by modifying the num_product_items parameter in init_env.py.

For customization, you can add your own product data and place the annotations in items_human_ins.json, items_ins_v2.json, and items_shuffle.json, then launch the agent sample easily.

• Q1: I'm having issues with gdown during agent setup. What should I do?
• A1: You can manually download the files from the individual Google Drive links and place them in the personalized-shopping/personalized_shopping/shared_libraries/data folder.

We are grateful to the developers of princeton-nlp/WebShop for their simulated environment. This agent incorporates modified code from their project.

This agent sample is provided for illustrative purposes only and is not intended for production use. It serves as a basic example of an agent and a foundational starting point for individuals or teams to develop their own agents.

This sample has not been rigorously tested, may contain bugs or limitations, and does not include features or optimizations typically required for a production environment (e.g., robust error handling, security measures, scalability, performance considerations, comprehensive logging, or advanced configuration options).

Users are solely responsible for any further development, testing, security hardening, and deployment of agents based on this sample. We recommend thorough review, testing, and the implementation of appropriate safeguards before using any derived agent in a live or critical system.