Compare products in chat

Product comparison lets users select products on your storefront and compare them with an Agent Studio agent. The agent responds in the chat with a comparison table based on the selected records. Comparison configurations control how the agent compares. Each configuration defines the comparison goal, instructions, selection limits, and whether the configuration is enabled.

Before you begin

You need an Algolia application with the Agent Studio feature and the Comparison component enabled.
To preview a configuration, you need an agent with an Algolia Search tool connected to an index.
To integrate a configuration, your storefront needs the InstantSearch chat widget.

How product comparison works

Users select products from the search results with a Compare toggle on each hit. The comparison bar shows the selected products.
When users select Compare, the comparison bar opens the chat and sends a comparison request that names the configuration. The selected records travel with the request.
Agent Studio replaces the request with the instructions from the configuration before calling the model. The chat doesn’t show a user message for the request: users go straight from the Compare button to the agent’s answer, and the comparison bar clears the selection.
The default instructions tell the agent to compare the selected records with the algolia_compare_products tool. The table has one column per selected product and one row per comparison criterion. The values come from the product records. Missing values are marked as “not listed”.

The comparison widgets require a configuration ID. Create and enable a configuration before you add them to your storefront.

Create a comparison configuration

Open the comparison configurations list

In the Agent Studio dashboard, open your agent, go to the Components section, and select the Comparison component.

Create a configuration

Select Create and fill in:

Name. An internal label. It’s not used in the integration.
Goal. What the comparison should help users do.
Instructions. Extra guidance for the agent, such as which attributes matter most.

Goal	What the agent does
Decision-relevant compare	Compares the attributes that drive a purchase decision, including differences from the descriptions, and ends with a one-line recommendation
Spec sheet	Lays out the structured attributes as a factual spec sheet, without opinions or a recommendation
Custom	Follows your instructions

Choosing a goal replaces the Instructions text. Editing the instructions switches the goal to Custom.

Configure the selection limits

In the configuration editor, adjust how many products users can compare at once:

Minimum products. The minimum number of products users must select before they can compare. The default is 2.
Maximum products. The maximum number of products users can select. The default is 3. The maximum is 6.

Keep the maximum low so users can review the comparison. If the maximum and minimum limits conflict, the editor adjusts the other limit to match the one you changed. Pass the same limits to the comparison widget to apply them on the storefront.

Customize the system prompt

The Advanced section shows the system prompt sent to the model. The default prompt tells the agent to compare the selected records with the algolia_compare_products tool, take every value from the records, and mark missing values as “not listed”. To write your own system prompt, turn on Customize and edit the text. Keep the instructions to render the table with algolia_compare_products, take the values from the selected records, and mark missing values as “not listed”.

Preview a comparison

Use the live preview to test a configuration before you enable it:

Select an Index connected to your agent through an Algolia Search tool.
Use Add product to search for records and add them to the selection, within the configured limits.
Select Run comparison.

The preview opens a chat with your draft agent and runs the comparison against the current draft of the configuration.

Enable and integrate a configuration

Enable the configuration

Turn on the Enabled toggle and save. The agent only applies a configuration to compare requests once the configuration is enabled and saved.

Copy the configuration ID

Copy the Configuration ID from the editor. Configuration IDs are stable: you can change the configuration’s behavior without updating your integration.

Add the widgets to your storefront

Select Integrate, choose an integration option, and copy the generated code. In InstantSearch, pass the configuration ID and selection limits to CompareBar (React) or compareBar (JavaScript), next to your hits and chat widgets. The comparison bar shows the selected products but doesn’t render a way to select them: add a Compare toggle to each hit that reads the shared selection from the render state.

import {
  Chat,
  CompareBar,
  Hits,
  useInstantSearch,
} from 'react-instantsearch';

function Hit({ hit }) {
  const { indexRenderState } = useInstantSearch();
  const { isSelected, toggleItem, canAddItems } =
    indexRenderState.compare ?? {};
  const selected = isSelected?.(hit.objectID) ?? false;

  return (
    <article>
      <h2>{hit.name}</h2>
      <label>
        <input
          type="checkbox"
          checked={selected}
          disabled={!toggleItem || (!selected && !canAddItems)}
          onChange={() => toggleItem?.(hit)}
        />
        Compare
      </label>
    </article>
  );
}

