Integrate Agent Studio

Integrate the Agent Studio with your application to deliver generative AI experiences powered by Algolia and large language models (LLMs).

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

You can interact with your published agents using HTTP API or use the AI SDK UI for a seamless integration.

Steps for integrating Agent Studio

1. Prepare your agent

   Ensure that your agent is configured and published in the Algolia dashboard. To learn more, see Get started with the Agent Studio dashboard.

2. Get your agent ID

   On the Agents page in the Agent Studio’s dashboard, find your published agent’s ID.

3. Choose how you want to integrate Agent Studio

   • HTTP API: directly interact with your agent using HTTP requests.
   • InstantSearch: use the InstantSearch.js or React InstantSearch libraries to integrate search capabilities alongside your agent.
   • AI SDK UI: use the React-based SDK for a ready-to-use conversational UI.

API integration

Interact with your GenAI agent directly using the Agent Studio API.

Example curl request:

Command line

curl "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions?stream=false&compatibilityMode=ai-sdk-5" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "x-algolia-application-id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  --data-raw '{
  "messages": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "What is 1+1 ?"
                }
            ]
        }
    ]
}'

And the response would look like the following:

JSON

{
  "role": "assistant",
  "parts": [
    {
      "type": "step-start"
    },
    {
      "type": "text",
      "text": "1 + 1 = 2"
    }
  ]
}

To continue the conversation, include the previous messages in the request:

JSON

{
    "messages": [
        {
            "role": "user",
            "content": "What is 1+1 ?"
        },
        {
            "role": "assistant",
            "content": "The sum of 1 + 1 is 2."
        },
+        {
+            "role": "user",
+            "content": "What is the sum of the previous value + 3"
+        }
    ]
}

To override Algolia search behavior for a single request, include algolia.searchParameters in the request body. For supported fields and examples, see Algolia Search tool. For the request schema for POST /agent-studio/1/agents/{agentId}/completions, see the Agent Studio API reference.

Enable conversation persistence

To automatically save conversations server-side, include both a conversation ID and message IDs in your request:

Command line

curl "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions?stream=false&compatibilityMode=ai-sdk-5" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "x-algolia-application-id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  --data-raw '{
  "id": "alg_cnv_abc123",
  "messages": [
        {
            "id": "alg_msg_001",
            "role": "user",
            "parts": [
                {
                    "text": "What is 1+1 ?"
                }
            ]
        }
    ]
}'

Both fields are required:

• id: conversation identifier (prefix with alg_cnv_ for consistency)
• messages[].id: unique ID for each message (prefix with alg_msg_)

You can then retrieve the conversation history using the conversations API. For more information, see Conversations.

---

• Replace {{ALGOLIA_APPLICATION_ID}} with your Algolia .
• Replace {{agentId}} with your published agent ID.
• Use your application’s search-only API key for authentication.
• The endpoint supports streaming responses and is compatible with ai-sdk v4 and v5.
• For streaming responses, set stream=true in the query parameters.
• For production, secure your API keys and restrict usage as needed.

InstantSearch integration

Agent Studio is compatible with InstantSearch.js and React InstantSearch. The InstantSearch integration only supports ai-sdk v5.

The benefits of using InstantSearch are:

• Provides an out-of-the-box chat interface with multiple customization options.
• Integrates search results alongside your agent’s responses.
• Handles custom tools with minimal setup.

For more information, see Get started with React InstantSearch and the examples on GitHub.

Examples

React

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, Chat } from 'react-instantsearch';
import 'instantsearch.css/components/chat.css';

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_API_KEY";
const agentId = "AGENT_ID";

const searchClient = algoliasearch(appID, apiKey);
export function App() {
  return (
    <InstantSearch searchClient={searchClient}>
      <Chat
        agentId={agentId}
        itemComponent={({ item }) => (
          <div>
            <h3>{item.title}</h3>
            <p>{item.description}</p>
          </div>
        )}
      />
    </InstantSearch>
  );
}

Rendering search results

If your agent uses a search tool, you must define item templates or components to control how search results appear in the chat interface. Templates are required for search results. They let you display product information, images, or other data in a format that fits your application.

React

<Chat
  // ...otherProps
  itemComponent={({ item }) => (
    <div>
      <h3>{item.title}</h3>
      <p>{item.description}</p>
      <img src={item.image} alt={item.title} />
    </div>
  )}
/>

The itemComponent (React) or templates.item (JavaScript) template renders each search result item with custom HTML and styling. If your agent uses a search tool, you must define this template to display search results correctly in the chat interface.

If your agent uses the Algolia Display Results tool, check the displayResultsEnabled flag in the response’s messageMetadata. When the flag is true, render the curated layout from the Display Results tool output (groups of results with intros and rationales) instead of, or alongside, the per-item template.

