Build an AI-powered search experience

Combine the searchBox, chat, and autocomplete widgets to build an AI-powered search experience with InstantSearch.js.

This widget is and is subject to change in minor versions.

Pair classic InstantSearch widgets with an Agent Studio chat agent to give users a conversational entry point alongside their search results. This guide wires together:

• An “AI Mode” button on the search box that opens a chat panel loaded with the user’s query.
• The chat widget itself, with hidden context to share session metadata.
• AI-generated prompt suggestions in the autocomplete drop-down menu.
• Streaming controls so you can stop or resume an in-flight response.

Prerequisites

• An Agent Studio agent ID.
• An instantsearch instance with an Algolia search client.
• instantsearch.js installed at a version that ships AI Mode (for example, the release from PR algolia/instantsearch#6982 or later).

1. Mount the chat widget

   Add the chat widget on the same instantsearch instance as your search UI. The other widgets in this guide rely on it being present.

   JavaScript

   import algoliasearch from "algoliasearch/lite";
   import instantsearch from "instantsearch.js";
   import { chat } from "instantsearch.js/es/widgets";
   
   const search = instantsearch({
     indexName: "instant_search",
     searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
   });
   
   search.addWidgets([
     chat({
       container: "#chat",
       agentId: "YOUR_AGENT_ID",
     }),
   ]);
   
   search.start();
   
2. Enable AI Mode on the search box

   Set aiMode on searchBox to render an AI Mode button next to the input. Clicking it opens the chat widget and forwards the current query.

   JavaScript

   import { chat, searchBox } from "instantsearch.js/es/widgets";
   
   search.addWidgets([
     searchBox({
       container: "#searchbox",
       aiMode: true,
     }),
     chat({
       container: "#chat",
       agentId: "YOUR_AGENT_ID",
     }),
   ]);
   
3. Show prompt suggestions in autocomplete (optional)

   If you use EXPERIMENTAL_autocomplete, surface AI-generated prompt suggestions alongside hits. See showPromptSuggestions for the full configuration surface.

   JavaScript

   import { EXPERIMENTAL_autocomplete } from "instantsearch.js/es/widgets";
   
   search.addWidgets([
     EXPERIMENTAL_autocomplete({
       container: "#autocomplete",
       showPromptSuggestions: {
         indexName: "prompt_suggestions",
       },
       indices: [
         {
           indexName: "instant_search",
           templates: {
             item: ({ item }, { html }) => html`<div>${item.name}</div>`,
           },
         },
       ],
     }),
   ]);
   

   Selecting a prompt suggestion opens the chat widget on the same index and sends the suggestion as the first message.

4. Pass session metadata with hidden context

   Use the context option to share metadata with the agent on every message. The widget serializes the value as JSON and adds it to the user message as a hidden text part. Users don’t see it in the chat UI, but the agent does.

   The widget sends context to the agent in plain text. Don’t put secrets, access tokens, or personally identifiable information you don’t intend to share with the model in this field.

   Static object

   chat({
     container: "#chat",
     agentId: "YOUR_AGENT_ID",
     context: { locale: "en", segment: "logged-in" },
   });
   
5. Handle the streaming lifecycle

   Listen for response completion with onFinish, and use the connectChat connector if you need a custom Stop button or to call resumeStream() manually. See Streaming and resumption on the chat widget reference for the full status surface.

   JavaScript

   search.addWidgets([
     chat({
       container: "#chat",
       agentId: "YOUR_AGENT_ID",
       resume: true,
       onFinish: ({ message, isError }) => {
         if (!isError) {
           analytics.track("chat_message_completed", { id: message.id });
         }
       },
     }),
   ]);
   

   Set resume: true to reconnect to an in-flight assistant response after a page reload.

End-to-end example

JavaScript

import algoliasearch from "algoliasearch/lite";
import instantsearch from "instantsearch.js";
import {
  EXPERIMENTAL_autocomplete,
  chat,
  hits,
  searchBox,
} from "instantsearch.js/es/widgets";

const search = instantsearch({
  indexName: "instant_search",
  searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
});

search.addWidgets([
  searchBox({
    container: "#searchbox",
    aiMode: true,
  }),
  EXPERIMENTAL_autocomplete({
    container: "#autocomplete",
    showPromptSuggestions: { indexName: "prompt_suggestions" },
    indices: [
      {
        indexName: "instant_search",
        templates: {
          item: ({ item }, { html }) => html`<div>${item.name}</div>`,
        },
      },
    ],
  }),
  hits({
    container: "#hits",
    templates: {
      item: (hit, { html }) => html`<article>${hit.name}</article>`,
    },
  }),
  chat({
    container: "#chat",
    agentId: "YOUR_AGENT_ID",
    resume: true,
    context: () => ({
      locale: navigator.language,
      currentPage: window.location.pathname,
    }),
    onFinish: ({ message, isError }) => {
      if (!isError) {
        analytics.track("chat_message_completed", { id: message.id });
      }
    },
  }),
]);

search.start();

Related

• searchBox widget reference
• chat widget reference
• autocomplete widget reference
• Agent Studio