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 up to 10 knowledge bases. For how the agent’s loop and tool badges work, see AI Agent gambit. Retrieval gambits with an empty Tool name and an empty Tool description share one knowledge tool on an AI Agent gambit. Their combined selection must also stay within 10 distinct knowledge bases.

​
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 AI Agent gambit, then Manage tools in its editor

Under Tools & Capabilities, open Manage tools. The popover has Connect tools and Add tools tabs.
2

Open Add tools and select Knowledge Retrieval

Find Knowledge Retrieval under Built-in Tools. Tars creates the gambit and connects it to the agent.
If a Knowledge Retrieval gambit already exists on the builder, use Connect tools to link it instead.

​
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, up to 10. Once 10 are selected, the others are disabled.
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 at the top right of the builder 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 the retrieval gambits that share one knowledge tool select more than 10 knowledge bases in total, publishing fails with an error that names the agent. Remove knowledge bases, or give some retrieval gambits their own Tool name.

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