<Hits hitComponent={Hit} />
<CompareBar
  minItems={2}
  maxItems={3}
  configurationId="CONFIGURATION_ID"
/>
<Chat agentId="AGENT_ID" />

import { chat, compareBar, hits } from 'instantsearch.js/es/widgets';

search.addWidgets([
  hits({
    container: '#hits',
    templates: {
      item(hit, { html }) {
        // Replace `instant_search` with your index name.
        const { isSelected, toggleItem, canAddItems } =
          search.renderState.instant_search?.compare ?? {};
        const selected = isSelected?.(hit.objectID) ?? false;

        return html`
          <article>
            <h2>${hit.name}</h2>
            <label>
              <input
                type="checkbox"
                checked=${selected}
                disabled=${!toggleItem || (!selected && !canAddItems)}
                onChange=${() => toggleItem?.(hit)}
              />
              Compare
            </label>
          </article>
        `;
      },
    },
  }),
  compareBar({
    container: '#compare-bar',
    minItems: 2,
    maxItems: 3,
    configurationId: 'CONFIGURATION_ID',
  }),
  chat({
    container: '#chat',
    agentId: 'AGENT_ID',
  }),
]);

For a custom comparison bar or toggle, use the useCompare Hook (React) or the connectCompare connector (JavaScript). For examples and configuration options, see the comparison widget reference for React or JavaScript.

Compare from a single button

On pages without search results, such as the home page or a product page, you can start a comparison from one Compare products button. The button opens a dialog with a regular search interface: a search box, hits with a Compare toggle, and a Compare button. When users select Compare in the dialog, the dialog closes and the chat opens with the comparison. The pattern uses the same widgets as a results page, inside a <dialog> element:

The search box and hits inside the dialog belong to the same InstantSearch instance and index as the chat widget, so the comparison request reaches the chat.
The Compare button in the dialog comes from useCompare (React) or connectCompare (JavaScript). Their compare() function returns true when it sends the request, which is when to close the dialog.
Keep the widgets in the dialog mounted while it’s closed, so the chat widget has an entry point when it starts. InstantSearch runs an initial search for the hidden hits.

The selection is empty every time the dialog opens, because the comparison bar clears it after each request.

import { useRef } from 'react';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  Chat,
  Hits,
  InstantSearch,
  SearchBox,
  useCompare,
  useInstantSearch,
} from 'react-instantsearch';
import 'instantsearch.css/components/chat.css';

const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

function Hit({ hit }) {
  const { indexRenderState } = useInstantSearch();
  const { isSelected, toggleItem, canAddItems } =
    indexRenderState.compare ?? {};
  const selected = isSelected?.(hit.objectID) ?? false;

  return (
    <article>
      <h2>{hit.name}</h2>
      <label>
        <input
          type="checkbox"
          checked={selected}
          disabled={!toggleItem || (!selected && !canAddItems)}
          onChange={() => toggleItem?.(hit)}
        />
        Compare
      </label>
    </article>
  );
}

function CompareDialog({ dialogRef }) {
  const { items, canCompare, maxItems, compare, clearItems } = useCompare({
    minItems: 2,
    maxItems: 3,
    configurationId: 'CONFIGURATION_ID',
  });

  function onCompare() {
    // `compare()` sends the request and clears the selection.
    // It returns `false` when the chat is busy or the selection is too small.
    if (compare()) {
      dialogRef.current.close();
    }
  }

  function onClose() {
    clearItems();
    dialogRef.current.close();
  }

  return (
    <dialog ref={dialogRef} aria-label="Compare products">
      <SearchBox />
      <Hits hitComponent={Hit} />
      <footer>
        <span>
          {items.length} of {maxItems} selected
        </span>
        <button type="button" onClick={onClose}>
          Cancel
        </button>
        <button type="button" disabled={!canCompare} onClick={onCompare}>
          Compare {items.length}
        </button>
      </footer>
    </dialog>
  );
}

