Algolia Search tool

Your agent can search across up to 10 indices in parallel or sequentially to answer questions with real-time data from your product catalog, content library, or any indexed data.

Key capabilities

Natural language queries (when Algolia NeuralSearch is enabled): users ask questions in plain language, agent performs the search
Keyword search: agent performs traditional keyword-based searches
Faceted filtering: agent applies filters with AND/OR logic based on user requests
Multiple indices: agent can query up to 10 indices per request, chosen either in the configuration or per request. For more information, see Control which indices the agent can search
Automatic enrichment: index metadata (facets, searchable attributes) is automatically discovered
Analytics tracking: all agent-performed queries tagged with the alg#agent-studio analytics tag
Search API parameters: supports a curated subset of query-time Algolia Search parameters. For more information, see Search parameters
Suggested refinements: agent can suggest follow-up search refinements based on facet values, using a deterministic (facet-count heuristic) or agentic (LLM-driven) strategy
Configurable AI behavior: control what the AI can change at query time, such as bounds on results per page, which attributes to retrieve, or a fixed set of facets
User-restricted access: works with secure API keys for record-level access control
Simplest integration: no external APIs required, uses existing Algolia Search configuration

Use a Search API key (never an Admin API key). For more information, see Algolia Search tool security.

Configure the Search tool

From the dashboard
With the API

From the Agent Studio agent edit view in the Algolia dashboard:

Click Add tool > Algolia Search
Select your (for example, products)
Add a description: “Product catalog with titles, descriptions, prices, and availability”
Click Add tool

Use the Other tools option when you need to configure tools with settings not supported by the Algolia dashboard, or when a dedicated interface isn’t available.

JSON tool definition:

JSON

{
  "type": "algolia_search_index",
  "name": "product_search",
  "indices": [
    {
      "index": "products",
      "description": "Ecommerce product catalog with electronics, clothing, and home goods",
      "searchParameters": {
        "filters": "inStock:true"
      },
      "searchControls": {
        "hitsPerPage": { "exposed": true, "default": 7, "constraint": { "min": 1, "max": 10 } },
        "attributesToRetrieve": { "exposed": true, "default": ["title", "price"], "constraint": { "values": ["title", "price", "brand"] } },
        "facets": { "exposed": false, "default": ["brand", "category"] }
      }
    }
  ]
}

Required fields

type: must be "algolia_search_index"
name: identifier for this tool instance.
indices: array of index configurations (minimum 1, maximum 10)
- index: Algolia index name
- description: describe what data is in the index, not how to use it. The tool automatically provides usage instructions to the LLM.

Optional fields

mode: "static" (default) or "dynamic". Controls whether a completion request can replace the index list. See Control which indices the agent can search
allowUnlistedIndices: false (default). Under mode: "dynamic", accepts per-request index names absent from indices. Setting it to true under mode: "static" is a validation error.

Per-index searchParameters: Algolia Search API parameters applied to a specific index.

JSON

{
  "type": "algolia_search_index",
  "name": "product_search",
  "indices": [
    {
      "index": "products",
      "description": "Ecommerce product catalog with electronics, clothing, and home goods",
      "searchParameters": {
        "filters": "isPublished:true AND inStock:true",
        "attributesToRetrieve": ["title", "price", "image", "brand"],
        "hitsPerPage": 20,
        "analytics": true,
        "clickAnalytics": true
      }
    }
  ]
}

Per-index settings (searchControls): structured settings controlling how the AI uses the index, and the dashboard’s AI Search Settings. See Control what the AI can change per index. Each field accepts:

exposed (boolean): whether the AI can change the value at query time
default: the default value
constraint (optional): {min, max} for numeric fields, {values} for array fields

JSON

{
  "searchControls": {
    "hitsPerPage": { "exposed": true, "default": 7, "constraint": { "min": 1, "max": 10 } },
    "page": { "exposed": true, "default": 0, "constraint": { "min": 0, "max": 10 } },
    "attributesToRetrieve": { "exposed": true, "default": ["title", "price"], "constraint": { "values": ["title", "price", "brand"] } },
    "responseFields": { "exposed": false, "default": null },
    "facets": { "exposed": false, "default": ["brand", "category"] },
    "custom": null
  }
}

For more information, see the Agent Studio API reference.

Advanced usage

Search parameters

Set Algolia Search API parameters per index with searchParameters. The tool accepts only a subset of the query-time parameters. The tool doesn’t expose attributesToHighlight, highlightPreTag, or highlightPostTag. responseFields should be set in searchControls.

JSON

