gem-hunter
Language: Python
AgenticShop is a solution accelerator that demonstrates how to build an intelligent, multi-agent retail experience powered by Azure Database for PostgreSQL.
AgenticShop is a GenAI-powered e-commerce demo that showcases how multi-agent workflows, powered by LlamaIndex, can drive personalized product discovery using unstructured data like user reviews and preferences. This demo runs fully on Azure, and can be deployed quickly using the Azure Developer CLI.
Explore how intelligent agents handle search, sentiment, memory, and personalization with observability and memory persistence.
AgenticShop is a GenAI-powered e-commerce demo that showcases how multi-agent systems and in-database intelligence can deliver personalized shopping experiences.
Built on LlamaIndex, the app leverages:
pg_diskann for fast vector search over product dataazure_ai for in-database sentiment and feature extractionThe frontend also features an Agentic Flow UI, providing real-time visibility into how agent workflows are triggered and executed—helping users understand what's happening under the hood.
Product Personalization
A multi-agent workflow built using LlamaIndex's Workflow module powers personalized product discovery by analyzing user preferences and reviews in real time.
Agentic Query Routing A smart search box routes user queries to the appropriate tool—vector search, sentiment-aware querying, or personalized agent workflows—based on inferred intent.
Using a curated electronics dataset (products, reviews, user profiles), AgenticShop enables:
The result is a responsive and intelligent user experience where AI agents dynamically interpret and fulfill user queries—whether it’s finding the right product, analyzing reviews, or adjusting user preferences.
The following image shows the high-level architecture of the solution, highlighting how various Azure services and components work together to power the agentic shopping experience.
Frontend:
Backend:
Observability:
The solution is deployed entirely within a single Azure Resource Group and uses the following core infrastructure:
The following are prerequisites for deploying this solution:
Contributor role and Role Based Admin Control Administrator role for the subscription)Clone the repository. Once done, navigate to the repository:
git clone https://github.com/Azure-Samples/postgres-agentic-shop.git
cd postgres-agentic-shopTo log in to Azure CLI, use the following command. You can use the --use-device-code flag if the command fails.
az login
To log in to Azure Developer CLI, use this command. You can use the --use-device-code flag if the command fails.
azd auth login
In the root of the project, execute the following command to create a new azd environment. Provide a name for your azd environment:
azd env new
The azd workflow automatically uses PowerShell hooks on Windows and Bash hooks on macOS and Linux. PowerShell is not required when deploying from macOS, Linux, or a Linux-based Dev Container.
⚠️ IMPORTANT: This step is only required if you are deploying from Windows. macOS and Linux users can skip this step.
If you are on Windows, run the following command in your current terminal session to allow execution of pwsh scripts located in the azd-hooks directory:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
NOTE: This solution uses PostgreSQL username/password authentication. During deployment, the admin login and password are autogenerated and written to your project’s
.envfile. Keep your.envfile out of version control.
Run the following command to provision the resources:
azd up
Once the above command is executed, the azd workflow prompts user to select the subscription for deployment, location and the resource group to create.
Make sure that you have enough Azure OpenAI model quota in the region of deployment. The azd workflow automatically filters and shows the region where the Azure OpenAI quota is available. The Azure OpenAI quota required for GlobalStandard deployment type for this solution is listed below. This configuration can be changed from the main.parameters.json file in the infra directory using the following parameters:
GlobalStandard GPT-4o: 50K TPM - AZURE_OPENAI_CHAT_DEPLOYMENT_CAPACITYGlobalStandard text-embedding-3-small: 70K TPM - AZURE_OPENAI_EMBED_DEPLOYMENT_CAPACITYIf you have changed the above parameters from the main.parameters.json file, you must change the following configuration in main.bicep file so that the changes are reflected in automatic Azure OpenAI region filtering as well:
@metadata({
azd: {
type: 'location'
usageName : [
'OpenAI.GlobalStandard.gpt-4o, 50'
'OpenAI.GlobalStandard.text-embedding-3-small, 70'
]
}
})
Before the azd workflow proceeds, checks are performed in the selected infra region and recommendations are generated on failure for following cases to ensure that the deployment is successful.
After creating the resource group, the workflow prompts the user for the Azure Container Apps deployment. Input yes as shown below -- this will build the docker images and deploy to Azure Container Apps. The docker image build can take 15+ mins.
Do you want to deploy Azure Container Apps? (y/n): yesThe deployment might take several minutes. Progress updates will be displayed in the terminal and can also be tracked via the Azure Portal.
Once the deployment is complete, azd will output the application URLs for the deployed services.
⚠️ IMPORTANT: Upon first time loading the frontend URL, this will kick off the data load step. This may take 1-2 minutes where you will see a spinner icon. You may need to refresh the browser to load the user interface. Note: Make sure to copy the frontend URL displayed in the output and open it in your browser to access the application.
To destroy all the resources that have been created in the steps above, as well as remove any accounts deployed by the solution accelerator, use the following command:
azd down --purge
The --purge flag deletes all the accounts permanently.
azd cli._, # etc. are used while initializing or creating a new environment or resources. Refer to rules and restrictions for naming conventions.azd workflow. Attach Contributor role and Role Based Access Control Administrator role to user permissions before deploying the solution accelerator.The resource entity provisioning state is not terminal. Please wait for the provisioning state to become terminal and then retry the request error occurs, restart the deployment using the azd up command.AgenticShop uses a modular, event-driven multi-agent system built on LlamaIndex Workflows to personalize the shopping experience. Each agent has a clearly defined role, and they collaborate through structured events to fulfill complex user intents.
These agents are orchestrated via LlamaIndex’s Workflow module, providing traceability, modularity, and fallback behavior in case of timeouts.
The system uses mem0 to persist user preferences across sessions. This memory influences agent behavior in real time:
mem0_chatstore table in PostgreSQLAgent prompts can be modified in
backend/src/agents/prompts.pyto customize tone, structure, or output logic.
Below is the LlamaIndex workflow generated via its visualization tool:
Each step function in the workflow is connected by events, enabling modular and reactive execution.
workflow.run(input_event), and proceeds by chaining steps through emitted events. This allows the system to reactively evolve based on user input and intermediate results.This event-driven architecture ensures agents are loosely coupled, traceable, and easy to modify or extend.
Experience how AgenticShop delivers tailored product suggestions through multi-agent intelligence:
Start the frontend (the URL was output earlier as part of azd up command) and choose a pre-set user profile. Each profile has a different set of profile pre-configured
Perform a search (e.g., “Wireless headphones”) → products are retrieved via semantic search and personalized against profile preferences.
Select any product and view the personalized content on a product detail page. Note that the personalization shows information that is relevant for this user.
On the top right is the Agentic Flow drawer which provides an under-the-hood look at the multi-agent flow. Open the Agentic Flow panel to inspect how each agent participates in this multi-agent flow. Note that all agents are not always triggered. For example, in this case the review agent is not triggered.
Now lets try a command to update our personalization. In the command bar input new preferences (e.g., "Show critical reviews about durability").
This will re-trigger the personalization workflow and update the product page with this new information.
Open the Agentic Flow panel to see confirm that the Review Agent has now been triggered.
"Always show me critical reviews about durability." In case the memory is updated a "Memory updated" message is shown. This new information be stored in memory using mem0.
Now, open a different product whose personalization hasn’t been generated yet. You should see a new section highlighting critical reviews about durability as part of the personalized output.
⚠️ Note: Personalizations are cached for performance. If a product’s personalization was generated before the new memory was saved, it may not reflect the updated preference. Personalization workflow typically takes ~10 seconds to complete.
This walkthrough showcases how AgenticShop delivers a responsive, transparent, and memory-driven shopping experience.
AgenticShop includes a powerful Command Routing Agent that interprets user queries and dynamically routes them to the appropriate tool—enabling a seamless, natural-language search experience.
This agent is equipped with three tools, each designed to handle a distinct type of user query:
| Tool | Purpose |
|---|---|
query_about_product |
Triggers the multi-agent personalization workflow for a selected product |
search_products |
Performs vector search using pg_diskann |
query_reviews_with_sentiment |
Combines sentiment + feature filters to rank products based on review insights |
General Search
Query: "Waterproof headphones"
→ The Command Routing Agent selects the search_products tool and performs a semantic vector search.
Sentiment-Based Query
Query: "Wireless headphones with good noise cancellation"
→ The agent uses the query_reviews_with_sentiment tool to return products with strong sentiment around the feature.
Personalization Trigger
Query (on a product detail page): "Always show if red color is available in stock"
→ The agent invokes the query_about_product tool, launching the multi-agent personalization workflow.
⚠️ If a sentiment-based query fails to map to a known feature or lacks reviews, the system gracefully falls back to a general vector search and displays a notice.
AgenticShop supports intelligent query handling over a limited dataset. To get meaningful results, it’s important to understand what product categories and features are supported, and how the system interprets your queries.
The system currently supports three categories only:
❌ Queries outside these categories (e.g., "laptops", "TVs", "keyboards") will return no results.
You can view all supported features per category in backend/data/features.csv.
AgenticShop supports two core query types via distinct tools:
Used for general product discovery, e.g.:
This is powered by pg_diskann, which performs a vector search over product descriptions and specs.
💡 Internally, the system tries to infer the product category from the query. If the model fails to map it to one of the 3 supported categories, no results will be returned.
Used for feature-based product discovery with sentiment context, e.g.:
This combines:
The system attempts to map:
If either mapping fails, the query will not yield accurate results.
Query: "Smartwatch with great battery life"
This might not work because:
The system supports synonyms and close variations of features:
All of these map to the tracked feature Noise Cancellation:
Even if a feature is supported, the system needs relevant review content to extract sentiment.
If no reviews discuss a feature for a product, it won’t affect the ranking—even if the feature exists in product specs.
Use the examples below to test how different tools behave:
(Used when you're on a product page)
(General product discovery with semantic matching)
(Feature-based preference queries)
💡 If a feature is supported but missing in user reviews, results may fall back to standard search with a notification.