Skip to main content
At the end of this page, your agent searches the right knowledge base whenever a question needs source material. The Knowledge Retrieval gambit is a tool gambit. You connect it to an AI Agent gambit’s tool handle, and the agent calls it during its reasoning loop whenever it needs source material. One gambit can search several knowledge bases. For how the agent’s loop and tool badges work, see AI Agent gambit.

​
Before you start

Before you start, sign in to the dashboard and select the organization you want to work in.
  • You need a knowledge base with at least one indexed retriever. Without one, the retriever picker shows Index a retriever first. See Configure a retriever.
  • Open the agent’s Make page. See Builder basics for finding your way around.
There are two ways to add the gambit, and both end in the same place. Pick whichever fits how you work.

​
Add it from the palette

1

Open the palette's Tools tab

Knowledge Retrieval sits at the top of the list with a Built-in badge.
2

Drag Knowledge Retrieval onto the builder

The gambit appears where you drop it, reading No Knowledge Bases until you configure it.
3

Drag from its handle to the AI Agent gambit's tool handle

The gambit’s handle sits on its right edge. The agent’s tool handle sits on its left edge.

​
Add it from the agent

1

Select the wrench button beside the AI Agent gambit's tool handle

Its tooltip reads Add tool. A panel opens, headed Add Tools.
2

Select Knowledge Retrieval

Knowledge Retrieval leads the grid, ahead of your toolkits.
Tars creates the gambit and draws the tool connection for you.

​
Choose knowledge bases and retrievers

Select the gambit to open its editor.
1

Pick the knowledge bases under Knowledge Bases

The agent searches every knowledge base you select here.
2

Check each row under Retriever per knowledge base

Every row is bound to one specific retriever. A new row binds to the live default on its own.
3

Pick a different retriever to rebind the row

The Default badge shows only while the bound retriever is also the live default.
Because each row holds one concrete retriever, a later change to the live default does not move this gambit. If the bound retriever stops serving queries, the editor rebinds the row to the live default the next time you open it. The picker lists only retrievers that can serve queries. A retriever marked with an amber warning icon keeps answering from its last index until you reindex it from the knowledge base. See Manage documents for the reindex flow, and Retrievers explained for what the live default is.

​
Name and describe the tool

Two optional fields at the top of the editor tell the agent when to search. A clear description matters most when one agent has several Knowledge Retrieval gambits.

​
Before you publish

Validation checks each connected Knowledge Retrieval gambit against its bound retriever, or the live default when the bound retriever no longer exists. Select Validate in the builder toolbar to see the result before you publish. Each of these is an error. After validation reports one, the publish dialog lists it and blocks publishing until you fix it. A retriever that needs a reindex, or that is reindexing, still passes because it keeps answering.

​
If someone deletes the knowledge base

Knowledge your agents depend on does not disappear silently. The delete dialog names the agents that use the knowledge base, and the member deleting it must confirm that those agents will stop answering from it. A deleted knowledge base stays in Recently deleted for 30 days. See Create a knowledge base for the restore flow.

​
Verify

The AI Agent gambit shows a badge for the connected Knowledge Retrieval gambit. Select Test in the builder toolbar and ask a question your knowledge base answers, as in Test your agent. The reply draws on the imported content. If it does not, run Test retriever from the retriever’s card menu to check what it returns.