{
  "type": "algolia_search_index",
  "name": "product_search",
  "indices": [
    {
      "index": "products",
      "description": "Ecommerce product catalog with electronics, clothing, and home goods",
      "searchParameters": {
        "filters": "isPublished:true AND inStock:true",
        "attributesToRetrieve": ["title", "price", "image", "brand"],
        "hitsPerPage": 20,
        "analytics": true,
        "clickAnalytics": true
      }
    }
  ]
}

To apply the same parameter across indices, repeat it in each indices[] entry. Agent Studio forwards searchParameters to the search tool so values outrank the agent’s own choices and the searchControls defaults below. For anything the agent should be able to vary, use searchControls instead.

Control what the AI can change per index

searchControls sets, for each index, which search parameters the agent can change at query time, what value applies when it doesn’t, and the bounds it must stay within. It accepts query, hitsPerPage, page, attributesToRetrieve, responseFields, distinct, facets, and custom. Every field defaults to exposed: false, so the agent can’t change any of them until you allow it.

From the dashboard
With the API

Click AI Search Settings on an index entry in the Agent Studio agent edit view.

Parameter	Notes
Faceting
`facets`	Facets the AI can use to filter results. Default: all available facets.
Pagination
`hitsPerPage`	Enable Allow AI to override to let the AI choose a value within configurable min/max bounds. Default: `7`.
`page`	Enable Allow AI to override to let the AI paginate through results. Default: `0`.
Retrieved Attributes
`attributesToRetrieve`	Enable Allow AI to override to let the AI choose from a restricted list of allowed attributes. Default: all attributes.
`responseFields`	Add extra response fields on top of the default set. Default: `hits`, `nbHits`, `page`, `nbPages`, `hitsPerPage`, `facets`.
Custom Search Parameters
`custom`	Pass any other Algolia Search API parameters in JSON format.

Use searchControls in the index configuration. Each field accepts:

exposed (boolean): whether the AI can change the value at query time
default: the default value
constraint (optional): {min, max} for numeric fields, {values} for array fields

JSON

{
  "searchControls": {
    "hitsPerPage": { "exposed": true, "default": 7, "constraint": { "min": 1, "max": 10 } },
    "page": { "exposed": true, "default": 0, "constraint": { "min": 0, "max": 10 } },
    "attributesToRetrieve": { "exposed": true, "default": ["title", "price"], "constraint": { "values": ["title", "price", "brand"] } },
    "responseFields": { "exposed": false, "default": null },
    "facets": { "exposed": false, "default": ["brand", "category"] },
    "custom": null
  }
}

Query-time search parameter overrides

You can override specific search parameters per request by passing algolia.searchParameters in the completions API request body. Use this when some values vary by user or session, without changing the tool configuration. The tool honors only the indices it is already configured to search. For how it resolves that set, see Control which indices the agent can search. This is useful when you want to:

Apply user-specific filters
Return fewer attributes
Restrict which attributes are searchable for a specific request
Change distinct dynamically
Pass personalization settings such as userToken

Pass overrides as an object with the index name as key:

JSON

{
  "messages": [
    {
      "role": "user",
      "content": "Show me something I might like"
    }
  ],
  "algolia": {
    "searchParameters": {
      "products": {
        "userToken": "user-123",
        "enablePersonalization": true,
        "personalizationImpact": 75,
        "attributesToRetrieve": ["name", "price", "url"],
        "restrictSearchableAttributes": ["name", "description"],
        "distinct": false
      }
    }
  }
}

These eight fields are the only ones the API accepts. A request carrying any other field gets a validation error.

Field	Type	Description
`filters`	`string`	Filter expression
`optionalFilters`	`string` or `array`	Filters that boost or bury matching records instead of removing them
`attributesToRetrieve`	`string[]`	Attributes returned in results
`restrictSearchableAttributes`	`string[]`	Attributes searched in this request
`distinct`	`boolean` or `integer`	Deduplicate results
`userToken`	`string`	User token for personalization and analytics
`enablePersonalization`	`boolean`	Enable Algolia personalization
`personalizationImpact`	`integer`	Weight of personalization in ranking, from 0 to 100

For the request schema for POST /agent-studio/1/agents/{agentId}/completions, see the Agent Studio API reference. Whether an override reaches Algolia depends on what else sets the same parameter. For the full resolution order, see Search parameter precedence.

Search parameter precedence

Several sources can set the same search parameter. From lowest to highest priority:

The search tool’s own defaults
The default value in searchControls
The value the agent chooses for this call, for any field you set to exposed: true
Per-index searchParameters, which Agent Studio forwards into custom
Query-time algolia.searchParameters for this index, also forwarded into custom
searchControls.custom
The index name, which the tool reapplies last

The custom field values override the agent’s choices, and they skip the bounds in constraint.

Control which indices the agent can search

The tool’s mode decides whether a completions request can change the index list.

Static mode (default)

