> ## 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.

# Search prefetch

> Answer faster: search your index first, before the model runs.

Search prefetch searches your index with the latest user message, before the model runs.
When the hits answer the question, the model replies right away, without searching itself.
That's often faster.
It's off by default: turn it on for each agent.

<Warning>
  Search prefetch is experimental and may change.
  [Share your feedback](https://www.algolia.com/support/).
</Warning>

## When to use search prefetch

Search prefetch helps when the user's message works as a search query.

| Good fit | Poor fit |
| - | - |
| Catalog: "waterproof hiking boots for kids" | Small talk: "great, that helps a lot". The search adds cost and delay. |
| Support: "return policy for sale items" | Constraints: "boots under \$50, size 3". The model often searches again, and the answer comes later. |
| Docs: "reset a forgotten password" | Tight budgets: each prefetch counts as a search request and adds input tokens. |

## How search prefetch works

With search prefetch, the model gets the hits in its first call:

```mermaid theme={"system"}
sequenceDiagram
    participant User
    participant Agent as Agent Studio
    participant LLM as Model
    participant Algolia as Algolia Search

    Note over User,Algolia: Without search prefetch
    User->>Agent: "Waterproof hiking boots for kids"
    Agent->>LLM: Message and tools
    LLM->>Agent: Call Algolia Search tool
    Agent->>Algolia: Search with the model's query
    Algolia->>Agent: Hits
    Agent->>LLM: Hits
    LLM->>Agent: Answer
    Agent->>User: Answer

    Note over User,Algolia: With search prefetch
    User->>Agent: "Waterproof hiking boots for kids"
    Agent->>Algolia: Search with the user's message
    Algolia->>Agent: Hits
    Agent->>LLM: Message, hits, and tools
    LLM->>Agent: Answer
    Agent->>User: Answer
```

* No hits, an error, or a timeout: the model runs as usual.
* Hits that don't fit: the model can still search.

<Accordion title="Streaming and saved conversations">
  The response stream opens right away.
  Only the first model call waits for the search, up to `timeoutMs`.

  Like the model's own searches, the hits stay in later model calls and in the saved conversation.
</Accordion>

## Turn on search prefetch

Set `searchPrefetch` in your agent's `config` object with the [Agent Studio API](/doc/rest-api/agent-studio):

```json JSON icon=braces theme={"system"}
{
  "config": {
    "searchPrefetch": true
  }
}
```

To turn it off, set `searchPrefetch` to `false`.

<Accordion title="Tune search prefetch">
  To change the defaults, set an object instead of `true`, such as `{"enabled": true, "hitsPerPage": 3}`.

  | Property | Range | Default | Description |
  | - | - | - | - |
  | `enabled` | `true`, `false` | `true` | `false` turns search prefetch off and keeps your settings. |
  | `indexName` | The tool's indices | The first one | Index to search when the Algolia Search tool covers several. |
  | `conversationWindow` | 1 to 5 | `1` | Latest user messages joined into the query. |
  | `minInformativeTokens` | 0 to 10 | `2` | Search words a message needs to trigger a search, not counting common words such as "the". |
  | `hitsPerPage` | 1 to 100 | The tool's value | Hits for the prefetched search. |
  | `timeoutMs` | 0 to 5000 | `1000` | Search budget in milliseconds. `0` turns search prefetch off. |
  | `searchParameters` | See below | `{}` | Search parameters for the prefetched search only. |

  Filters and retrieved attributes come from the [Algolia Search tool](/doc/guides/algolia-ai/agent-studio/how-to/tools/algolia-search).
</Accordion>

<Accordion title="Search parameters and index languages">
  `searchParameters` accepts only [`removeWordsIfNoResults`](/doc/api-reference/api-parameters/removeWordsIfNoResults), [`queryLanguages`](/doc/api-reference/api-parameters/queryLanguages), [`removeStopWords`](/doc/api-reference/api-parameters/removeStopWords), [`ignorePlurals`](/doc/api-reference/api-parameters/ignorePlurals), [`typoTolerance`](/doc/api-reference/api-parameters/typoTolerance), [`restrictSearchableAttributes`](/doc/api-reference/api-parameters/restrictSearchableAttributes), and [`naturalLanguages`](/doc/api-reference/api-parameters/naturalLanguages).
  `removeWordsIfNoResults` defaults to `allOptional`.
  Your values override the Algolia Search tool's.

  To set language defaults, Agent Studio reads the index's languages when you save the agent.
  Save it with an API key that has the `settings` ACL.

  On Chinese, Japanese, or Korean indices, set [`indexLanguages`](/doc/api-reference/api-parameters/indexLanguages),
  or the search finds fewer relevant hits.

  Test `restrictSearchableAttributes` on your index first, and set `indexName` with it.
  It helps only when the listed attributes carry the words people use in chat.
</Accordion>

## Track search prefetch in the stream

With streaming and `compatibilityMode=ai-sdk-5`,
the stream carries a `data-search_prefetch` part for each user message that search prefetch reads.

`agentSearchedAnyway` says whether the model searched again.
The less often it's `true`, the better.

To hide the prefetched search's tool call in your UI, skip the tool parts whose `toolCallId` matches the one in `data-search_prefetch`.

<Accordion title="Stream part properties">
  | Property | Description |
  | - | - |
  | `decision` | `injected_candidate` when the model got the hits, otherwise `skipped_too_few_tokens`, `skipped_no_user_turn`, `skipped_no_index`, `skipped_no_hits`, or `error`. |
  | `nbHits` | Number of hits. |
  | `latencyMs` | Search duration in milliseconds. |
  | `toolName`, `index` | Search tool and index used. |
  | `toolCallId` | ID of the prefetched search call, starting with `prefetch_`, when the model got the hits. |
  | `agentSearchedAnyway` | Whether the model searched again, sent at the end in a part with the same `id`. |
  | `gateSignals` | Ranking details of the top hit, for information only. |
  | `missingIndexLanguages` | `true` when a Chinese, Japanese, or Korean index doesn't set `indexLanguages`. |

  AI SDK 4 streams and non-streaming responses include the prefetched search call, but not this part.
</Accordion>

## Limits

* Works only with the Algolia Search tool through the Algolia MCP Server.
* Runs only on new user messages, not on client-side tool results or tool approvals.
* Searches before input [guardrails](/doc/guides/algolia-ai/agent-studio/how-to/guardrails) decide, so blocked messages still reach your index.
* Recognizes common words in English, French, German, and Spanish only.
  In other languages, every word of two or more characters counts toward `minInformativeTokens`.

## See also

* [Experimental features](/doc/guides/algolia-ai/agent-studio/how-to/experimental-features)
* [Agent configuration](/doc/guides/algolia-ai/agent-studio/how-to/agent-configuration)
* [Integrate Agent Studio](/doc/guides/algolia-ai/agent-studio/how-to/integration)