Search prefetch

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.

Search prefetch is experimental and may change. Share your feedback.

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:

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

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.

Turn on search prefetch

Set searchPrefetch in your agent’s config object with the Agent Studio API:

JSON

{
  "config": {
    "searchPrefetch": true
  }
}

To turn it off, set searchPrefetch to false.

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.

Search parameters and index languages

searchParameters accepts only removeWordsIfNoResults, queryLanguages, removeStopWords, ignorePlurals, typoTolerance, restrictSearchableAttributes, and 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, 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.

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.

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.

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

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Search prefetch

When to use search prefetch

How search prefetch works

Turn on search prefetch

Track search prefetch in the stream

Limits

See also

​When to use search prefetch

​How search prefetch works

​Turn on search prefetch

​Track search prefetch in the stream

​Limits

​See also

When to use search prefetch

How search prefetch works

Turn on search prefetch

Track search prefetch in the stream

Limits

See also