feat(agent studio): add prompt suggestions widget by shaejaz · Pull Request #7054 · algolia/instantsearch

shaejaz · 2026-05-22T15:00:55Z

Adds a PromptSuggestions widget that renders AI-generated prompt "pills" for the page, powered by the Agent Studio /tasks endpoint. Clicking a pill hands the prompt off to the Chat widget on the same index.

Highlights

New connector connectPromptSuggestions (instantsearch.js, $$type: 'ais.promptSuggestions') — owns all search-aware logic: fetch on mount, 300ms debounced refetch on query/refinement change, manual refresh(), transformItems/transformHits, and chat hand-off.
New generic connectTasks connector — the reusable core underneath. connectPromptSuggestions is now a thin search-aware layer on top of it, so any future task-backed feature can reuse the same request/streaming/output plumbing. Connector-only (no default UI), generic over TOutput, $$type: 'ais.tasks'; params are agentId XOR transport, task, and stream.
New lib/tasks/ runtime — the generic Agent Studio tasks-endpoint counterpart to lib/chat/ (completions). Endpoint/credential/payload primitives (resolveEndpoint, buildTaskPayload, fetchTask with optional streaming, createTaskRunner, and Task* types); nothing widget-specific.
Context, decided at init by the presence of context:
- Default (no context): auto-extracts { query, filters, hitsSample } from the current search state and refreshes as results change. transformHits shapes the sample (default: first 5 hits, internal _-prefixed metadata stripped).
- Explicit context (object or per-fetch function): sent as-is; hit auto-extraction is skipped.
Shared UI in instantsearch-ui-components (createPromptSuggestionsComponent): .ais-PromptSuggestions pills + skeleton loading state, disabled while the chat is busy. Overridable via layoutComponent (React) / templates.layout (JS) and onSuggestionClick.
Auth: pass agentId (uses the InstantSearch client's app id / key) or a custom transport (api / headers). configurationId selects the Agent Studio task (sent as the task field, default 'prompt_suggestions').
Tests: full connector unit suites for connectPromptSuggestions and connectTasks, lib/tasks unit tests, and cross-flavor common tests (common-widgets -t "PromptSuggestions widget common tests"); Vue registered as skipped.

React API

Default (page-driven):

import { PromptSuggestions } from 'react-instantsearch';

<PromptSuggestions agentId="YOUR_AGENT_ID" />

Explicit context (e.g. a product page):

<PromptSuggestions
  agentId="YOUR_AGENT_ID"
  context={{
    productName: product.name,
    category: product.category,
    price: product.price,
  }}
/>

codacy-production · 2026-05-22T15:03:41Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 437 complexity

Metric Results

Complexity 437

View in Codacy

_{TIP This summary will be updated as you push new changes.}

Copilot

Pull request overview

This PR introduces a new ChatPageSuggestions widget (prompt “pills” driven by Agent Studio tasks) across InstantSearch.js and React InstantSearch, and extends the SSR pipeline to await and hydrate chat-related async state so suggestions/messages can be embedded in server HTML and reused on hydration.

Changes:

Add connectChatPageSuggestions + JS/React widget wrappers and common-widget tests (Vue explicitly unsupported).
Add SSR “server-wait promises” + initialChatStates serialization/hydration (Next.js + core SSR utilities).
Update shared ChatPromptSuggestions UI component and CSS to support loading skeletons/disabled state.

Reviewed changes

Copilot reviewed 45 out of 46 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/common/widgets/index.ts	Exports the new common widget test suite.
tests/common/widgets/chat-page-suggestions/templates.tsx	Common template/layout override tests for the widget.
tests/common/widgets/chat-page-suggestions/options.ts	Common behavioral/option tests (loading, transform, click, transport, context).
tests/common/widgets/chat-page-suggestions/index.ts	Registers the flavored common tests for the widget.
packages/vue-instantsearch/src/tests/common-widgets.test.js	Marks the widget unsupported in Vue common tests.
packages/react-instantsearch/src/widgets/index.ts	Exposes `ChatPageSuggestions` from React widgets entrypoint.
packages/react-instantsearch/src/widgets/ChatPageSuggestions.tsx	Implements the React widget wrapper around `useChatPageSuggestions` + UI component.
packages/react-instantsearch/src/widgets/tests/all-widgets.test.tsx	Adds widget metadata coverage to the “all widgets” snapshot list.
packages/react-instantsearch/src/widgets/tests/utils/all-widgets.tsx	Excludes `ChatPageSuggestions` from generic render assertions (renders `null` initially).
packages/react-instantsearch/src/tests/common-widgets.test.tsx	Wires the React widget into cross-flavor common widget tests.
packages/react-instantsearch-nextjs/src/InstantSearchNext.tsx	Adds `initialChatStates` support to SSR context hydration.
packages/react-instantsearch-nextjs/src/InitializePromise.ts	Awaits widget-registered SSR promises and injects serialized `chatStates`.
packages/react-instantsearch-nextjs/src/createInsertHTML.tsx	Injects serialized initial chat state into HTML for hydration.
packages/react-instantsearch-core/src/server/getServerState.tsx	Exposes `initialChatStates` from server state when present.
packages/react-instantsearch-core/src/lib/useInstantSearchApi.ts	Hydrates `_initialChatStates` onto the InstantSearch instance client-side.
packages/react-instantsearch-core/src/index.ts	Exports the new `useChatPageSuggestions` hook.
packages/react-instantsearch-core/src/connectors/useChatPageSuggestions.ts	Adds hook wrapper for `connectChatPageSuggestions`.
packages/react-instantsearch-core/src/components/InstantSearchSSRProvider.tsx	Extends SSR provider contract to include `initialChatStates`.
packages/instantsearch.js/test/createInstantSearch.ts	Updates InstantSearch test mock to include SSR wait/chat state fields.
packages/instantsearch.js/src/widgets/index.ts	Exposes `chatPageSuggestions` widget from JS widgets entrypoint.
packages/instantsearch.js/src/widgets/chat-page-suggestions/chat-page-suggestions.tsx	Implements the InstantSearch.js widget wrapper (Preact renderer + templates).
packages/instantsearch.js/src/widgets/tests/index.test.ts	Ensures the widget is creatable via the widgets index.
packages/instantsearch.js/src/lib/tasks/types.ts	Adds types for the Agent Studio tasks transport/credentials.
packages/instantsearch.js/src/lib/tasks/resolveEndpoint.ts	Resolves task endpoint + headers from either transport or credentials.
packages/instantsearch.js/src/lib/tasks/index.ts	Exports tasks helpers/types.
packages/instantsearch.js/src/lib/tasks/buildTaskPayload.ts	Builds `{ task, input }` payload envelope.
packages/instantsearch.js/src/lib/tasks/buildEndpoint.ts	Constructs default Agent Studio tasks endpoint URL.
packages/instantsearch.js/src/lib/server.ts	SSR now waits for widget-registered promises before resolving.
packages/instantsearch.js/src/lib/InstantSearch.ts	Adds `_initialChatStates` + server-wait promise registry APIs.
packages/instantsearch.js/src/lib/chat/sendMessageWithContext.ts	Extracts send-with-context wrapper into reusable helper.
packages/instantsearch.js/src/lib/chat/openChat.ts	Extends chat referer values for new page widgets.
packages/instantsearch.js/src/lib/chat/createAgentTransport.ts	Introduces shared agent transport builder for chat connector.
packages/instantsearch.js/src/lib/chat/chat.ts	Makes chat persistence safer in SSR/non-storage environments and adds `persist` option.
packages/instantsearch.js/src/connectors/index.ts	Exports `connectChatPageSuggestions`.
packages/instantsearch.js/src/connectors/chat/connectChat.ts	Refactors transport creation + context injection to shared helpers.
packages/instantsearch.js/src/connectors/chat-page-suggestions/connectChatPageSuggestions.ts	New connector implementing debounced fetch + SSR snapshot/hydration + chat handoff.
packages/instantsearch.js/src/connectors/chat-page-suggestions/tests/connectChatPageSuggestions-test.ts	Unit tests for connector lifecycle, payloads, handoff, SSR behavior.
packages/instantsearch.js/src/tests/common-widgets.test.tsx	Wires JS widget into cross-flavor common widget tests.
packages/instantsearch.css/src/components/chat/_chat-suggestions.scss	Adds skeleton styling for prompt suggestions.
packages/instantsearch-ui-components/src/components/chat/ChatPromptSuggestions.tsx	Adds loading skeleton + disabled support to shared UI component.
examples/react/next-app-router/app/Search.tsx	Demonstrates the widget usage in Next App Router example.
examples/react/next-app-router/app/page.tsx	Computes absolute base URL for SSR-side fetches in example.
examples/react/next-app-router/app/api/chat-page-suggestions/route.ts	Adds a mock endpoint for page suggestions example.
examples/react/getting-started/vite.config.mjs	Adds a Vite dev-server mock endpoint for page suggestions.
examples/react/getting-started/src/App.tsx	Demonstrates the widget usage in the “getting-started” React example.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The example wiring isn't needed for now; reverts examples/ back to master. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pkg-pr-new · 2026-07-09T10:40:38Z

More templates

algoliasearch-helper

npm i https://pkg.pr.new/algolia/instantsearch/algoliasearch-helper@7054

instantsearch-ui-components

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch-ui-components@7054

instantsearch.css

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch.css@7054

instantsearch.js

npm i https://pkg.pr.new/algolia/instantsearch/instantsearch.js@7054

react-instantsearch

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch@7054

react-instantsearch-core

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-core@7054

react-instantsearch-nextjs

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-nextjs@7054

react-instantsearch-router-nextjs

npm i https://pkg.pr.new/algolia/instantsearch/react-instantsearch-router-nextjs@7054

vue-instantsearch

npm i https://pkg.pr.new/algolia/instantsearch/vue-instantsearch@7054

commit: 8bd3025

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 4 comments.

# Conflicts: # packages/instantsearch.js/src/lib/server.ts # packages/react-instantsearch-nextjs/src/InitializePromise.ts # packages/react-instantsearch-nextjs/src/__tests__/InitializePromise.test.tsx

The SSR guard for `sessionStorage` in the Chat state is moved to its own PR (fix/chat-ssr-sessionstorage-guard) since it touches internal lib/chat files and reviews more clearly on its own. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Haroenv · 2026-07-17T15:16:01Z

+const DEFAULT_TRANSFORM_HITS: PromptSuggestionsTransformHits = (hits) =>
+  hits.slice(0, 5).map(stripInternalHitMetadata);
+
+function buildFilters(results: SearchResults): string[][] | undefined {


have we tested if this logic is worth it? wonder if it's better to send the whole search results without transforming the parameters and doing any transform later backend?

I believe the evaluations stated that the results are sent as hits plus the query/filters/categories.
So replicated that here without sending everything.

Haroenv · 2026-07-20T10:02:08Z

+  | 'prompt-suggestions'
+  | 'ai-mode'
+  | 'prompt-suggestions';


twice the same one? one of the two should be the autocomplete prompt suggestions, the other should be the standalone one. We should be able to distinguish

I've gone with prompt-suggestions for the widget and prompt-suggestions-autocomplete for autocomplete as it makes a bit more sense to me.

This does cause the previous prompt-suggestions associated with autocomplete to be mixed going forward. Only if we are saving this information currently. Wdyt?

Haroenv

couple questions about edge cases

Haroenv · 2026-07-22T08:50:42Z

+  return suggestions.filter(
+    (s: unknown): s is string => typeof s === 'string' && s.trim().length > 0
+  );
+}


why would there be an empty suggestion?

Haroenv · 2026-07-22T08:58:49Z

+      const tasksWidget = connectTasks(
+        handleInnerRender,
+        noop
+      )({
+        ...(transport ? { transport } : { agentId }),
+        task: configurationId ?? 'prompt-suggestions',
+        stream: true,
+      } as TasksConnectorParams);


so we create a widget, but don't explicitly render it, this seems fragile. What about returning both widgets in an array and using render state to access its items? otherwise it seems like it could cause issues later (maybe we don't call the tasks widget in all the hooks for example)

