Build your first agent

Add an Agent Studio shopping assistant to a product search app.

Before you begin

Make sure you have:

An Algolia account. Create one for free if you don’t already have one.
Node.js 20.19 or later.
React InstantSearch 7.34.0 or later. The Chat and ChatTrigger widgets require this version.
instantsearch.css 8.15.0 or later. Earlier versions don’t include the chat and AI Mode button stylesheets.
An API key from a supported LLM provider. For supported providers, see LLM providers.

Start from the product search app

This quickstart extends the product search quickstart. If you completed the quickstart, open that project and skip to Create your agent. To build the app from scratch instead of downloading it, follow the product search quickstart first, then return here.

Download the product search app

To download the app, run:

npx gitpick algolia/quickstarts/tree/main/product-search-react-typescript agent-studio-quickstart
cd agent-studio-quickstart
npm install

Add your Algolia credentials

In the Algolia dashboard, open the API Keys page and copy these values:

Application ID. Identifies your Algolia application.
Write API key. Used by the indexing script to update records and index settings.
Search API key. Used by the React app to query the index and call Agent Studio from the browser.

Create a .env.local file and add the values to it:

.env.local

VITE_ALGOLIA_APPLICATION_ID=
ALGOLIA_WRITE_API_KEY=
VITE_ALGOLIA_SEARCH_API_KEY=

Keep your Write API key secret. Don’t commit .env.local to version control or expose the write key in your app.

Index the sample products

Run the indexing script to create the quickstart-products index, add sample product records, and configure product_type as a facet.

npm run index:products

You should see Successfully indexed products. in your terminal. In the Algolia dashboard, you can explore the quickstart-products index on the Browse page.

Create your agent

Create an agent that can search the quickstart-products index and answer shopping questions.

Open Agent Studio in the dashboard

In the Algolia dashboard, select your application.
On the left sidebar, select Generative AI > Get started.
Under Agent templates, select Shopping assistant.
On the Shopping assistant page, click Start setup.

Add an LLM provider

On the Connect your agent to an LLM provider page, select an existing provider or create a new one and enter the required credentials. For more information about supported providers and the required credentials, see LLM providers.

The Algolia Sandbox provider lets you test Agent Studio in the dashboard only. You need to use your own provider if you want to follow this quickstart.

Click Next: Data Access.

Connect an index

On the Define your agent’s knowledge page, select the quickstart-products index and click Save. Agent Studio automatically generates a description for the index.Click Next: Prompt.

Set up agent instructions

This quickstart uses the default template for a shopping assistant, with only a few adjustments.On the Guide your agent’s responses page, replace the following placeholders in the template:

Replace {{INSERT_BRAND}} with Algolia
Replace {{INSERT_INDUSTRY}} with fashion
Replace {{INSERT_LANGUAGE}} with English
Feel free to delete the line with the {{INSERT_COMPETITORS_LIST}} placeholder. This quickstart doesn’t need it, but leaving it in shouldn’t cause any issues.

Click Next: Entry Points.

Accept the default entry points, conversation features, and safety controls

On the Configure how users find your agent page, accept the defaults and click Next: Conversation Features.
On the Enhance your agent’s conversations page, accept the defaults and click Next: Safety Controls.
On the Protect your agent’s usage page, accept the defaults and click Complete.
In the confirmation dialog, click Start exploring. This opens the agent’s details page.

Test and publish your agent

On the agent’s details page, you can change all settings, including the agent prompt and safety controls. You can also test your agent with a few queries.When you’re ready to use the agent in your app, click Publish. In the confirmation dialog, click View integration help. Copy your agent ID.

You can also see the agent ID from the agent details view, by clicking on the Integration help icon.

Add chat to the product search app

Add the React InstantSearch chat widgets to the existing product search app.

Optional: upgrade your dependencies

If you just downloaded the code with npx gitpick, you can skip this step.If you completed the product search quickstart a while ago, upgrade the InstantSearch libraries:

npm install react-instantsearch@latest instantsearch.css@latest

The chat widgets require react-instantsearch 7.34.0 or later and instantsearch.css 8.15.0 or later.

Add your agent ID

Add your published agent ID to .env.local:

.env.local

VITE_ALGOLIA_APPLICATION_ID=
ALGOLIA_WRITE_API_KEY=
VITE_ALGOLIA_SEARCH_API_KEY=
VITE_ALGOLIA_AGENT_ID=

Update the app

Replace src/App.tsx with the following code. The highlighted lines show changes to the product search app you prepared earlier.

src/App.tsx

