Knowledge
Give an agent documents to answer from, attach them, and check that search finds the right passage.
Knowledge is what your agent reads and cites. You collect documents into a knowledge base, attach it to one or more agents, and the agent answers from it with sources the user can see.
You can fill a knowledge base three ways:
Upload documents
Crawl a website
Push via API
Who can read what is a separate decision, covered in Knowledge access.
Owners, admins and developers can see and manage knowledge. Viewers cannot open knowledge bases.
Create a knowledge base
Open Knowledge in the sidebar and press New knowledge base.
Enter a Name (2 to 80 characters) and an optional Description (up to 280 characters).
Choose the embedding settings: Provider, Key, Model and Dimensions. The embedding model turns text into vectors so search can match meaning. Models are tagged recommended, multilingual or English-first.
Press Create knowledge base.
Choose the model now. The provider, model and dimensions lock once the first source is processed. Changing them later re-embeds every source and uses tokens on your key, and search returns nothing until it finishes.
For Arabic and English together, choose a multilingual model. With an English-first model the page warns: "Arabic questions may not find English documents, and the reverse." If you see "A knowledge base needs a provider key that can create embeddings, and this organization has none yet", add an OpenRouter, OpenAI or Google key under Provider keys. Anthropic does not offer embedding models.
An organization can have up to 50 knowledge bases.
Attach it to an agent
Open the agent and choose Knowledge in its sidebar.
Under Knowledge bases, select the bases the agent can use. An agent can use at most 10.
Under How the agent uses its knowledge, choose a mode:
- When it decides to search: the agent gets a search tool and calls it when a question needs your documents. Cheaper, and it can search several times. This is the default.
- Search on every turn: every message searches first, and the top results are added to the prompt. The answer is always grounded, at the cost of extra latency and tokens on every turn.
Press Save to the draft, then publish. See Preview and publish.
A knowledge base that an agent still uses cannot be deleted. Detach it first.
See the sources in an answer
When the agent uses knowledge, it cites inline, and the chat shows the sources as small chips under the answer. The user sees a title, and a section or page. Whether they can open the original file is your choice per source (see Knowledge access). For documents from a crawled website, the chip opens the live page.
In the session trace, a warning row "Answered without sources." appears when an agent with knowledge replied without a valid citation. It tells you why: no search ran, a search found nothing relevant, or sources were found but not cited.
Test retrieval
On a knowledge base page, Test retrieval runs the same search an agent runs, so you can check the right passage comes back before a user asks.
Type a Question, for example "how long do refunds take?".
Optionally enter a Tenant id, or Search as a reader with these claims, to see what a particular reader would get. Leave both empty to search as a user with no tenant and no claims.
Press Search.
Each result shows the passage, its score, and how it matched: Vector (by meaning), Text (by matching words) or Both. Passages found by both rank highest. If you see "Text search only: the embedding failed", the question could not be embedded and only word matching ran. If you see "Nothing relevant was found", note that sources still processing are not searched.
Press Save as retrieval test to keep a question with the sources a good search should return. Evaluations can run these later. See Evaluations.
Update and delete
- Embedding: Embedding in the knowledge base settings. You can always change the key. Changing the provider, model or dimensions asks you to confirm Change and re-embed.
- Delete a source: its file, chunks and embeddings are removed for good, agents stop finding it at once, and past answers lose its sources. Every deletion is logged with who, what and when, never with names or content, under Deletions and privacy.
- Delete a knowledge base: removes its sources, chunks and original files. This cannot be undone.
- Purge a tenant: Purge tenant removes every source of one tenant from all knowledge bases. Only owners and admins can do it. Knowledge shared by every tenant is not touched.