feat(docs): add Ask AI to Agent Studio migration guide (#2931)

* feat(docs): add Ask AI to Agent Studio migration guide * feat(docs): agentStudio migrating from askAI * feat(docs): renaming agentId * feat(agentStudio): dynamic mode indices updated
2026-08-05 16:37:57 -05:00 · 2026-08-05 16:37:57 -05:00 · e5a5aa1e20
commit e5a5aa1e20
parent fe4d0c29f3
15 changed files with 359 additions and 32 deletions
--- a/.tool-versions
+++ b/.tool-versions
@ -1,2 +1,2 @@
-bun  1.3.10
+bun 1.3.10
 nodejs 24.13.1
--- a/packages/website/docs/agent-studio/feedback.mdx
+++ b/packages/website/docs/agent-studio/feedback.mdx
@ -57,7 +57,7 @@ Override feedback text through `translations.modal.askAiScreen`:
  appId="YOUR_APPLICATION_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['docs']}
-  askAi={{ assistantId: 'YOUR_AGENT_ID' }}
+  askAi={{ agentId: 'YOUR_AGENT_ID' }}
  translations={{
    modal: {
      askAiScreen: {
--- a/packages/website/docs/agent-studio/getting-started.mdx
+++ b/packages/website/docs/agent-studio/getting-started.mdx
@ -10,10 +10,12 @@ DocSearch v5 uses [Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/a

 Don't add an `agentStudio` flag. There's no AI backend selector in v5.

+If you already have an Ask AI assistant, see [Migrate Ask AI to Agent Studio](/docs/agent-studio/migrate-to-agent-studio).
+
 ## Before you begin

 1. [Create and publish an Agent Studio agent](https://www.algolia.com/doc/guides/algolia-ai/agent-studio/how-to/quickstart).
-2. Copy its agent ID. DocSearch calls this value `assistantId` in its public API.
+2. Copy its agent ID. DocSearch calls this value `agentId` in its public API.
 3. Create a Search API key that can search the indices used by DocSearch and Agent Studio. Don't expose an Admin API key.
 4. Note your Algolia application ID and DocSearch index name.

@ -68,7 +70,7 @@ export function Search() {
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['YOUR_DOCSEARCH_INDEX']}
      askAi={{
-        assistantId: 'YOUR_AGENT_ID',
+        agentId: 'YOUR_AGENT_ID',
      }}
    />
  );
@ -131,7 +133,7 @@ docsearch({
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_DOCSEARCH_INDEX'],
  askAi: {
-    assistantId: 'YOUR_AGENT_ID',
+    agentId: 'YOUR_AGENT_ID',
  },
 });
 ```
@ -145,7 +147,7 @@ See the [JavaScript package reference](/docs/packages/js/api-reference) for the

 Use the `askAi` object to add:

- [Dynamic indices and search controls](/docs/agent-studio/dynamic-indices)
+- [Dynamic indices](/docs/agent-studio/dynamic-indices)
 - [Client-side and MCP tools](/docs/agent-studio/tools)
 - [User-scoped memory](/docs/agent-studio/memory)
 - [Suggested prompts and follow-ups](/docs/agent-studio/prompt-suggestions)
@ -153,6 +155,6 @@ Use the `askAi` object to add:

 ## Use the Docusaurus adapter

-The v5 Docusaurus adapter requires `themeConfig.docsearch.askAi` to be an object with `assistantId`. It rejects the string shorthand and the removed `agentStudio` property. Keep `appId`, `apiKey`, and keyword-search `indices` at the top level.
+The v5 Docusaurus adapter requires `themeConfig.docsearch.askAi` to be an object with `agentId`. It rejects the string shorthand and the removed `agentStudio` property. Keep `appId`, `apiKey`, and keyword-search `indices` at the top level.

 See the [Docusaurus adapter guide](/docs/packages/docusaurus-adapter/getting-started) for its full configuration and validation rules.
--- a/packages/website/docs/agent-studio/memory.mdx
+++ b/packages/website/docs/agent-studio/memory.mdx
@ -36,7 +36,7 @@ docsearch({
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['docs'],
  askAi: {
-    assistantId: 'YOUR_AGENT_ID',
+    agentId: 'YOUR_AGENT_ID',
    memory: {
      enabled: true,
      userToken,
--- a/packages/website/docs/agent-studio/migrate-to-agent-studio.mdx
+++ b/packages/website/docs/agent-studio/migrate-to-agent-studio.mdx
@ -0,0 +1,150 @@
+---
+title: Migrate Ask AI to Agent Studio
+description: Move an existing Ask AI assistant into Agent Studio and point DocSearch v5 at the new agent.
+---
+
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+Ask AI is now part of [Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio). Migrate your existing Ask AI assistant, publish the new agent, then point DocSearch at the agent ID.
+
+DocSearch v5 uses Agent Studio as its only AI backend. There's no `agentStudio` flag.
+
+If you're still on DocSearch v4, follow the [v4 migration guide](/docs/v4/v4/migrating-askai-to-agent-studio). To upgrade packages at the same time, see [Migrate from DocSearch v4](/docs/migrating-from-v4).
+
+## Migrate your assistant
+
+### 1. Start the migration in the dashboard
+
+1. Sign in to the [Algolia dashboard](https://dashboard.algolia.com/users/sign_in).
+2. Open [Ask AI](https://dashboard.algolia.com/ask-ai).
+3. Select your assistant and click **Migrate to Agent Studio**.
+
+The wizard creates a draft Agent Studio agent from your assistant configuration, including the prompt, model, indices, and related settings. After migration, the assistant and agent are independent and don't stay in sync.
+
+### 2. Review and publish the agent
+
+1. Open [Agents](https://dashboard.algolia.com/generativeAi/agent-studio/agents) in Agent Studio.
+2. Review the migrated agent.
+3. Publish the agent when you're ready to go live.
+
+Copy the **agent ID**. DocSearch calls this value `agentId` in its public API.
+
+### 3. Update your integration
+
+Choose the path that matches how you embed Ask AI today:
+
+- [DocSearch v5](#update-docsearch-v5)
+- [Custom Ask AI API](#custom-ask-ai-api-integrations)
+
+Your existing Ask AI assistant keeps serving traffic until Ask AI is fully retired. Switch your client to the Agent Studio agent when you're ready.
+
+## Update DocSearch v5
+
+Pass the Agent Studio **agent ID** as `askAi.agentId`, or as the `askAi` string shorthand. Rename any `assistantId` field to `agentId`.
+
+<Tabs groupId="language" aria-label="Programming language">
+  <TabItem value="react" label="React">
+
+Use `DocSearchAI`. Keyword-only `DocSearch` doesn't accept `askAi`.
+
+```tsx title="Search.tsx"
+import { DocSearchAI } from '@docsearch/react';
+import '@docsearch/css';
+
+export function Search() {
+  return (
+    <DocSearchAI
+      appId="YOUR_APPLICATION_ID"
+      apiKey="YOUR_SEARCH_API_KEY"
+      indices={['YOUR_DOCSEARCH_INDEX']}
+      askAi={{
+        agentId: 'YOUR_AGENT_ID',
+      }}
+    />
+  );
+}
+```
+
+The string shorthand remains supported:
+
+```tsx title="Search.tsx"
+<DocSearchAI
+  appId="YOUR_APPLICATION_ID"
+  apiKey="YOUR_SEARCH_API_KEY"
+  indices={['YOUR_DOCSEARCH_INDEX']}
+  askAi="YOUR_AGENT_ID"
+/>
+```
+
+  </TabItem>
+  <TabItem value="js" label="JavaScript">
+
+Keep the root `@docsearch/js` import. It renders the AI-capable component:
+
+```js title="load-docsearch.js"
+import docsearch from '@docsearch/js';
+import '@docsearch/css';
+
+docsearch({
+  container: '#docsearch',
+  appId: 'YOUR_APPLICATION_ID',
+  apiKey: 'YOUR_SEARCH_API_KEY',
+  indices: ['YOUR_DOCSEARCH_INDEX'],
+  askAi: {
+    agentId: 'YOUR_AGENT_ID',
+  },
+});
+```
+
+  </TabItem>
+</Tabs>
+
+### Update `searchParameters`
+
+Agent Studio search parameters are keyed by index name. Move any flat Ask AI `searchParameters` under the index:
+
+```diff title="app.js"
+ askAi: {
+-  assistantId: 'YOUR_ASSISTANT_ID',
+  agentId: 'YOUR_AGENT_ID',
+   searchParameters: {
+-    filters: 'language:en',
+-    attributesToRetrieve: ['title', 'content', 'url'],
+    docs: {
+      filters: 'language:en',
+      attributesToRetrieve: ['title', 'content', 'url'],
+    },
+   },
+ }
+```
+
+Supported keys are `filters`, `attributesToRetrieve`, `restrictSearchableAttributes`, and `distinct`. Don't put `facetFilters` in this object. Put fixed facet conditions in `filters`. For per-request index selection, see [dynamic indices](/docs/agent-studio/dynamic-indices).
+
+### Docusaurus adapter
+
+The adapter requires `themeConfig.docsearch.askAi` as an object with `agentId`. It rejects the string shorthand and the removed `agentStudio` property. See the [Docusaurus adapter guide](/docs/packages/docusaurus-adapter/getting-started).
+
+## Custom Ask AI API integrations
+
+If you call the Ask AI HTTP API yourself instead of using DocSearch, configure your client for Agent Studio instead of `https://askai.algolia.com`.
+
+Don't build new integrations against the Ask AI chat API. Use the Agent Studio APIs:
+
+- [Integrate Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio/how-to/integration)
+- [Agent Studio API](https://www.algolia.com/doc/rest-api/agent-studio)
+- Completions endpoint example:  
+  `https://{APPLICATION_ID}.algolia.net/agent-studio/1/agents/{AGENT_ID}/completions`
+
+Authenticate with your application ID and a search-only API key. Prefer the DocSearch configuration above when you embed DocSearch—the SDK wires the Agent Studio transport for you.
+
+## Next steps
+
+After the agent ID is live in DocSearch:
+
+- [Get started with Agent Studio](/docs/agent-studio/getting-started)
+- [Dynamic indices](/docs/agent-studio/dynamic-indices)
+- [Tools](/docs/agent-studio/tools)
+- [Memory](/docs/agent-studio/memory)
+- [Prompt suggestions](/docs/agent-studio/prompt-suggestions)
+- [Feedback](/docs/agent-studio/feedback)
--- a/packages/website/docs/agent-studio/prompt-suggestions.mdx
+++ b/packages/website/docs/agent-studio/prompt-suggestions.mdx
@ -15,7 +15,7 @@ Enable curated starting questions with `suggestedQuestions`:

 ```js title="docsearch.js"
 askAi: {
-  assistantId: 'YOUR_AGENT_ID',
+  agentId: 'YOUR_AGENT_ID',
  suggestedQuestions: true,
 }
 ```
@ -44,7 +44,7 @@ Create an Algolia index whose records contain a `prompt` string, then configure

 ```js title="docsearch.js"
 askAi: {
-  assistantId: 'YOUR_AGENT_ID',
+  agentId: 'YOUR_AGENT_ID',
  promptSuggestions: {
    indexName: 'docs_prompt_suggestions',
    hitsPerPage: 3,
--- a/packages/website/docs/agent-studio/tools.mdx
+++ b/packages/website/docs/agent-studio/tools.mdx
@ -43,7 +43,7 @@ export function Search() {
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['docs']}
      askAi={{
-        assistantId: 'YOUR_AGENT_ID',
+        agentId: 'YOUR_AGENT_ID',
        tools,
      }}
    />
--- a/packages/website/docs/migrating-from-v4.mdx
+++ b/packages/website/docs/migrating-from-v4.mdx
@ -122,7 +122,7 @@ docsearch({
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: {
-    assistantId: 'YOUR_ASSISTANT_ID',
+    agentId: 'YOUR_AGENT_ID',
  },
 });
 ```
@ -156,25 +156,26 @@ Replace `DocSearch` with `DocSearchAI`:
   appId="YOUR_APP_ID"
   apiKey="YOUR_SEARCH_API_KEY"
   indices={['YOUR_INDEX_NAME']}
-   askAi={{ assistantId: 'YOUR_ASSISTANT_ID' }}
+   askAi={{ agentId: 'YOUR_AGENT_ID' }}
 />
 ```

 `DocSearchAI` requires `askAi`. The string shorthand remains supported:

 ```jsx title="Search.jsx"
-<DocSearchAI askAi="YOUR_ASSISTANT_ID" {...searchProps} />
+<DocSearchAI askAi="YOUR_AGENT_ID" {...searchProps} />
 ```

 ## 3. Move Ask AI to Agent Studio

-V5 removes the legacy Ask AI token and chat transport. Create the assistant in [Agent Studio](/docs/agent-studio/getting-started) before switching production traffic.
+V5 removes the legacy Ask AI token and chat transport. Create the assistant in [Agent Studio](/docs/agent-studio/getting-started) before switching production traffic. If you already have an Ask AI assistant, follow [Migrate Ask AI to Agent Studio](/docs/agent-studio/migrate-to-agent-studio).

-Remove `agentStudio` and `useStagingEnv` from `askAi`. Agent Studio is the only Ask AI backend in v5.
+Rename `assistantId` to `agentId`. Remove `agentStudio` and `useStagingEnv` from `askAi`. Agent Studio is the only Ask AI backend in v5.

 ```diff title="app.js"
 askAi: {
-   assistantId: 'YOUR_ASSISTANT_ID',
+-  assistantId: 'YOUR_ASSISTANT_ID',
+  agentId: 'YOUR_AGENT_ID',
 -  agentStudio: true,
 -  useStagingEnv: false,
 }
@ -184,7 +185,8 @@ The v4 Agent Studio form keyed search parameters by index name. V5 keeps that sh

 ```diff title="app.js"
 askAi: {
-   assistantId: 'YOUR_ASSISTANT_ID',
+-  assistantId: 'YOUR_ASSISTANT_ID',
+  agentId: 'YOUR_AGENT_ID',
   searchParameters: {
 -    filters: 'language:en',
 -    attributesToRetrieve: ['title', 'content', 'url'],
--- a/packages/website/sidebars.js
+++ b/packages/website/sidebars.js
@ -89,6 +89,7 @@ export default {
      label: 'Agent Studio',
      items: [
        'agent-studio/getting-started',
+        'agent-studio/migrate-to-agent-studio',
        'agent-studio/dynamic-indices',
        'agent-studio/tools',
        'agent-studio/memory',
--- a/packages/website/src/components/mdx/ask-ai-deprecation-notice.jsx
+++ b/packages/website/src/components/mdx/ask-ai-deprecation-notice.jsx
@ -0,0 +1,16 @@
+import Admonition from '@theme/Admonition';
+import React from 'react';
+
+export default function AskAIDeprecationNotice() {
+  return (
+    <Admonition type="warning">
+      Ask AI is now part of{' '}
+      <a href="https://www.algolia.com/doc/guides/algolia-ai/agent-studio" target="_blank" rel="noreferrer">
+        Agent Studio
+      </a>{' '}
+      and isn&apos;t available as a standalone feature for new applications. Use these docs for existing Ask AI
+      implementations. To move an existing assistant, see{' '}
+      <a href="/docs/v4/v4/migrating-askai-to-agent-studio">Migrate Ask AI to Agent Studio</a>.
+    </Admonition>
+  );
+}
--- a/packages/website/versioned_docs/version-v4/docsearch.mdx
+++ b/packages/website/versioned_docs/version-v4/docsearch.mdx
@ -235,7 +235,7 @@ docsearch({

 ### Using Agent Studio with DocSearch

-To use [Algolia Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio) as the chat backend, set `agentStudio: true` inside the `askAi` object.
+To use [Algolia Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio) as the chat backend, set `agentStudio: true` inside the `askAi` object and pass your Agent Studio **agent ID** as `assistantId`. Full migration steps (v4, v5, and custom Ask AI API) are in [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio).

 ```js
 docsearch({
--- a/packages/website/versioned_docs/version-v4/v4/askai-api.mdx
+++ b/packages/website/versioned_docs/version-v4/v4/askai-api.mdx
@ -2,25 +2,36 @@
 title: Ask AI API Reference
 ---

-The Ask AI API enables developers to build custom chat interfaces powered by Algolia's AI assistant. Use these endpoints to create tailored conversational experiences that search your Algolia index and generate contextual responses using your own LLM provider.
+import AskAIDeprecationNotice from '@site/src/components/mdx/ask-ai-deprecation-notice.jsx';

-:::info
-This API documentation is primarily for developers building custom Ask AI integrations. If you're using the DocSearch package, you typically won't need this information since DocSearch handles the Ask AI API integration automatically. For standard DocSearch usage, see the [DocSearch documentation](/docs/docsearch) instead.
+<AskAIDeprecationNotice />
+
+:::warning
+New and migrating integrations should use [Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio) instead of the Ask AI API.
+If you call these endpoints today, configure your client to use Agent Studio completions.
+For migration steps, see [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio).
 :::

-## API Documentation
+The Ask AI API lets you build custom chat interfaces powered by an Algolia Ask AI assistant.
+These endpoints search your Algolia index and generate contextual responses with your LLM provider.

-For complete API documentation including endpoints, authentication, request/response formats, and implementation examples, please visit the official Algolia Ask AI API Reference:
+Prefer Agent Studio for new work:
+
+- [Integrate Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio/how-to/integration)
+- [Agent Studio API](https://www.algolia.com/doc/rest-api/agent-studio)
+
+This page is mainly for developers who built custom Ask AI HTTP clients.
+If you use DocSearch, configure Agent Studio in DocSearch instead—
+see [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio).
+
+## Legacy Ask AI API
+
+Legacy Ask AI HTTP docs remain available for reference while you migrate:

 **[Algolia Ask AI API Reference](https://www.algolia.com/doc/guides/algolia-ai/askai/reference/api)**

-The official documentation includes:
+**Base URL:** `https://askai.algolia.com`

- Authentication and token management
- Chat endpoint with streaming responses
- Search parameters and facet filtering
- Feedback submission
- Integration examples with Next.js and Vercel AI SDK
- Error handling and best practices
+That reference covers the older Ask AI token, chat, and feedback endpoints. Prefer Agent Studio for all new work.

-For more information about Ask AI in general, see the [Ask AI documentation](/docs/v4/v4/askai).
+For DocSearch SDK setup (including `agentStudio: true`), see [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio) and [Get started with Ask AI](/docs/v4/v4/askai).
--- a/packages/website/versioned_docs/version-v4/v4/askai.mdx
+++ b/packages/website/versioned_docs/version-v4/v4/askai.mdx
@ -3,11 +3,16 @@ title: Get started with Ask AI
 ---

 import useBaseUrl from '@docusaurus/useBaseUrl';
+import AskAIDeprecationNotice from '@site/src/components/mdx/ask-ai-deprecation-notice.jsx';
+
+<AskAIDeprecationNotice />

 ## Overview

 Ask AI is a conversational AI product that lets you connect your own Large Language Model (LLM) provider (such as OpenAI, Anthropic, Mistral, and more) using your own API keys and model choice. It enables you to use LLMs with the context of your own Algolia index—so your users can ask anything and get answers grounded in your documentation, support articles, or any content you index with Algolia.

+To move an existing Ask AI assistant into Agent Studio, see [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio).
+
 - **Bring Your Own LLM (BYOLLM):** Choose your provider and model, supply your own API keys.
 - **Index-Aware AI:** Ask AI uses your Algolia index as the context for the LLM.
 - **Works with Any Index:** Use with documentation, blogs, support, product data, and more.
--- a/packages/website/versioned_docs/version-v4/v4/migrating-askai-to-agent-studio.mdx
+++ b/packages/website/versioned_docs/version-v4/v4/migrating-askai-to-agent-studio.mdx
@ -0,0 +1,134 @@
+---
+title: Migrate Ask AI to Agent Studio
+---
+
+Ask AI is now part of [Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio),
+where you build and manage AI agents.
+Migrate your existing Ask AI assistant, publish the new agent,
+then point DocSearch or your custom API client to Agent Studio.
+
+## Migrate your assistant
+
+### 1. Start the migration in the dashboard
+
+1. Sign in to the [Algolia dashboard](https://dashboard.algolia.com/users/sign_in).
+2. Open [**Ask AI**](https://dashboard.algolia.com/ask-ai).
+3. Select your assistant and click **Migrate to Agent Studio**.
+
+The wizard creates a draft Agent Studio agent from your assistant configuration,
+including the prompt, model, indices, and related settings.
+After migration, the assistant and agent are independent and don't stay in sync.
+
+### 2. Review and publish the agent
+
+1. Open [**Agents**](https://dashboard.algolia.com/generativeAi/agent-studio/agents) in Agent Studio.
+2. Review the migrated agent.
+3. Publish the agent when you're ready to go live.
+
+Copy the **agent ID**. You use it in DocSearch and in custom API clients.
+
+### 3. Update your integration
+
+Choose the path that matches how you embed Ask AI today:
+
+- [DocSearch v4](#docsearch-v4)
+- [DocSearch v5](#docsearch-v5)
+- [Custom Ask AI API](#custom-ask-ai-api-integrations)
+
+Your existing Ask AI assistant keeps serving traffic until Ask AI is fully retired.
+Switch your client to the Agent Studio agent when you're ready.
+
+## Update DocSearch
+
+### DocSearch v4
+
+Set `agentStudio` to `true` inside the `askAi` object
+and pass your Agent Studio **agent ID** as `assistantId`:
+
+```js
+docsearch({
+  container: '#docsearch',
+  appId: 'YourApplicationID',
+  apiKey: 'YourSearchOnlyAPIKey',
+  indexName: 'YourIndexName',
+  askAi: {
+    assistantId: 'YOUR_AGENT_ID',
+    agentStudio: true,
+  },
+});
+```
+
+```jsx
+<DocSearch
+  appId="YourApplicationID"
+  apiKey="YourSearchOnlyAPIKey"
+  indexName="YourIndexName"
+  askAi={{
+    assistantId: 'YOUR_AGENT_ID',
+    agentStudio: true,
+  }}
+/>
+```
+
+Notes:
+
+- Put `agentStudio` inside `askAi`, not as a top-level DocSearch prop.
+- When `agentStudio` is `true`, DocSearch sends chat requests to Agent Studio for you.
+- When `agentStudio: true`, `searchParameters` must be keyed by index name. See [Using Agent Studio with DocSearch](/docs/v4/docsearch#using-agent-studio-with-docsearch) and [`askAi.agentStudio`](/docs/v4/api#askaiagentstudio).
+
+For the Sidepanel, set `agentStudio={true}` and pass the agent ID as `assistantId`. See the [Sidepanel API reference](/docs/v4/sidepanel/api-reference#agentstudio).
+
+### DocSearch v5
+
+In DocSearch v5, Agent Studio is the only chat backend.
+Pass your Agent Studio **agent ID** as `askAi.agentId`, or as the `askAi` string shorthand.
+Rename `assistantId` to `agentId`. You don't need an `agentStudio` flag:
+
+```js
+docsearch({
+  container: '#docsearch',
+  appId: 'YourApplicationID',
+  apiKey: 'YourSearchOnlyAPIKey',
+  indices: ['YourIndexName'],
+  askAi: {
+    agentId: 'YOUR_AGENT_ID',
+  },
+});
+```
+
+```jsx
+<DocSearchAI
+  appId="YourApplicationID"
+  apiKey="YourSearchOnlyAPIKey"
+  indices={['YourIndexName']}
+  askAi={{ agentId: 'YOUR_AGENT_ID' }}
+/>
+```
+
+For more v5 detail, see the [DocSearch v5 migration guide](/docs/agent-studio/migrate-to-agent-studio).
+
+## Custom Ask AI API integrations
+
+If you call the Ask AI HTTP API yourself instead of using DocSearch,
+configure your client to use **Agent Studio** instead of `https://askai.algolia.com`.
+
+Don't build new integrations against the Ask AI chat API.
+Use the Agent Studio APIs:
+
+- [Integrate Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio/how-to/integration)
+- [Agent Studio API](https://www.algolia.com/doc/rest-api/agent-studio)
+- Completions endpoint example:  
+  `https://{APPLICATION_ID}.algolia.net/agent-studio/1/agents/{AGENT_ID}/completions`
+
+Authenticate with your application ID and a search-only API key.
+For DocSearch users, prefer the SDK configuration above—
+DocSearch wires the Agent Studio transport when `agentStudio` is `true`.
+
+## See also
+
+- [Get started with Ask AI](/docs/v4/v4/askai)
+- [Ask AI API](/docs/v4/v4/askai-api) for existing custom clients
+- [`askAi.agentStudio` API reference](/docs/v4/api#askaiagentstudio)
+- [Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio)
+- [Migrate Ask AI to Agent Studio (DocSearch v5)](/docs/agent-studio/migrate-to-agent-studio)
+- [Get started with Agent Studio (DocSearch v5)](/docs/agent-studio/getting-started)
--- a/packages/website/versioned_sidebars/version-v4-sidebars.json
+++ b/packages/website/versioned_sidebars/version-v4-sidebars.json
@ -20,12 +20,18 @@
      "label": "Algolia Ask AI",
      "items": [
        "v4/askai",
+        "v4/migrating-askai-to-agent-studio",
        "v4/askai-api",
        "v4/askai-prompts",
        "v4/askai-whitelisted-domains",
        "v4/askai-models",
        "v4/askai-markdown-indexing",
        "v4/askai-errors",
+        {
+          "type": "link",
+          "label": "Agent Studio",
+          "href": "https://www.algolia.com/doc/guides/algolia-ai/agent-studio"
+        },
        {
          "type": "link",
          "label": "Full Documentation",