import { liteClient as algoliasearch } from "algoliasearch/lite";
import type { Hit } from "instantsearch.js";
import {
  Chat, 
  ChatTrigger, 
  Configure,
  Highlight,
  Hits,
  InstantSearch,
  Pagination,
  PoweredBy,
  RefinementList,
  SearchBox,
  Snippet,
} from "react-instantsearch";
import "instantsearch.css/themes/reset-min.css";
import "instantsearch.css/components/chat-min.css"; 
import "instantsearch.css/components/ai-mode-button.css"; 
import "./App.css";

const appId = import.meta.env.VITE_ALGOLIA_APPLICATION_ID;
const apiKey = import.meta.env.VITE_ALGOLIA_SEARCH_API_KEY;
const agentId = import.meta.env.VITE_ALGOLIA_AGENT_ID; 

if (!appId) {
  console.error("Missing environment variable: VITE_ALGOLIA_APPLICATION_ID");
}

if (!apiKey) {
  console.error("Missing environment variable: VITE_ALGOLIA_SEARCH_API_KEY");
}

if (!agentId) { 
  console.error("Missing environment variable: VITE_ALGOLIA_AGENT_ID");
}

const searchClient = algoliasearch(appId, apiKey);

type ProductRecord = {
  title: string;
  description: string;
  product_type: string;
  price: number;
  showcase_image: string;
};

type ProductHit = Hit<ProductRecord>;

function SearchProductCard({ hit }: { hit: ProductHit }) { 
  return (
    <article className="product-card">
      <div className="product-card-image">
        <img src={hit.showcase_image} alt={hit.title} />
      </div>
      <div className="product-card-body">
        <p className="product-card-type">{hit.product_type}</p>
        <h2 className="product-card-title">
          <Highlight attribute="title" hit={hit} />
        </h2>
        <p className="product-card-description">
          <Snippet attribute="description" hit={hit} />
        </p>
        <p className="product-card-price">${hit.price}</p>
      </div>
    </article>
  );
}

function ChatProductCard({ item }: { item: ProductHit }) { 
  return (
    <article className="product-card">
      <div className="product-card-image">
        <img src={item.showcase_image} alt={item.title} />
      </div>
      <div className="product-card-body">
        <p className="product-card-type">{item.product_type}</p>
        <h2 className="product-card-title">{item.title}</h2>
        <p className="product-card-description">{item.description}</p>
        <p className="product-card-price">${item.price}</p>
      </div>
    </article>
  );
}

export default function App() {
  return (
    <InstantSearch indexName="quickstart-products" searchClient={searchClient}>
      <Configure hitsPerPage={12} />
      <div className="search-header">
        <SearchBox
          placeholder="Search products"
          aiMode
        />
        <PoweredBy />
      </div>

      <div>
        <Chat<ProductHit>
          agentId={agentId}
          feedback={true}
          itemComponent={ChatProductCard}
        />
      </div>

      <div className="search-body">
        <div className="filter-panel">
          <div className="filter-panel-section">
            <div className="filter-panel-section-title">Product type</div>
            <RefinementList attribute="product_type" sortBy={["count:desc"]} />
          </div>
        </div>

        <div className="search-results">
          <Hits<ProductRecord> hitComponent={SearchProductCard} />
          <Pagination />
        </div>
      </div>

      <ChatTrigger />
    </InstantSearch>
  );
}

Place Chat and ChatTrigger inside the same InstantSearch component as the search widgets.The product search app’s single ProductCard becomes two components, because search results and agent responses provide different props:

SearchProductCard renders search results with highlighting and snippets. Hits passes each record as a hit prop.
ChatProductCard renders products returned by the agent’s Algolia Search tool as plain text. The itemComponent prop of Chat passes each record as an item prop.

Update styles

Replace src/App.css with the following code. The highlighted lines show changes to the product search app you prepared earlier.

src/App.css

*,
*::before,
*::after {
  box-sizing: border-box;
}

:root {
  --color-text: #111827;
  --color-background: #ffffff;
  --color-border: #e5e7eb;
  --color-surface: #ffffff;
  --color-surface-muted: #f3f4f6;
  --color-muted: #6b7280;
  --color-accent: #5468ff;
  --color-accent-strong: #5468ff;
  --color-accent-ring: rgb(84 104 255 / 0.15);
  --color-error: #dc2626;
  --color-error-surface: #fef2f2;
  --color-error-ring: rgb(220 38 38 / 0.12);
}

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  color: var(--color-text);
  background-color: var(--color-background);
}

#root {
  inline-size: min(100%, 70rem);
  margin-inline: auto;
  padding-block: 2rem;
  padding-inline: 1.25rem;
  color: inherit;
}

