Skip to main content
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: 
curl 'https://{{"YourApplicationID"}}.algolia.net/agent-studio/1/agents/{{agentId}}/completions?stream=false&compatibilityMode=ai-sdk-5' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-algolia-application-id: YourApplicationID' \
  -H 'X-Algolia-API-Key: YourSearchOnlyApiKey' \
  --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"
+        }
    ]
}
  • Replace {{ALGOLIA_APPLICATION_ID}} with your Algolia application ID.
  • 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

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

const searchClient = algoliasearch('APP_ID', 'SEARCH_API_KEY');
export function App() {
  return (
    <InstantSearch searchClient={searchClient}>
      <Chat agentId="AGENT_ID" />
    </InstantSearch>
  );
}

​
Tools

InstantSearch Chat widgets allow easy integration of tools in your agent’s responses. Once a tool has been added to your agent in the dashboard, you can customize how it is rendered with InstantSearch. 
<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 to customize how tool calls appear in the chat interface. The layoutComponent accepts these props:
  • message: A message object with tool call information, including tool input and output. For more information about the message structure, read the AI SDK documentation.
  • indexUiState and setIndexUiState: manage the InstantSearch UI state, useful for updating filters or queries based on tool calls.
  • addToolResult: function to add an output for the tool call. For client-side tools, you must call this at least once before the next message. For more information, see the AI SDK documentation.
You can also provide an optional onToolCall function to execute custom logic when the tool is invoked. It receives the same arguments as the onToolCall function in the useChat hook, plus an additional addToolResult function to provide tool outputs.

​
Complete examples

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

const searchClient = algoliasearch('APP_ID', 'SEARCH_API_KEY');

export function App() {
  return (
    <InstantSearch searchClient={searchClient}>
      <Chat
        agentId="AGENT_ID"
        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

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 { messages, sendMessage } = useChat({
      transport: new DefaultChatTransport({
      api: `https://${"YourApplicationID"}.algolia.net/agent-studio/1/agents/${agentId}/completions?stream=true&compatibilityMode=ai-sdk-5`,
      headers: {
        'x-algolia-application-id': 'YourApplicationID',
        'x-algolia-api-key': 'YourSearchOnlyApiKey',
      },
    }),
  })

  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>
    </>
  )
}