Free shipping at CA$99.00 within Canada · A small number of remote areas are excluded
AI Agent
AI Shopping Assistant — User Guide
Source check (2026-07-15): chat, streaming output, generation stop, session management, and product comparison all use
/bff/ai/*; the browser never calls the AI API directly. Product citations must come from the current retrieval evidence and visible catalog, while quota, tenant feature switches, and session ownership are rechecked at the BFF/API boundaries.
1. Feature Overview
The AI Shopping Assistant is a conversational product recommendation tool integrated into the Trelanto Mall. You can describe your needs in natural language, and the system will automatically search for matching products and provide professional recommendations. Key capabilities include:
- Natural Language Product Search: Describe what you need in everyday language; AI automatically understands and retrieves matches
- Smart Product Recommendations: Precisely match products to your needs, returning a scored and ranked recommendation list
- Fast Intent Recognition: When you explicitly say things like "coming soon", "new arrival", "any product", or "just product info", the system identifies that shopping intent before retrieval and decides whether to search purchasable products, the visible catalog, or research/upcoming products
- Product Comparison Analysis: Select multiple recommended products for side-by-side comparison with difference and use-case analysis
- Multi-turn Conversation Context: AI remembers conversation history within the same session, supporting follow-up questions and refined needs
- Trilingual Support: Supports Chinese, English, and French conversations and recommendations
- Session Management: Create, rename, delete, and restore multiple independent conversations from a trash bin
2. Accessing the AI Assistant
Click the "AI Assistant" entry in the mall's navigation bar to enter the AI Shopping Assistant page. You can also visit the localized /ai path directly. The page is divided into three core areas:
| Area | Description |
|---|---|
| Left Session List | Manage multiple conversation sessions; supports creating, renaming, switching, and deleting |
| Central Chat Panel | Displays the complete conversation with AI, including user messages and AI replies |
| Right Recommendation Panel | Shows AI-recommended product cards, comparison results, and product action buttons |
On mobile devices, the session list opens as a drawer, and the recommendation panel is displayed below the conversation. The overall layout uses responsive design.
3. Feature Activation Prerequisites
The AI Assistant requires a system administrator to enable the AI feature in the admin panel. If you see a "Page Not Found" message when accessing the AI Assistant page, the feature is currently disabled — please contact your administrator.
The system checks the feature toggle status via the ai-feature-gate.tsx component, which uses the use-ai-feature-config Hook to fetch configuration from the BFF layer and determine whether to display the AI page.
4. Creating and Managing Sessions
4.1 Creating a New Session
Click the "New Session" button at the top of the session list. New session titles follow the current language: "新的 AI 会话" in Chinese, "New AI Session" in English, and "Nouvelle session IA" in French. After sending your first message, the system automatically generates a more appropriate session title based on your input.
4.2 Switching Sessions
Click any session in the left session list to switch. The central panel loads the corresponding session's message history, and the right recommendation panel shows the most recent recommendation result.
4.3 Renaming Sessions
Find the target session in the session list, click the edit icon, enter a new title, and save. Titles are limited to 60 characters.
4.4 Deleting and Restoring Sessions
- Soft Delete: After deletion, the session moves to the trash bin and can be viewed in "Trash" mode.
- Restore: Click the restore button in the trash bin to move the session back to the normal list.
- Permanent Delete: Permanently delete a single session from the trash bin. This action is irreversible.
- Empty Trash: Permanently delete all sessions in the trash bin at once.
5. Sending Messages and Getting Recommendations
5.1 Entering Messages
Type your needs in the input box at the bottom of the chat panel. The input character limit defaults to 1,000 characters; the exact limit is configured by the system administrator. Press Enter or click the send button to submit.
Example conversation:
User: I'm looking for a health supplement suitable for middle-aged adults, budget under $30
AI: Based on your needs, here are several recommended health products for middle-aged adults...
5.2 AI Thinking Process
After sending a message, the AI enters a "thinking" state. The page displays a thinking timer indicating the AI is processing. Thinking time typically ranges from 30 to 90 seconds (controlled by system configuration). If it exceeds the slow-hint threshold, the interface displays "AI is performing deep analysis, please be patient."
5.3 Streaming Replies
AI replies appear incrementally in the chat panel using a streaming "typewriter" effect. This lets you start reading without waiting for the complete response.
5.4 Recommendation Results
Alongside the AI's text reply (on the right panel on desktop, below on mobile), recommended product cards are displayed. Each card includes:
- Product image
- Product name and subtitle
- Price
- Stock status
- Recommendation reason and relevance score
- Product tags and attributes
- Focus labels (Winner / Finalist): indicating products the AI considers the best match for your needs
5.5 How Fast Intent Recognition Changes the Search Scope
By default, the AI prioritizes products with publicationStatus=published, salesStatus=available, and sellable stock. If your message clearly says that purchasability is not required or that you only need product information, the system can broaden retrieval to the visible catalog. If you mention "coming soon", "new arrival", or "market test", it can include market_test, coming_soon, and preorder products. Safety-sensitive intent, such as pregnancy, children, allergies, contraindications, or treatment-like phrasing, can only increase safety handling and never lowers the safety baseline.
5.6 No-Result Handling
When the AI cannot find matching products, it does not return an empty result. Instead, it generates a consultative reply guiding you to adjust your requirement description or offering alternative suggestions. This is provided by ai-no-result-response.service.ts.
6. Product Comparison Feature
6.1 Selecting Products for Comparison
In the recommendation panel, you can check multiple products for comparison. The maximum number of products that can be compared simultaneously is controlled by system configuration (default: 4).
6.2 Viewing Comparison Results
After selection, click the "Compare" button. The system calls the AI to perform an in-depth comparison analysis of the selected products, generating the following content:
| Comparison Dimension | Description |
|---|---|
| Common Strengths | Shared features across all compared products |
| Key Differences | Critical distinctions between products |
| Use Cases | Target audiences or usage scenarios for each product |
| Price Comparison | Analysis of price-level differences |
| Ingredient Comparison | Differences in ingredients or materials (applicable to supplements, etc.) |
Comparison results are rendered in Markdown format within the recommendation panel and recorded in session history for later review.
6.3 Multiple Comparisons
Within the same session, you can perform multiple different product comparisons. Each comparison generates an independent comparison group and summary.
7. Adding to Cart
Recommendation cards recommend products, not concrete variants. Images and titles open product details; the card button only represents the purchase action.
Button state is determined by structured purchase status, not by the AI's natural-language answer:
| Button | Meaning |
|---|---|
| Quick Add | The product currently has a directly addable sellable variant; clicking still goes through server-side cart validation |
| Choose Variant | The product has multiple variants or requires variant confirmation before purchase |
| Unavailable | The product is not currently purchasable, has no sellable variant, or is blocked by product-level state |
This operation is handled through the use-ai-add-to-cart.ts Hook and still goes through the mall's unified cart validation. Only products with publicationStatus=published, salesStatus=available, and a sellable variant can proceed through normal checkout. Research, upcoming, or preorder products surfaced by fast intent recognition are mainly for viewing and comparison, and are not guaranteed to be immediately addable or purchasable.
8. Quota and Usage Limits
8.1 Conversation Limits
The system tracks AI conversation usage on a weekly basis. Different identity types have different default quotas:
| User Type | Default Weekly Quota |
|---|---|
| Authenticated User | 10 times/week |
| Anonymous User | 3 times/week |
When the quota is exhausted, sending a message returns the prompt "Weekly AI chat limit reached." The quota automatically resets every Monday at UTC midnight.
8.2 Checking Remaining Quota
The page header displays current quota status, including this week's usage count and remaining count. This information is fetched via the /ai/quota endpoint.
9. Sorting Preferences
When sending messages, you can select a recommendation sorting strategy through interface controls:
| Strategy | Description |
|---|---|
| Best Match (effectiveness) | Default strategy; combines semantic relevance, product scoring, etc. |
| Price Low to High (price_low) | Sorted by ascending price |
| Price High to Low (price_high) | Sorted by descending price |
You can also specify a price range in your message, such as "under $30," and the AI will automatically recognize and apply price filtering.
10. Message Operations
10.1 Deleting Messages
In the chat panel, you can delete individual messages. After deletion, the message is no longer displayed, but other messages are unaffected.
10.2 Stopping Generation
While the AI is streaming output, click the "Stop" button to interrupt the current generation process. Already-output content is preserved.
11. Multilingual Support
The AI Assistant supports Chinese, English, and French. The system determines the language according to the following priority:
- The locale parameter specified by the user in the request
- The browser's Accept-Language header
- Defaults to Chinese
After switching languages, the AI replies and recommends in the corresponding language. Product information (title, description, etc.) also displays the translated version.
12. Disclaimer
The AI Assistant's recommendations are for shopping reference only and do not constitute professional advice. For health-related products, please consult a professional physician.
Disclaimer: AI suggestions are for shopping reference only. For medical issues, consult a professional.
13. Frequently Asked Questions
Q: The AI keeps "thinking" for a very long time without replying?
A: AI thinking time is typically 30–90 seconds. If it exceeds this time, the external AI service may be temporarily busy. Try refreshing the page or try again later.
Q: The recommendation results don't match my needs well?
A: Try describing your needs more specifically. For example, instead of just saying "supplements," say "calcium supplements for elderly adults, budget under $15." The AI provides more precise recommendations with more constraint information.
Q: Why are some products marked with a "featured" label?
A: The system automatically evaluates how well products match your needs. When a product's composite score is significantly higher than others, it is labeled as Winner (best recommendation) or Finalist (excellent candidate).
Q: What's the difference between anonymous and logged-in users?
A: Anonymous users have lower chat quotas (default 3 times/week) and sessions are not linked to a personal account. Logged-in users have higher quotas (default 10 times/week) and sessions are bound to their account, accessible across devices.
Q: How many products can the comparison feature support?
A: By default, up to 4 products can be compared simultaneously. The exact limit is configured by the system administrator.
Q: The page shows "Page Not Found"?
A: This means the AI feature is not enabled. Please contact the system administrator to enable the AI feature in "System Settings."
14. Technical Limitations
| Limitation | Default Value | Description |
|---|---|---|
| Max characters per message | 1,000 | Exceeding will be truncated |
| Weekly chat quota (authenticated) | 10 times | Resets every Monday |
| Weekly chat quota (anonymous) | 3 times | Resets every Monday |
| Max products for comparison | 4 | Adjustable by administrator |
| Max AI reply characters | 3,000 | Excess is truncated |
| Session title length limit | 60 characters | Auto-generated or manually edited |
All the above limits can be adjusted by the system administrator in the admin panel.