The configured indices is the only set the tool can search. A request that sends algolia.indices anyway gets a 422 with the code static_tool_rejects_per_request_indices. Setting allowUnlistedIndices: true under static mode is a validation error.

Dynamic mode

Use dynamic mode when your application, rather than the agent configuration, decides which indices a request should search:

Multi-region catalogs: a shopper browsing the US site asks about availability in Germany, so that turn searches products_eu instead of products_us
Multi-tenant data: each customer owns a separate index, and the request names the index for the signed-in tenant
More indices than one tool holds: a configuration takes at most 10 indices, so route across a larger set one request at a time

A request can send algolia.indices, a list of up to 10 index names, which replaces indices for that request only. Omit algolia.indices and the configured indices apply as usual. Send the list under algolia at the top level of the completions request body:

JSON

{
  "messages": [
    {
      "role": "user",
      "content": "Is the linen shirt available in Germany?"
    }
  ],
  "algolia": {
    "indices": ["products_eu"]
  }
}

Each entry is a bare index name. Descriptions and per-index search parameters stay in the tool configuration, and Agent Studio looks them up for every listed name the request sends. The field takes at most 10 entries and rejects duplicates. It also rejects an empty array, so omit algolia.indices instead of sending []. With allowUnlistedIndices left at false, the request’s list must be a subset of the configured indices. A name you haven’t configured gets a 422 with the code index_not_listed_on_tool.

JSON

{
  "type": "algolia_search_index",
  "name": "product_search",
  "mode": "dynamic",
  "allowUnlistedIndices": false,
  "indices": [
    { "index": "products_us", "description": "US product catalog" },
    { "index": "products_eu", "description": "EU product catalog" }
  ]
}

With allowUnlistedIndices: true, the configured indices can also be empty, so every index arrives per request. Such a tool doesn’t have any fallback: a request that omits algolia.indices leaves the agent with nothing to search. On the search tool’s index configuration, two toggles control this:

Toggle	Description
Dynamic mode	Allow completion requests to override which indices this tool searches with `algolia.indices`. Without an override, the tool falls back to the configured indices.
Allow unlisted indices	Accept any index reachable by the agent’s API key, not only the indices listed above. Unlisted names get a minimal description.

Setting both mode: "dynamic" and allowUnlistedIndices: true accepts any index name a request asks for, including indices you never configured. The Algolia API key’s own ACL becomes the only limit on what the agent can read.Unconfigured names get a minimal description and none of your per-index parameters, so a filters you rely on doesn’t apply to them.Scope the key with restrictIndices before turning this on. Agent Studio matches the resolved index list against the key’s restrictions before it runs any search and rejects the request when a name falls outside them. A key with no index restrictions passes every name, so the agent reads whatever that key can reach. For more information, see Algolia Search tool security.

Example filters for configuration

Always exclude out-of-stock items
Combine multiple filter conditions
Limit retrieved attributes for faster responses
Configure faceting behavior

JSON

{
  "searchParameters": {
    "filters": "inStock:true"
  }
}

JSON

{
  "searchParameters": {
    "filters": "isPublished:true AND (category:electronics OR category:computers)"
  }
}

JSON

{
  "searchParameters": {
    "attributesToRetrieve": ["objectID", "title", "price", "image"]
  }
}

JSON

{
  "searchParameters": {
    "facets": ["brand", "category", "price_range"],
    "maxValuesPerFacet": 10
  }
}

Analytics tracking

All queries made by the Algolia Search tool are automatically tagged with:

alg#agent-studio

You can:

Track agent-generated queries separately in your Algolia analytics
Identify popular search patterns from conversational interactions
Optimize your index based on agent usage

Find the agent analytics data in the Algolia dashboard:

Go to Algolia Analytics
Filter by tag: alg#agent-studio
Review top queries, click-through rates, and conversion metrics

For more information about user-restricted access with secured API keys, see Security and credentials.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Algolia Search tool

Configure the Search tool

Advanced usage

Search parameters

Control what the AI can change per index

Query-time search parameter overrides

Search parameter precedence

Control which indices the agent can search

Static mode (default)

Dynamic mode

Example filters for configuration

Analytics tracking

See also

​Configure the Search tool

​Advanced usage

​Search parameters

​Control what the AI can change per index

​Query-time search parameter overrides

​Search parameter precedence

​Control which indices the agent can search

​Static mode (default)

​Dynamic mode

​Example filters for configuration

​Analytics tracking

​See also

Configure the Search tool

Advanced usage

Search parameters

Control what the AI can change per index

Query-time search parameter overrides

Search parameter precedence

Control which indices the agent can search

Static mode (default)

Dynamic mode

Example filters for configuration

Analytics tracking

See also