.search-header {
  display: grid;
  gap: 0.5rem;
  margin-block-end: 1.5rem;
}

.search-body {
  display: grid;
  grid-template-columns: 12.5rem minmax(0, 1fr);
  gap: 2rem;
}

.ais-SearchBox-input,
.ais-Pagination-link {
  border: 1px solid var(--color-border);
  border-radius: 0.5rem;
  background-color: var(--color-surface);
}

.ais-SearchBox-input {
  inline-size: 100%;
  padding-block: 0.75rem;
  padding-inline: 1rem;
  font: inherit;
  font-size: 1rem;
  color: inherit;
  outline: none;
}

.ais-SearchBox-input:focus {
  border-color: var(--color-accent);
  box-shadow: 0 0 0 0.1875rem var(--color-accent-ring);
}

.ais-SearchBox-submit,
.ais-SearchBox-reset {
  display: none;
}

.ais-RefinementList-list,
.ais-Hits-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

.ais-Hits-list {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(12.5rem, 1fr));
  gap: 1rem;
}

.ais-Hits-item {
  display: flex;
}

.ais-Pagination-list {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
  justify-content: center;
  padding-block: 0.75rem;
}

.ais-RefinementList-label {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
}

.ais-PoweredBy,
.ais-RefinementList-count,
.product-card-type {
  font-size: 0.75rem;
  color: var(--color-muted);
}

.ais-PoweredBy {
  display: flex;
  align-items: center;
  min-block-size: 1.5rem;
  line-height: 1;
  justify-self: end;
}

.ais-PoweredBy-link {
  display: flex;
  align-items: center;
}

.ais-PoweredBy-text {
  line-height: 1;
}

.ais-RefinementList-list {
  display: grid;
  gap: 0.5rem;
}

.ais-RefinementList-count {
  margin-inline-start: auto;
}

.ais-RefinementList-checkbox {
  inline-size: 0.875rem;
  block-size: 0.875rem;
  accent-color: var(--color-accent);
}

.ais-RefinementList-item--selected .ais-RefinementList-label {
  font-weight: 500;
}

.ais-Pagination-link {
  display: block;
  padding-block: 0.5rem;
  padding-inline: 0.75rem;
  font-size: 0.875rem;
  color: inherit;
  text-decoration: none;
}

.ais-Pagination-item--selected .ais-Pagination-link {
  color: #fff;
  background: var(--color-accent-strong);
  border-color: var(--color-accent-strong);
}

.ais-Pagination-item--disabled .ais-Pagination-link {
  opacity: 0.4;
  pointer-events: none;
}

.product-card {
  display: flex;
  flex: 1;
  flex-direction: column;
  inline-size: 100%;
  overflow: hidden;
  border: 1px solid var(--color-border);
  border-radius: 0.75rem;
  background-color: var(--color-surface);
}

.product-card-image {
  aspect-ratio: 1;
  overflow: hidden;
  background: var(--color-surface-muted);
}

.product-card-image img {
  inline-size: 100%;
  block-size: 100%;
  object-fit: cover;
}

.product-card-body {
  display: flex;
  flex: 1;
  flex-direction: column;
  gap: 0.25rem;
  padding: 0.75rem;
}

.product-card-type {
  margin: 0;
  text-transform: uppercase;
  letter-spacing: 0.06em;
}

.product-card-title,
.product-card-price,
.filter-panel-section-title {
  margin: 0;
  font-size: 0.875rem;
  font-weight: 500;
}

.product-card-description {
  flex: 1;
  margin: 0;
  overflow: hidden;
  font-size: 0.875rem;
  line-height: 1.5;
  color: var(--color-muted);
  display: -webkit-box;
  -webkit-line-clamp: 3;
  line-clamp: 3;
  -webkit-box-orient: vertical;
}

.filter-panel-section {
  padding-block-end: 0.75rem;
}

.filter-panel-section-title {
  margin-block-end: 0.5rem;
}

@media (max-width: 800px) {
  #root {
    padding-block: 1.5rem;
    padding-inline: 1rem;
  }

  .search-body {
    grid-template-columns: 1fr;
    gap: 1.5rem;
  }
}

/* Agent Studio additions */
.ais-SearchBox-form { 
  position: relative;
}

.ais-SearchBox-input { 
  padding-inline-end: 7rem;
}

.ais-AiModeButton { 
  position: absolute;
  inset-block-start: 50%;
  inset-inline-end: 0.5rem;
  transform: translateY(-50%);
  border-radius: 0.5rem;
  box-shadow: 0 0 0 0.1875rem transparent;
}

.ais-AiModeButton:focus-visible {
  outline: none;
  box-shadow: 0 0 0 0.1875rem var(--color-accent-ring);
}

