This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).
Before you begin
To use AI Mode:- Use the Algolia app blocks in your theme, with the Autocomplete block turned on.
- Turn on Agent Studio for your Algolia application. The Algolia API key you use in the app must have the settings permission Agent Studio requires.
- Create and publish an agent with the Algolia Search tool configured to search your store’s products index (
<prefix>products). - Add your storefront domains to the agent’s approved domains.
Include your
myshopify.comdomain for theme previews and all domains used to access your storefront. The app requires your primary domain and warns when yourmyshopify.comdomain is missing. It doesn’t check other domains. - Set a rate limit for the agent. Without one, anyone can send the agent unlimited questions and use your LLM credits, so the app doesn’t let you turn on AI Mode until the agent has one.
- If your store uses language or market URL prefixes, such as
/fror/en-jp, turn on Use default dynamic selector in the Autocomplete settings. Autocomplete and AI Mode need this setting to load on those pages.
Turn on AI Mode
1
Open the AI Mode settings
In your Shopify admin, open the Algolia AI Search & Discovery app,
go to the Search options tab,
and find the AI Mode card in the Search basics section.
If the card shows an application or API key error, fix it and click Try again.
If no agents are available, create one in Agent Studio and click Refresh.

2
Connect an agent
Under Connect an agent, select an agent and click Connect and check.
The app checks that the agent meets the requirements and shows its product filter under Store filters configured.The app lists required fixes and recommended changes.
Issues that require a fix prevent activation and appear with an 
× icon.
Use each row’s link to update the agent in Agent Studio, then click Check again.
3
Turn on the setting
When the card shows Ready, click Enable AI Mode,
then confirm in the Enable AI Mode? dialog.
AI Mode appears on your storefront right away.
Set up your agent for AI Mode
AI Mode works with any published agent that meets the requirements. The following settings add features or improve answers. Set them on the agent in Agent Studio, not in the Algolia app. AI Mode can also use other tools you add to the agent, including tools provided by a Model Context Protocol (MCP) server.
Some behaviors need lines in the agent’s instructions, such as grouped results and price questions.
For these fixes, see Troubleshooting.
Configure grouped results
Turn on Grouped Results. In Advanced settings, set Min results per group to1 so groups with only one or two matching products can still appear.
Keep the other settings at their defaults.
If products aren’t grouped, see Products aren’t grouped.
Set up search box suggestions
1
Generate the suggestions in Agent Studio
In Agent Studio, open the agent, go to Components > Search Box > Searchable prompt suggestions, and click Set up.
For the options, see Searchable prompt suggestions.
2
Open the AI Mode card
In the Algolia app, open the AI Mode card.
The app detects that you turned on prompt suggestions and shows them in your search box.
Users see the suggestions the next time they load a storefront page.
beforeAutocompleteMainTemplate,
include elements.promptSuggestionsPlugin in the returned template.
Without it, the suggestions don’t appear.
Apply changes from Agent Studio
The app copies some agent settings to your store: the agent’s index filters, User feedback, and Searchable prompt suggestions. The app checks the agent once a day and applies any changes it finds, so a change you make in Agent Studio reaches your store within a day. To apply it right away, open the AI Mode card in the Algolia app. Opening the card applies the changes. To confirm that the app has applied them, click Check again. Users see the change the next time they load a storefront page.What shoppers see
Selecting AI Mode in the Autocomplete panel opens the chat. If the shopper has already entered a search query, the chat submits it as the first question. The chat opens at the bottom right of the page. On screens 680 pixels wide or less, it opens full screen. Pressing Escape or selecting Close returns focus to the search field.
Product cards
Products appear in a carousel below the answer. Each card shows an image, title, and price. Selecting a card opens the product. If the answer is still loading, selecting a card stops it. To customize the cards, use thebeforeAiModeProductTemplate hook.
Add to cart
Product cards in the chat have an Add to cart button. Selecting Add to cart adds one item to the user’s cart, and the button briefly changes to Added. The app doesn’t open the cart drawer. How the cart updates depends on your theme.- Variant records: the button adds the card’s variant.
- Product-level records or Distinct: the card shows a menu to choose a size, color, or other option before adding.
- Out of stock: a sold-out item shows an Out of stock link to the product page instead of the button. In the menu, sold-out options are unavailable and marked Out of stock.
Add to cart uses Shopify’s cart actions, which every Online Store theme supports.
On themes based on Dawn or Horizon, and on themes that set up Shopify’s cart actions themselves, the cart updates in place and the chat stays open.
On other themes, Shopify reloads the page after the user adds the item.
Users can reopen the chat and continue the conversation.
Add to cart limitations
- The app reads stock from your index. The index can show an item as in stock when Shopify can’t sell it, for example with untracked inventory or when stock is only at a location that doesn’t ship. The user sees Out of stock after selecting Add to cart.
- While the agent is generating an answer, the chat may not respond when users select Add to cart.
- Scrolling a chat clears a product card’s Added confirmation.
- To include the Add to cart button, add
${cart}to your custom card template. For more information, seebeforeAiModeProductTemplate.
Style the button
The control uses these classes. Style them with CSS. The chat’s--ais-* CSS variables also apply.
The
.algolia-assistant-cart element has a data-state attribute you can target in CSS:
Grouped results
When the agent shows products in groups, each group has a title and its own carousel of product cards. The agent decides when to group, for example when an answer covers snowboards and shirts. Once Grouped Results is on, the chat shows product cards only in groups. A group with one product shows a card at the same width as the cards in other groups, including on phones. To turn on grouping, see Set up your agent for AI Mode. The group headings, such as N results, and the Curating results… message are available only in English.Follow-up suggestions
Suggested follow-up questions appear as buttons under the latest answer, after the answer finishes. Selecting one asks that question, with the same page context as any other question. Suggestions are in the language of the answer. To turn on follow-up suggestions, see Set up your agent for AI Mode. To hide or restyle them, use thesuggestions template in the beforeAiModeOptions hook.
Thumbs up and down
Thumbs up and down buttons appear under each finished answer. They don’t appear on an answer that ended in an error. For how Agent Studio stores the ratings, see Feedback. To turn on user feedback, see Set up your agent for AI Mode. The button labels and the confirmation message are in English only. Afeedback option set in the beforeAiModeOptions hook overrides the Agent Studio setting.
View all
The product carousel has a View all link. It opens your store’s search page with the agent’s query. On the search page itself, it reloads the page with the new query. View all shows only when Grouped Results is off. Grouped answers show product cards in groups without it. To send View all to a different page, overridegetSearchPageURL in the beforeAiModeOptions hook.
Search box suggestions
When the agent has searchable prompt suggestions, up to three suggested questions appear in the Autocomplete panel once the user starts typing. They appear under an AI Mode header. Selecting one opens AI Mode and asks that question. To set up search box suggestions, see Set up search box suggestions.Conversations
The conversation follows the shopper from page to page in the same browser tab. The chat stays closed until the shopper opens it again. A new tab, or selecting New chat, starts a new conversation. If an answer hasn’t started after 10 seconds, the chat shows “Still working…”. After 30 seconds, it stops waiting and shows an error with a Retry button.Language
AI Mode sends the storefront language with each question. To get answers in each user’s language, tell the agent in its instructions to reply in the language of the conversation. Answer quality depends on the agent’s instructions and model.Page awareness
AI Mode tells the agent which page the user is viewing. Users can ask “What is this made of?” on a product page or “Which products cost less than $50?” on a collection page. They don’t need to name the product or collection. The app sends this information with every question. If the user moves to another page during the same chat, the next question includes context for the new page.
Notes:
- On
/collections/all, the app doesn’t send any collection information. - On a product page, the app sends only the product information,
even when the user opened it from a collection.
For example,
/collections/winter-boots/products/trail-boot. - The app sends only information publicly available on your storefront.
- The app sends titles and descriptions in the storefront’s language.
- Agent Studio treats this information as untrusted: the agent uses it as facts but doesn’t follow instructions written in it, such as text in a product description. Agent Studio stores it with the conversation, under your retention settings.
beforeAiModeOptions hook.
If the context exceeds Agent Studio’s size limits,
Agent Studio rejects each question sent with that context.
Product pages
The agent receives the product’s title, vendor, type, and description. It doesn’t receive the variant the user selected, so the agent answers questions about the selected size or color for the product in general. The app sends only the beginning of the product description. It doesn’t send metafield values or information from Shopify apps that add sizing tables to product pages. For more information, see The agent misses details from a long product description.Collection pages
For the agent to filter by the collection, turn on Algolia on collection pages: in the app, go to the Collection pages tab and click Enable. The agent can filter by collection once the reindex finishes. For more information, see Collection search pages. If Algolia isn’t enabled on collection pages, the agent knows which collection the user is viewing but can’t filter results by that collection. For example, a question about “the Hydrogen collection” can return unrelated products.Add guidance to your agent’s instructions
You can guide how the agent uses page information through its instructions in Agent Studio. For example, you can tell it to say when the description doesn’t answer a question instead of guessing, or to exclude the product the user is viewing from “similar” suggestions. The following instructions are examples.Product pages
Agent instructions
Collection pages
Agent instructions
Page awareness limitations
- “Similar” can still show the viewed product. Without grouped results, the chat shows a card for every product the agent’s search returns. Instructions change the agent’s answer, not the cards, so the viewed product can still appear in the carousel.
Filter products
AI Mode shows products from your store’s products index. Two things decide which products:- Your agent’s filter, set on the products index in the agent’s Algolia Search tool.
- Your store’s out-of-stock setting:
AI Mode combines them with
AND.
For example, the agent filter vendor:"Burton" with Hide all out of stock items in search results gives vendor:"Burton" AND inventory_quantity > 0.
If your store shows out-of-stock items, AI Mode doesn’t add a stock filter, and the agent’s filter applies on its own.
AI Mode sends a copy of the agent’s filter because a filter in the request replaces the agent’s own.
Set the agent’s filter
SetsearchParameters.filters on your products index in the tool’s JSON, with Other tools in Agent Studio or the Agent Studio API.
For an example, see Configure the Search tool.
The tool form in the dashboard doesn’t have a filter field.
A changed filter reaches your store as described in Apply changes from Agent Studio.
The AI Mode card shows the active filter under Filter in use.
Don’t put filters in Custom
A filter in Custom (searchControls.custom) overrides every other filter.
AI Mode then can’t apply your out-of-stock setting or the beforeAiModeFiltersString hook, and the AI Mode card shows a warning.
Move the filter to searchParameters.filters, or add the stock condition to the Custom filter yourself,
for example vendor:"Burton" AND inventory_quantity > 0.
Filter syntax
AI Mode adds AND <stock filter> to the end of the agent’s filter, without parentheses.
Algolia reads vendor:"Burton" OR vendor:"Nike" AND inventory_quantity > 0 as (vendor:"Burton" OR vendor:"Nike") AND inventory_quantity > 0.
The agent’s filter must follow Algolia’s rules for parentheses:
OR groups inside AND work, but AND groups inside OR return an error.
Show one result per product
If your store shows products instead of variants, AI Mode sendsdistinct: true so each product appears once.
This overrides the agent’s distinct setting.
Customize the stock filter
Use thebeforeAiModeFiltersString hook to change the stock filter.
The beforeAutocompleteFiltersString hook doesn’t apply to AI Mode.
The hook receives the stock filter, which can be an empty string.
AI Mode combines the returned string with the agent’s filter using AND.
Returning an empty string removes the stock filter but preserves the agent’s filter.
The hook must return a string.
If it returns nothing, AI Mode also removes the stock filter.
The returned filter must follow the same syntax rules.
Translate labels
AI Mode uses the following keys in thealgolia_search.translations shop metafield.
Missing or empty keys use their English defaults.
Shopify Translate and Adapt stores a separate copy of the metafield JSON for each language.
Add any missing keys to each language’s copy of the metafield.
Translate each language directly, and use a market adaptation only when needed.
For instructions, see Widget text translations.
You can also change the chat’s labels with the
beforeAiModeOptions hook.
Text set by the hook overrides translations.
The hook doesn’t change the AI Mode button or the loading messages.
To change the button, use the beforeAutocompleteAiModeTemplate hook.
To hide a label, such as the disclaimer, use CSS.
Analytics
When you turn on click and conversion events, AI Mode sends click and view events for product cards. The web pixel tracks purchases of clicked products as conversions. Shopify’s web pixel doesn’t report items added through the chat. When a user adds a product from a chat card, AI Mode sends its own add to cart event to Algolia Insights. At checkout, the pixel sends a conversion event that links each purchased product to the chat answer that showed it. For usage and conversation data, see Agent Studio analytics. Its Impact tab shows how many conversations led to clicks and conversions.Turn off AI Mode
In the AI Mode card, click Disable AI Mode. The button disappears from your storefront. The app keeps the connected agent, so you can turn AI Mode back on without selecting it again.Troubleshooting
Use these checks to resolve common AI Mode issues.The AI Mode button doesn’t appear
Check that you turned on AI Mode and that Autocomplete loads on the page. Confirm that your store meets the requirements, including the dynamic selector setting for language or market URL prefixes.Every question returns an error
Open the AI Mode card and resolve any failed checks. In Agent Studio, confirm that:- The API key for the agent’s LLM provider is valid. The AI Mode card doesn’t check this key.
- The Algolia Search tool still includes your store’s products index.
- The agent’s approved domains include the domain where the error occurs.
- The agent hasn’t reached its rate limit.
The chat can’t load
If the chat shows “AI Mode couldn’t load.”, the browser couldn’t download the chat files. Click Retry.Products don’t match the configured filter
Open the AI Mode card to refresh the saved filter, then check Filter in use. If the card warns about custom search parameters, see Don’t put filters in Custom. For filter behavior and exceptions, see Filter products.Products aren’t grouped
The agent decides when to call the grouped results tool. Once Grouped Results is on, the chat shows product cards only in groups. If the agent answers without creating groups, the answer shows text but no product cards. If the agent doesn’t group products, you can add instructions like these:Agent instructions
Price questions fail or return nothing
Price questions can fail if the agent uses a price range facet value that doesn’t exist in your index, such as20:100.
Add this line to the agent’s instructions, so price questions use the product price instead of the price range facet:
Agent instructions
”Similar” shows the same product
On a product page, a request for something similar can return the product the user is viewing. Add the “similar” line from the product page guidance to the agent’s instructions. The line changes the agent’s answer, but the viewed product can still appear in the product cards. For details, see Page awareness limitations.The agent misses details from a long product description
The app sends the first 512 bytes of each page value, about 500 characters of English text. Details beyond the 512-byte limit, such as size or fit information, don’t reach the agent with the question. If those details are in your index, the agent can still find them by searching your products. To send a specific detail, such as a metafield, see Send an extra field to the agent. For Agent Studio’s limits on page context, see Per-turn context.An answer ends with “Something went wrong”
If the full answer appears and then the chat shows “Something went wrong”, the agent might have reached its step limit. In that case, Agent Studio returns the errorMax steps per completion limit was reached.
Grouped answers use more steps.
In Safety Controls > Cost controls, increase Max steps per completion above its current value.
If the current value is below 20, try 20.
In the API, the setting is config.max_iterations.
For the setting, see Cost control.
If an answer ends in an error, the chat doesn’t save it.
Reloading the page removes that answer from the chat.
Search box suggestions don’t appear
Check that:- Generation finished in Agent Studio, and you opened the AI Mode card afterward. If the card warns that the suggestions index wasn’t found, reopen it after generation finishes.
- If you customized the Autocomplete menu with
beforeAutocompleteMainTemplate, includeelements.promptSuggestionsPluginin the returned template. Without it, the suggestions don’t appear. - The user has started typing in the search box. Suggestions don’t appear in an empty search box.
User feedback or follow-up suggestions don’t appear
Check that:- User feedback or Follow-up prompt suggestions is on in the agent’s settings. A User feedback change reaches your store as described in Apply changes from Agent Studio. Changes to Follow-up prompt suggestions take effect immediately.
- The answer didn’t end in an error.