that was how it was done initially, but i thought since the task connector is more an internal structure, maybe we don't want our renderstate to have this information.

Haroenv · 2026-07-22T08:59:13Z

+        noop
+      )({
+        ...(transport ? { transport } : { agentId }),
+        task: configurationId ?? 'prompt-suggestions',


I don't think we need a fallback

unless the "first created prompt suggestion" always has that id, cc @FabienMotte, it would be possible.

so basically have configurationId be a required prop?

anjola-adeuyi · 2026-07-22T09:39:52Z

+        const entries = Object.entries(pageContext)
+          .map(([key, value]): [string, string] => [
+            key,
+            typeof value === 'string' ? value : JSON.stringify(value),


should the chat context be shaped separately here? a valid task input can put hitsSample over chat’s 1 KB per-value limit, so clicking a rendered suggestion can fail with 422

yes this is already the case. this should be rechecked once the 10kb limit is merged on the backend.

thanks, that helps. if this PR depends on the 10 KB backend rollout, what keeps the default five-hit hitsSample within that limit?

anjola-adeuyi · 2026-07-22T10:00:49Z

+      ? (prompt: string) => onSuggestionClickOverride(prompt, { sendToChat })
+      : onSuggestionClick;
+
+    if (templates?.layout) {


should layout and header use prepareTemplateProps and TemplateComponent like other JS widgets? layout(data, { html }) currently receives only data, so the documented template throws

anjola-adeuyi · 2026-07-22T10:01:53Z

+
+        const chatRenderState = getChatRenderState(renderOptions);
+
+        const isChatBusy = chatRenderState


should chat status transitions schedule a full InstantSearch render? after chat moves from submitted to ready, the shared render state can stay at submitted, leaving these pills disabled

i believe this already happens, yes. will double check

anjola-adeuyi · 2026-07-22T10:02:34Z

+        renderOptions: RenderOptions
+      ) => {
+        if (disposed || !tasksState) return;
+        refetchPending = false;


should this invalidate the active task before returning? when search state A changes to a no-hits state B, A can still resolve and render stale pills into B

it won't render since there's now a check for this var there.

not sure about the invalidate active task, having cancellation support for that request seems a bit more complicated, perhaps in a separate PR?

refetchPending is set to false before this return, so the guard in handleInnerRender still accepts A’s late result. could we invalidate A here without cancelling the request?

anjola-adeuyi · 2026-07-22T10:03:32Z

+    processStream(
+      chunkStream,
+      (chunk) => {
+        if (!chunk || chunk.type !== 'data-task-output') {


should this reject when the stream emits an error event? the backend can send partial output before a terminal error but [DONE] currently resolves the last partial as success

yeah we don't really have error states for the pills atm.

I can add that check here, but not sure how to display that to a user. For now a blank state should be okay i think

a blank state is fine, no error UI is needed. could the error event reject the task and the prompt connector clear any streamed partial so a failed stream can’t leave partial pills visible?

shaejaz added 4 commits May 21, 2026 15:15

init

38a296a

fix types

8d1e0b4

Merge branch 'master' into feat/chat-page-suggestions-widget

fd8f9dd

fix duplicate requests

599683b

shaejaz added 11 commits May 26, 2026 11:16

rename current page suggestions

b867e28

add suggestions pills component

aee97fd

standalone suggestions

01349ec

fix ssr

b33b848

remove ChatPageSummary widget (split to feat/chat-page-summary-widget)

6881fd8

Merge branch 'master' into feat/chat-page-suggestions-widget

5479d0f

fix tests

fe120b1

update api

a9a6004

Merge branch 'master' into feat/chat-page-suggestions-widget

2e0f439

update endpoint, remove standalone naming

3b48a55

add tests

71db731

shaejaz changed the title ~~wip: on page suggestions widget~~ feat(chat): add on page suggestions widget Jul 9, 2026

shaejaz requested a review from Copilot July 9, 2026 09:31

Copilot started reviewing on behalf of shaejaz July 9, 2026 09:31 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

shaejaz and others added 5 commits July 9, 2026 11:05

Merge branch 'master' into feat/chat-page-suggestions-widget

2fd7918

chore(examples): revert example changes for chat-page-suggestions

922aa54

The example wiring isn't needed for now; reverts examples/ back to master. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

add task name test

953baf4

address comments

aae135c

fix bundlesize

5970f2b

shaejaz requested a review from Copilot July 9, 2026 10:39

Copilot started reviewing on behalf of shaejaz July 9, 2026 10:42 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

fix nextjs and loading states

9f59a30

shaejaz requested a review from Haroenv July 15, 2026 09:23

Haroenv reviewed Jul 15, 2026

View reviewed changes

shaejaz and others added 5 commits July 16, 2026 16:56

Merge branch 'master' into feat/chat-page-suggestions-widget

1b0b390

# Conflicts: # packages/instantsearch.js/src/lib/server.ts # packages/react-instantsearch-nextjs/src/InitializePromise.ts # packages/react-instantsearch-nextjs/src/__tests__/InitializePromise.test.tsx

address comments

f360a6f

Merge branch 'master' into feat/chat-page-suggestions-widget

bd11185

remove next and ssr changes

88fdcc1

shaejaz requested a review from Haroenv July 17, 2026 11:35

rename to prompt suggestions

99ae0b5

Haroenv changed the title ~~feat(chat): add on page suggestions widget~~ feat(agent studio): add prompt suggestions widget Jul 17, 2026

Haroenv requested changes Jul 17, 2026

View reviewed changes

shaejaz added 4 commits July 17, 2026 17:23

add back chat prompt suggestions

87c12b1

move back chat transport

9ee79ae

rename connector

c52f220

update bundlesize

ff78870

shaejaz requested a review from Haroenv July 20, 2026 09:35

Haroenv reviewed Jul 20, 2026

View reviewed changes

address comments

5781b1d

shaejaz requested a review from Haroenv July 20, 2026 11:39

Haroenv reviewed Jul 20, 2026

View reviewed changes

Comment thread packages/instantsearch.js/src/lib/chat/openChat.ts Outdated

update refer name

3244084

shaejaz requested a review from Haroenv July 20, 2026 13:34

anjola-adeuyi reviewed Jul 20, 2026

View reviewed changes

shaejaz added 4 commits July 21, 2026 11:46

use queryid

f624a9e

address comments

8633901

update default task name

0aa15eb

update turn context

8bd3025

shaejaz requested a review from anjola-adeuyi July 21, 2026 14:48

Haroenv reviewed Jul 22, 2026

View reviewed changes

anjola-adeuyi reviewed Jul 22, 2026

View reviewed changes


		const chatRenderState = getChatRenderState(renderOptions);

		const isChatBusy = chatRenderState

Uh oh!

Conversation

shaejaz commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Highlights

React API

Uh oh!

codacy-production Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Haroenv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

shaejaz commented May 22, 2026 •

edited

Loading

codacy-production Bot commented May 22, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 9, 2026 •

edited

Loading