@media (prefers-reduced-motion: reduce) { 
  .ais-ChatMessages-content--clearing {
    transition: opacity 1ms var(--ais-transition-timing-function) !important;
  }
}

body:has(.ais-ChatToggleButton--floating) .ais-ChatOverlayLayout--maximized { 
  height: calc(100% - var(--ais-chat-margin) * 2 - var(--ais-spacing) * 4);
}

.ais-ChatMessage-message .ais-Carousel-item { 
  display: flex;
}

.ais-Chat { 
  --ais-border-radius-lg: var(--ais-border-radius-sm);
}

Test the chat

Start the development server:

npm run dev

If the server was already running, restart it. Open http://localhost:5173.

The app shows a product grid, a product type filter, and a search box with an AI Mode button. A floating chat button is in the lower corner.Select AI Mode and ask questions, such as Show polka dot pants or What should I wear to a wedding?. The agent returns matching products from the quickstart-products index.

Customize the assistant experience

Add a welcome message and prompt suggestions

Use emptyComponent to show a welcome message before the first chat message. Prompt suggestions help users start a conversation.Add the prompts and welcome component before the App component:

src/App.tsx

const shoppingAssistantPrompts = [
  "Find me a summer wedding outfit",
  "What goes with wide-leg jeans?",
  "Show me floral skirts",
];

function ShoppingAssistantWelcome({
  sendMessage,
  status,
}: {
  sendMessage?: (params: { text: string }) => void;
  status?: string;
}) {
  const disabled = status !== undefined && status !== "ready";

  return (
    <div className="ais-ChatGreeting">
      <h2 className="ais-ChatGreeting-heading">How can I help you shop today?</h2>
      <p className="ais-ChatGreeting-subheading">
        Ask for outfit ideas, product recommendations, sizing help, or style advice.
      </p>
      <div className="ais-ChatPromptSuggestions">
        {shoppingAssistantPrompts.map((prompt) => (
          <button
            className="ais-ChatPromptSuggestions-suggestion"
            disabled={disabled || !sendMessage}
            key={prompt}
            onClick={() => sendMessage?.({ text: prompt })}
            type="button"
          >
            {prompt}
          </button>
        ))}
      </div>
    </div>
  );
}

Pass ShoppingAssistantWelcome to the Chat component:

src/App.tsx

<Chat<ProductHit>
  agentId={agentId}
  emptyComponent={ShoppingAssistantWelcome}
  feedback={true}
  itemComponent={ChatProductCard}
/>

Add styles for the prompt suggestions to src/App.css:

src/App.css

.ais-ChatPromptSuggestions-suggestion {
  background-color: rgba(var(--ais-primary-color-rgb), 0.08);
  border: 1px solid rgba(var(--ais-primary-color-rgb), 0.3);
  color: rgba(var(--ais-primary-color-rgb), 1);
}

@media (hover: hover) {
  .ais-ChatPromptSuggestions-suggestion:hover:not(:disabled) {
    background-color: rgba(var(--ais-primary-color-rgb), 0.15);
    border-color: rgba(var(--ais-primary-color-rgb), 1);
  }
}

.ais-ChatPromptSuggestions-suggestion:active:not(:disabled) {
  background-color: rgba(var(--ais-primary-color-rgb), 0.2);
}

For more information, see Customize the chat welcome screen.

Customize button and chat labels

Use translations to change the AI Mode button label and chat title.

src/App.tsx

<SearchBox
  placeholder="Search products"
  aiMode
  translations={{ aiModeButtonTitle: "Ask assistant" }}
/>

<Chat<ProductHit>
  agentId={agentId}
  feedback={true}
  itemComponent={ChatProductCard}
  translations={{ 
    header: {
      title: "Shopping assistant",
    },
  }}
/>

Adjust token and rate limits

You set cost controls and rate limits during agent creation in the Safety Controls stage. You can adjust them anytime to manage LLM usage. Cost controls limit output tokens, tool or reasoning loops, and conversation length. Rate limits restrict calls to the agent’s /completions endpoint.For more information, see Cost control and Rate limiting.

What’s next

Integrate Agent Studio to learn about API and frontend integrations.
Use tools in Agent Studio to add search, client-side, or Model Context Protocol tools.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Build your first agent

Before you begin

Start from the product search app

Create your agent

Add chat to the product search app

Customize the assistant experience

What’s next

​Before you begin

​Start from the product search app

​Create your agent

​Add chat to the product search app

​Customize the assistant experience

​What’s next

Before you begin

Start from the product search app

Create your agent

Add chat to the product search app

Customize the assistant experience

What’s next