Tools

InstantSearch Chat widgets let you integrate tools in your agent’s responses. Once a tool has been added to your agent in the dashboard, you can customize how it’s rendered with InstantSearch.

For a complete guide to configuring tools in Agent Studio, see Tools for Agent Studio.

React

<Chat
  // ...otherProps
  tools={{
    weather: {
      layoutComponent: ({
        message,
        indexUiState,
        setIndexUiState,
        addToolResult,
      }) => <CustomWeatherComponent message={message} />,
      onToolCall: ({ addToolResult, input, ...rest }) =>
        addToolResult({ output: { temperature: 20 } }),
    },
  }}
/>

The tools prop is an object where the keys are the tool names defined in your agent configuration. Each tool includes a layoutComponent (React) or templates.layout (JavaScript) to customize how tool calls appear in the chat interface, and an optional onToolCall handler to run custom logic when the tool is invoked.

For the full list of available props (including applyFilters, sendEvent, onClose, and streamInput), see the Chat widget reference for React or JavaScript.

Hidden context

Use the context prop (React) or context option (JavaScript) on the chat widget to send extra metadata with each user message—for example, the current page, locale, or session segment. The widget serializes the value as JSON and adds it to the user message as a hidden text part of the form <context>{"key":"value"}</context>. Users don’t see it in the chat UI, but the agent does.

context can be a static object or a function that returns an object at send time. Use a function when the context depends on the current state of the page.

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.

React

<Chat
  // ...otherProps
  context={() => ({
    locale: navigator.language,
    currentPage: window.location.pathname,
  })}
/>

For more details, see the Chat widget reference for React or JavaScript.

Prompt suggestions

Prompt Suggestions can be enabled in InstantSearch by enabling the suggestions feature in the Agent Studio dashboard or API.

When enabled, the Chat widgets automatically handle and display suggestions after each agent response. You can customize the suggestions layout using the suggestions component or template.

React

<Chat
  // ...otherProps
  suggestionsComponent={({ suggestions, onSuggestionClick }) => (
    <div>
      <h4>Suggestions:</h4>
      <ul>
        {suggestions.map((suggestion, index) => (
          <li key={index} onClick={() => onSuggestionClick(suggestion)}>
            {suggestion}
          </li>
        ))}
      </ul>
    </div>
  )}
/>

Complete examples

React

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, Chat } from 'react-instantsearch';
import 'instantsearch.css/components/chat.css';

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_API_KEY";
const agentId = "AGENT_ID";

const searchClient = algoliasearch(appID, apiKey);

export function App() {
  return (
    <InstantSearch searchClient={searchClient}>
      <Chat
        agentId={agentId}
        itemComponent={({ item }) => (
          <div>
            <h3>{item.title}</h3>
            <p>{item.description}</p>
          </div>
        )}
        tools={{
          weather: {
            layoutComponent: () => <div>Custom weather component</div>,
            onToolCall: ({ addToolResult }) =>
              addToolResult({ output: { temperature: 20 } }),
          },
        }}
      />
    </InstantSearch>
  );
}

AI SDK UI integration

The Agent Studio is compatible with AI SDK UI, a React-based UI integration for building conversational interfaces. Agent Studio supports both ai-sdk v5 and v4.

AI SDK UI isn’t required to use Agent Studio, but it makes the integration process much easier by handling common tasks like UI rendering and state management. The benefits of using the AI SDK UI are:

• Abstractions over low-level HTTP requests
• Built-in error handling, retries, and extensibility using middleware and plugins
• Fast setup for conversational user interfaces

It also allows for advanced use cases, such as:

• Custom tool handling
• UI state control

For more information, see the AI SDK documentation.

Installation

Command line

npm install ai @ai-sdk/react

Example React integration

React

import { useState } from 'react';
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';

const App = () => {
  const [input, setInput] = useState('');

  const appID = "ALGOLIA_APPLICATION_ID";
  const apiKey = "ALGOLIA_SEARCH_API_KEY";
  const agentId = "AGENT_ID";

  const { messages, sendMessage } = useChat({
    transport: new DefaultChatTransport({
      api: `https://${appID}.algolia.net/agent-studio/1/agents/${agentId}/completions?stream=true&compatibilityMode=ai-sdk-5`,
      headers: {
        'x-algolia-application-id': appID,
        'x-algolia-api-key': apiKey,
      },
    }),
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    sendMessage({ text: input });
    setInput('');
  };

  return (
    <>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === 'user' ? 'User: ' : 'AI: '}
          {message.parts.map((part, index) =>
            part.type === 'text' ? <span key={index}>{part.text}</span> : null,
          )}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={(e) => setInput(e.target.value)} />
        <button type="submit">Submit</button>
      </form>
    </>
  );
};