> ## Documentation Index > Fetch the complete documentation index at: https://www.algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Algolia Search tool > Query Algolia indices with natural language, filters, or keywords. export const Index = () => index ; 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. Screenshot of a 'Configure Algolia Search' dialog with an 'Add index' field, a 'Description' text box, and a 'Save' button. * **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](#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](#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](/doc/guides/security/api-keys/how-to/user-restricted-access-to-data) 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](/doc/guides/algolia-ai/agent-studio/how-to/tools/security#algolia-search). ## Configure the Search tool From the [Agent Studio agent edit view](https://dashboard.algolia.com/generativeAi/agent-studio/agents) in the Algolia dashboard: 1. Click **Add tool** > **Algolia Search** 2. Select your (for example, `products`) 3. Add a description: "Product catalog with titles, descriptions, prices, and availability" 4. 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 JSON icon=braces theme={"system"} { "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](#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](/doc/api-reference/search-api-parameters) applied to a specific index. ```json JSON icon=braces theme={"system"} { "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](#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 JSON icon=braces theme={"system"} { "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](/doc/rest-api/agent-studio). ## Advanced usage ### Search parameters Set [Algolia Search API parameters](/doc/api-reference/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`](/doc/guides/algolia-ai/agent-studio/how-to/tools/algolia-search#control-what-the-ai-can-change-per-index). ```json JSON icon=braces theme={"system"} { "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. Click **AI Search Settings** on an index entry in the [Agent Studio agent edit view](https://dashboard.algolia.com/generativeAi/agent-studio/agents). | 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](/doc/api-reference/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 JSON icon=braces theme={"system"} { "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's already configured to search. For how it resolves that set, see [Control which indices the agent can search](#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 JSON icon=braces theme={"system"} { "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](/doc/rest-api/agent-studio/create-agent-completion). 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). ### Search parameter precedence Several sources can set the same search parameter. From lowest to highest priority: 1. The search tool's own defaults 2. The `default` value in `searchControls` 3. The value the agent chooses for this call, for any field you set to `exposed: true` 4. Per-index `searchParameters`, which Agent Studio forwards into `custom` 5. Query-time `algolia.searchParameters` for this index, also forwarded into `custom` 6. `searchControls.custom` 7. 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 JSON icon=braces theme={"system"} { "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 JSON icon=braces theme={"system"} { "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](/doc/guides/algolia-ai/agent-studio/how-to/tools/security#algolia-search). ### Example filters for configuration ```json JSON icon=braces theme={"system"} { "searchParameters": { "filters": "inStock:true" } } ``` ```json JSON icon=braces theme={"system"} { "searchParameters": { "filters": "isPublished:true AND (category:electronics OR category:computers)" } } ``` ```json JSON icon=braces theme={"system"} { "searchParameters": { "attributesToRetrieve": ["objectID", "title", "price", "image"] } } ``` ```json JSON icon=braces theme={"system"} { "searchParameters": { "facets": ["brand", "category", "price_range"], "maxValuesPerFacet": 10 } } ``` ### Analytics tracking All queries made by the Algolia Search tool are automatically tagged with: ```txt theme={"system"} 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: 1. Go to [Algolia Analytics](https://dashboard.algolia.com/analytics) 2. Filter by tag: `alg#agent-studio` 3. Review top queries, click-through rates, and conversion metrics For more information about user-restricted access with secured API keys, see [Security and credentials](/doc/guides/algolia-ai/agent-studio/how-to/tools/security#user-restricted-access-with-secured-api-keys). ## See also * [Tools overview](/doc/guides/algolia-ai/agent-studio/how-to/tools/overview) * [Client-side tools](/doc/guides/algolia-ai/agent-studio/how-to/tools/client-side-tools) * [Credentials](/doc/guides/algolia-ai/agent-studio/how-to/tools/security) * [Search API parameters](/doc/api-reference/search-api-parameters)