Skip to main content
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

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();
The chat widget renders the chat panel but doesn’t open it on its own. In this guide, the AI Mode button you add in the next step is the entry point. If you don’t enable AI Mode, add the chatTrigger widget instead, or the chat widget logs a development warning.
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. AI Mode is a valid chat entry point, so you don’t also need a chatTrigger widget.
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.
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();
Last modified on June 2, 2026