Before you start
Before you start, sign in to the dashboard and select the organization you want to work in.- You need a role that can manage resources to add, edit, or index retrievers.
- You need a knowledge base with at least one processed source. See Create a knowledge base.
Configure and test
1
Open your knowledge base and select the Retriever tab
The tab lists existing retrievers and marks the live default Default.
2
Select Add retriever and pick a preset
Select Add on Vector search for most agents. Select Customize on Custom retriever for advanced options.
3
Select + Index on the new card
A toast confirms Indexing started. Wait for the progress bar to finish.
4
Open the Actions menu and select Test retriever
Enter a question an end user would ask, then select Search.
5
Review the results
Check that the top chunks contain the answer. Try several real questions.
6
Select Make default from the Actions menu
A toast confirms Set as default retriever. The card now shows the Default badge.
The Test retriever dialog
The dialog is titled Test retriever and searches only the retriever you opened it from. Type a question into the Enter a question… field and press Enter or select Search. Results appear below the search field. Each chunk shows its source document title, the rendered content, a rank marker such as #1, and a Score badge. For what the score means, see Retrievers explained. When Media search is on for the knowledge base, the same search also ranks its media. The results then split into a Text tab and a Media tab. The Media tab ranks images, videos, and document links with this retriever’s media settings. It searches every document in the knowledge base, and leaves out hidden media. Each media result shows its source document title, a preview or link, its alt text, a rank marker, and a Score badge. A line above the results tells you when the answering index was built. If the retriever needs a reindex, the line notes that later changes are not in the index yet and offers Reindex. Results clear on their own when the index changes.Verify
Run a test query against the promoted retriever. The results show the chunks your agent receives when it searches this knowledge base. The card carries the Default badge and no status badge.Reference
The Retriever tab
Open a knowledge base and select the Retriever tab. The retriever marked Default answers live for your agent. On plans that include evaluations, a guide strip below the tab bar tracks three steps: Add a retriever, Add test questions, and Run experiments.The Add a retriever picker
Add retriever opens a dialog titled Add a retriever. An info strip recommends starting with Vector Search. Four cards are available:The Build from scratch dialog
The dialog holds a Name field of up to 40 characters, then three sections. An info icon beside most fields explains what it controls. For a new retriever, the Name field fills itself from the Search strategy and the Embedding model, for exampleVector · OpenAI · 3-small. The strategy shows as Vector, Hybrid, or Keyword, and the model drops its (default) suffix.
The name follows those fields until you type your own name, which then stays. If the name is already used on this knowledge base, a suffix such as (2) is added. If you clear the field, the retriever gets the generated name.
Under the Parent-child index, the chunk fields read Child chunk size and Child overlap. An Advanced chunking (parent size/overlap) section then holds Parent chunk size and Parent overlap.
When Refinement is Re-rank top results, the first count field reads Passages to re-rank. A second field, Results to retrieve, sets how many re-ranked passages the agent gets.
Media always uses the embedding model of the text index. The Embedding model field under 3 · Media retrieval shows that model and cannot be changed. When you change the text Embedding model, the retriever’s media moves to the new model with it, and the images are embedded again.
Under 3 · Media retrieval, Settings controls how this retriever searches images and videos:
A retriever that was saved with its own media embedding model keeps it in the same way. It moves to the text embedding model the next time you save a change to the text index or to the media settings. A rename alone does not move it.
Number fields accept whole numbers only. A value out of range shows its allowed range under the field, and Add stays disabled until you fix it.
Embedding models on a free plan
On a free plan, a retriever can index only with OpenAI · 3-small. The other models show in the Embedding model list as disabled, marked (Premium).- Upgrade opens billing.
- Switch to 3-small & reindex moves the retriever to text-embedding-3-small and builds a new index.
The retriever card
Each retriever renders as a card with its name, a summary line, and a footer.
While a build runs, the card shows Indexing or Replacing with a percentage and a progress bar. A failed build shows a red Indexing failed alert with a Details popover and a Retry button. When some images fail to index, a red alert asks you to reprocess them. Use Reprocess all media in Manage media.
When single documents fail to index, an amber alert reads Repairing N documents. They are temporarily unavailable. Details lists each document and its retry attempts. Tars retries on its own, and Retry now schedules another attempt at once. See Manage documents for the reindex flow.
The card Actions menu
The menu on a card offers:
When a change in Edit config requires a rebuild, the footer warns that saving reindexes the retriever. A change to the media settings alone saves without a rebuild, and a toast asks you to reindex to apply it. A retriever with settings the form cannot show can only be renamed there.
The chunk limit
On the Free plan, your organization can store 1,000 chunks across all its knowledge bases. For how chunks count, see The chunk limit. Plans with no chunk limit do not show these screens. The Knowledge bases page shows a Chunk limit button with the chunks used and the limit, such as 640 / 1,000. Select it to open the Chunk limit dialog:
Go to billing opens your plan settings.
The size estimate
When you add a retriever, or save a change that needs a new index, a Chunk limit dialog first estimates the size. It shows the chunks the index will use, a bar of the chunks used and the chunks it adds, and the total. Nothing is written until you index it.- When the new retriever shares an existing index, the dialog reads No extra storage. and names the retrievers it shares with.
- When the estimate fits, select Add retriever or Save to continue.
- When it does not fit, the dialog states how many chunks are left and lists Ways to fit. The ways can be Larger chunks, deleting some documents, or Change search settings only, which reuses the existing index. Select Add retriever anyway or Save anyway to index what fits.
At the limit
When the limit stops a build, the retriever card shows one of these alerts:
The retriever keeps answering from what it already stored. When deleted content waits for a reindex, the alert adds Deleted content frees space once its retriever is reindexed.
When a rebuild with new settings would pass your chunk limit, a Settings change not applied dialog opens instead. The retriever keeps answering with its previous settings. The dialog opens only once for each retriever, and offers Got it, Delete content and Go to billing.
The Apply pending changes dialog shows Chunks freed, Chunks to add, and After reindex, the chunks stored after the reindex of the limit. When the organization is over its limit, a reindex that does not free enough room opens Reindex blocked: you’re over your chunk limit. It shows Stored now, This reindex frees, and Still to free, with Delete content and Go to billing. Your agents keep answering from the existing index.