Skip to content

Build

Search Knowledge

Give a task relevant passages from longer documents, with source revisions kept in History.

Add and connect sources

Add text or a UTF-8 TXT/Markdown file in the agent’s Knowledge tab, or manage text through the SDK. Use Knowledge in the Space menu for a shared library, then explicitly connect the documents an agent needs. Shared documents are not automatically given to every agent.

Sources can contain up to 1 MiB of text. Wait for preparation before searching. A replacement keeps the preceding prepared revision in use until the complete new revision is ready. PDF and DOCX imports are not available.

Manage sources from your application

Use the agent from the quickstart
const source = await agent.space.knowledge.add({
  name: 'Returns policy',
  text: 'Unused goods may be returned within 30 days.'
});

await agent.space.knowledge.waitUntilReady(source);
await agent.knowledge.connect(source.id);

const own = await agent.knowledge.add({
  name: 'FAQ', text: 'We ship on weekdays.'
});
const changed = await agent.knowledge.update(own.id, {
  text: 'We ship Monday to Thursday.', ifVersion: own.version
});
await agent.knowledge.delete(own.id, { ifVersion: changed.version });
MethodWhat it manages
agent.knowledge.add/list/get/update/delete/retryDocuments owned by this agent
agent.space.knowledge.add/list/get/update/delete/retryThe shared Space library
agent.knowledge.connections/connect/disconnectWhich Space documents this agent searches
agent.space.knowledge.usage()30-day preparation and search embedding totals

waitUntilReady(source, { timeout: 120000, signal }) waits for the exact version returned by add or update, using metadata reads. Timeout is milliseconds; an optional AbortSignal cancels waiting and the in-flight read.

add and update return id, revision and version. get returns the text and preparation state: preparing, ready or failed. Updates and deletes require ifVersion; version_conflict means another writer changed the source. Read and edit a shared source through agent.space.knowledge, even after connecting it. Scope IDs do not narrow Knowledge ownership or connections.

Choose what to look for

JavaScript
const result = await agent.validate(
  'Every claim must agree with the return policy.',
  'A personalised mug can always be returned.',
  { knowledge: { query: 'Return exceptions for personalised products' } }
);

Search includes the agent’s own documents and its explicitly connected Space sources. conversation does not filter that source set. Selected passages have a separate 6000-character budget, including labels. Search does not replace your existing Context.

Inspect the evidence and usage

result.knowledge describes the actual query, sources, revisions and selected passages. History preserves that selection even after a source is edited, disconnected or deleted. Selected evidence shows what was supplied; it does not guarantee the model interpreted it correctly.

Search embedding usage is separate in result.knowledgeUsage. Preparation and queries go to Mistral’s embedding API; selected passages then go to the agent’s generation model. No extra generative call is used for search.