Algolia Search tool

Query Algolia indices with natural language, filters, or keywords.

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

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 agent
• Automatic enrichment: index metadata (facets, searchable attributes) is automatically discovered
• Analytics tracking: all agent-performed queries tagged with the alg#agent-studio analytics tag
• Full search API support: supports all query-time Algolia Search parameters. For more information, see Search API parameters
• 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

From the Agent Studio agent edit view 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.

With the API

JSON tool definition:

JSON

{
  "type": "algolia_search_index",
  "name": "product_search",
  "indices": [
    {
      "index": "products",
      "description": "Ecommerce product catalog with electronics, clothing, and home goods"
    }
  ]
}

Required fields

• type: must be "algolia_search_index"
• 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

• name: custom name for this tool instance (defaults to "algolia_search_index")
• Per-index searchParameters: index-specific search parameters

For more information, see the Agent Studio API reference.

Advanced usage

Full search parameters support

The Algolia Search tool supports all query-time parameters from the Algolia Search API. Configure parameters in one of two ways:

Per-index parameters (most common)

JSON

{
  "type": "algolia_search_index",
  "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"],
        "attributesToHighlight": ["title", "description"],
        "hitsPerPage": 20,
        "analytics": true,
        "clickAnalytics": true
      }
    }
  ]
}

Global tool-level parameters

JSON

{
  "type": "algolia_search_index",
  "predefinedSearchParameters": {
    "filters": "status:active",
    "analytics": true
  },
  "indices": [...]
}

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.

You can only override indices that are already configured on the agent’s Algolia Search tool. Requests for other indices are rejected.

This is useful when you want to:

• Apply user-specific filters
• Limit which properties are returned
• Restrict which properties 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,
        "filters": "inStock:true",
        "attributesToRetrieve": ["name", "price", "url"],
        "restrictSearchableAttributes": ["name", "description"],
        "distinct": false
      }
    }
  }
}

Allowed override fields:

Field	Type	Description
filters	string	Filter expression
attributesToRetrieve	string[]	Properties returned in results
restrictSearchableAttributes	string[]	Properties 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 (0 to 100)

For the request schema for POST /agent-studio/1/agents/{agentId}/completions, see the Agent Studio API reference.

If a parameter is already defined in the tool configuration, the tool configuration takes precedence over the query-time override. Query-time overrides are most useful for per-user or per-session values, especially userToken, when these values aren’t already fixed in the tool configuration.

For more information about Algolia personalization, see Personalization.

Example filters for configuration

Always exclude out-of-stock items

JSON

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

Combine multiple filter conditions

JSON

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

Limit retrieved attributes for faster responses

JSON

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

Configure faceting behaviour

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:

1. Go to Algolia 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.

See also

• Tools overview
• Client-side tools
• Credentials
• Search API parameters