function App() {
  const dialogRef = useRef(null);

  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <button type="button" onClick={() => dialogRef.current.showModal()}>
        Compare products
      </button>
      <CompareDialog dialogRef={dialogRef} />
      <Chat agentId="AGENT_ID" />
    </InstantSearch>
  );
}

import instantsearch from 'instantsearch.js';
import { connectCompare } from 'instantsearch.js/es/connectors';
import { chat, hits, searchBox } from 'instantsearch.js/es/widgets';
import 'instantsearch.css/components/chat.css';

/*
<button type="button" id="open-compare">Compare products</button>
<dialog id="compare-dialog" aria-label="Compare products">
  <div id="searchbox"></div>
  <div id="hits"></div>
  <footer id="compare-actions"></footer>
</dialog>
<div id="chat"></div>
*/

const dialog = document.querySelector('#compare-dialog');

document.querySelector('#open-compare').addEventListener('click', () => {
  dialog.showModal();
});

const search = instantsearch({ indexName: 'instant_search', searchClient });

const compareActions = connectCompare((renderOptions, isFirstRender) => {
  const { items, canCompare, maxItems, compare, clearItems } = renderOptions;
  const container = document.querySelector('#compare-actions');

  if (isFirstRender) {
    container.addEventListener('click', (event) => {
      if (event.target.matches('[data-compare]')) {
        // `compare()` sends the request and clears the selection.
        // It returns `false` when the chat is busy or the selection is too small.
        if (compare()) {
          dialog.close();
        }
      }
      if (event.target.matches('[data-cancel]')) {
        clearItems();
        dialog.close();
      }
    });
  }

  container.innerHTML = `
    <span>${items.length} of ${maxItems} selected</span>
    <button type="button" data-cancel>Cancel</button>
    <button type="button" data-compare ${canCompare ? '' : 'disabled'}>
      Compare ${items.length}
    </button>
  `;
});

search.addWidgets([
  searchBox({ container: '#searchbox' }),
  hits({
    container: '#hits',
    templates: {
      item(hit, { html }) {
        const { isSelected, toggleItem, canAddItems } =
          search.renderState.instant_search?.compare ?? {};
        const selected = isSelected?.(hit.objectID) ?? false;

        return html`
          <article>
            <h2>${hit.name}</h2>
            <label>
              <input
                type="checkbox"
                checked=${selected}
                disabled=${!toggleItem || (!selected && !canAddItems)}
                onChange=${() => toggleItem?.(hit)}
              />
              Compare
            </label>
          </article>
        `;
      },
    },
  }),
  compareActions({
    minItems: 2,
    maxItems: 3,
    configurationId: 'CONFIGURATION_ID',
  }),
  chat({ container: '#chat', agentId: 'AGENT_ID' }),
]);

search.start();

On a page that already has search results, add the Compare toggle to those results instead, as shown in the integration step: a search box inside the dialog would change the page’s query.

Render a comparison table from product records

The chat widget includes a renderer for the algolia_compare_products client-side tool. The table has one column per selected product and one row per comparison criterion. When you enable a comparison configuration, Agent Studio adds this tool to your agent, and the default instructions tell the agent to use it. While a configuration is enabled, the tool’s name and input schema are read-only in the agent’s Tools list. Without the tool, the agent writes the comparison as a Markdown table in its answer. The agent passes the product object IDs and the criteria to algolia_compare_products, along with optional introductory text. Each criterion has a label and one value per product, taken from the product records, including details from the descriptions. The chat widget renders each product header with the same item template as the search results, using the records it holds: the selected products and any search results from the conversation. Missing values appear as —. While a configuration is enabled, you can edit the tool’s description from the agent’s Tools list, the way you edit the instructions. The model reads the description to decide when to call the tool and what to pass, so use it for guidance that applies to every comparison, such as “Lead with price”. The tool name and input schema are fixed, because the chat widget renders the table from them. Select Reset to default to return to the default description. If you manage the agent through the API instead, add the tool to the agent’s tools as a client-side tool, in the shape the Agent Studio API expects:

JSON

{
  "type": "client_side",
  "name": "algolia_compare_products",
  "description": "Renders a comparison table for the user: selected products across the top, one row per criterion. Pass objectIDs and criteria with one value per product from the records. Never repeat it in text.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "objectIDs": {
        "type": "array",
        "description": "The objectIDs of the products to compare, one column each, in display order",
        "items": { "type": "string" }
      },
      "criteria": {
        "type": "array",
        "description": "The comparison rows. Each row has a short label and one value per product, in the same order as objectIDs. Take values from the product records, including details from the description; use null when a record has no value.",
        "items": {
          "type": "object",
          "properties": {
            "label": { "type": "string", "description": "Short row label, e.g. \"Battery life\"" },
            "values": {
              "type": "array",
              "description": "One value per product, aligned to objectIDs; null when not listed",
              "items": { "type": ["string", "null"] }
            }
          },
          "required": ["label", "values"],
          "additionalProperties": false
        }
      },
      "intro": {
        "type": ["string", "null"],
        "description": "Optional one-line introduction shown above the table"
      }
    },
    "required": ["objectIDs", "criteria", "intro"]
  }
}

The widget shows one column per object ID, in the order the agent passes them, and one row per criterion. A value that’s missing, null, or shorter than the list of products appears as —. To change how the table looks, override the comparison tool in the chat widget’s tools object, using CompareProductsToolType as the property name. For more information, see the chat widget reference for React or JavaScript.

Send a compare request without InstantSearch

If you don’t use InstantSearch, send the compare request to the completions endpoint yourself. The user message text is a placeholder that names the configuration, and the selection travels as per-turn context:

Command line

curl "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions?compatibilityMode=ai-sdk-5" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "x-algolia-application-id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  --data-raw '{
  "messages": [
    {
      "role": "user",
      "parts": [{ "type": "text", "text": "__ALGOLIA_COMPARISON_CONFIGURATION_ID__" }],
      "metadata": {
        "turnContext": {
          "comparison_configuration_id": "CONFIGURATION_ID",
          "selected_products": "[{\"objectID\":\"1\",\"name\":\"Product A\"},{\"objectID\":\"2\",\"name\":\"Product B\"}]"
        }
      }
    }
  ]
}'

Replace CONFIGURATION_ID with the configuration ID, in both the placeholder and the turn context. The match is case-sensitive.
The placeholder must be the entire text of the user message. A message that wraps it in other text passes through to the agent unchanged.
selected_products is the selected records serialized as a JSON string. Remove internal attributes such as _highlightResult before serializing them.

Agent Studio replaces the placeholder with the configured instructions for the model and stores the user message without text. The response stream includes a transient data-prompt-shortcut part with the placeholder as sentinel and an empty displayText: don’t show a user message for the request, as the InstantSearch chat widget does. If the configuration doesn’t exist or you turned it off, the message passes through unchanged, so only send the placeholder for an enabled configuration. For the request schema, see the Agent Studio API reference.

Manage configurations

From the configurations list, you can:

Search configurations by name.
Duplicate a configuration to use it as a starting point. The copy is turned off by default.
Delete a configuration. Disable it first: you can’t delete an enabled configuration.

You can create up to 15 configurations per agent. The Create button shows the limit when you reach it.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Compare products in chat

Before you begin

How product comparison works

Create a comparison configuration

Configure the selection limits

Customize the system prompt

Preview a comparison

Enable and integrate a configuration

Compare from a single button

Render a comparison table from product records

Send a compare request without InstantSearch

Manage configurations

​Before you begin

​How product comparison works

​Create a comparison configuration

​Configure the selection limits

​Customize the system prompt

​Preview a comparison

​Enable and integrate a configuration

​Compare from a single button

​Render a comparison table from product records

​Send a compare request without InstantSearch

​Manage configurations

Before you begin

How product comparison works

Create a comparison configuration

Configure the selection limits

Customize the system prompt

Preview a comparison

Enable and integrate a configuration

Compare from a single button

Render a comparison table from product records

Send a compare request without InstantSearch

Manage configurations