Skip to main content
This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).
AI Mode lets shoppers ask product questions in natural language from the Autocomplete search box. An agent you publish in Agent Studio answers their questions. Each answer can include product cards with images, titles, and prices.

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.com domain for theme previews and all domains used to access your storefront. The app requires your primary domain and warns when your myshopify.com domain 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 /fr or /en-jp, turn on Use default dynamic selector in the Autocomplete settings. Autocomplete and AI Mode need this setting to load on those pages.
AI Mode isn’t available for B2B stores or stores that index data for Shopify Markets.

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.Screenshot of the 'AI Mode' card with a 'Ready' status, the 'Test - Agent Studio' agent selected, and an 'Enable AI Mode' button.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.Screenshot of the 'AI Mode' card with a 'Needs fixing' status and three required issues: 'Agent published', 'Rate limit setup', and 'Domains approved'.
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.
To connect a different agent, turn off AI Mode first. If the connected agent later fails a check, AI Mode stays on. The card shows the issues you need to fix.

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 to 1 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.
If you open the card before generation finishes, it warns that the suggestions index wasn’t found. Reopen the card after generation finishes. Suggestions can go stale after large catalog changes. To refresh them, regenerate them in Agent Studio, on demand or on a schedule. If you customized the Autocomplete menu with 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. Screenshot of the AI Mode chat with product cards, an answer about snowboards, and a prompt 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 the beforeAiModeProductTemplate 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 is on by default. To turn it off, clear Add to cart in chat in the AI Mode card. The setting saves when you click it.
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, see beforeAiModeProductTemplate.

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 the suggestions 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. A feedback 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, override getSearchPageURL 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.
To add or remove fields, or to send extra ones from your theme such as a metafield, use the 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
If you rename or remove these properties with a hook, update the instructions to match.

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.
The agent’s answers depend on its model and instructions. Test page-aware questions, such as “What’s popular here?” on a collection page, in AI Mode on your storefront. For tips on writing and testing instructions, see Prompting.

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

Set searchParameters.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 sends distinct: true so each product appears once. This overrides the agent’s distinct setting.

Customize the stock filter

Use the beforeAiModeFiltersString 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 the algolia_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
For tips on writing and testing instructions, see Prompting. For the tool’s options, see Grouped results.

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 as 20:100. Add this line to the agent’s instructions, so price questions use the product price instead of the price range facet:
Agent instructions
A product matches a price limit if at least one of its variants meets the price condition. For more on filters in the agent’s search tool, see Algolia Search tool.

”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 error Max 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, include elements.promptSuggestionsPlugin in 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.

Settings changed in Agent Studio don’t show

Open the AI Mode card to apply the change right away. For the settings this covers, see Apply changes from Agent Studio.

Share feedback

To share feedback about this beta feature, email Algolia support or join the Algolia community on Discord.
Last modified on November 18, 2026