Build an AI-powered search experience

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> root with an Algolia search client.
react-instantsearch installed at a version that ships AI Mode (for example, the release from PR algolia/instantsearch#6982 or later).

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.

React

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { Chat, InstantSearch } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <Chat agentId="YOUR_AGENT_ID" />
    </InstantSearch>
  );
}

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.

React

import { Chat, InstantSearch, SearchBox } from "react-instantsearch";

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SearchBox aiMode />
      <Chat agentId="YOUR_AGENT_ID" />
    </InstantSearch>
  );
}

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.

React

<EXPERIMENTAL_Autocomplete
  showPromptSuggestions={{
    indexName: "prompt_suggestions",
  }}
  indices={[
    {
      indexName: "instant_search",
      templates: {
        item: ({ item }) => <div>{item.name}</div>,
      },
    },
  ]}
/>

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

Pass session metadata with hidden context

Use the context prop 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
  agentId="YOUR_AGENT_ID"
  context={{ locale: "en", segment: "logged-in" }}
/>

Handle the streaming lifecycle

Listen for response completion with onFinish, and use the useChat hook to expose Stop and resume controls. See Streaming and resumption on the Chat widget reference for the full status surface.

React

import { Chat, useChat } from "react-instantsearch";

function StopButton({ agentId }) {
  const { status, stop } = useChat({ agentId });

  if (status !== "streaming") {
    return null;
  }

  return <button onClick={() => stop()}>Stop</button>;
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SearchBox aiMode />
      <Chat
        agentId="YOUR_AGENT_ID"
        resume
        onFinish={({ message, isError }) => {
          if (!isError) {
            analytics.track("chat_message_completed", { id: message.id });
          }
        }}
      />
      <StopButton agentId="YOUR_AGENT_ID" />
    </InstantSearch>
  );
}

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

End-to-end example

React

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import {
  Chat,
  EXPERIMENTAL_Autocomplete,
  Hits,
  InstantSearch,
  SearchBox,
  useChat,
} from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");
const agentId = "YOUR_AGENT_ID";

function StopButton() {
  const { status, stop } = useChat({ agentId });
  if (status !== "streaming") return null;
  return <button onClick={() => stop()}>Stop</button>;
}

function Hit({ hit }) {
  return <article>{hit.name}</article>;
}

export default function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SearchBox aiMode />
      <EXPERIMENTAL_Autocomplete
        showPromptSuggestions={{ indexName: "prompt_suggestions" }}
        indices={[
          {
            indexName: "instant_search",
            templates: { item: ({ item }) => <div>{item.name}</div> },
          },
        ]}
      />
      <Hits hitComponent={Hit} />
      <Chat
        agentId={agentId}
        resume
        context={() => ({
          locale: navigator.language,
          currentPage: window.location.pathname,
        })}
        onFinish={({ message, isError }) => {
          if (!isError) {
            analytics.track("chat_message_completed", { id: message.id });
          }
        }}
      />
      <StopButton />
    </InstantSearch>
  );
}

Documentation Index

​Prerequisites

​End-to-end example

​Related

Prerequisites

End-to-end example

Related