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
source = agent.space.knowledge.add(
name="Returns policy",
text="Unused goods may be returned within 30 days.",
)
agent.space.knowledge.wait_until_ready(source)
agent.knowledge.connect(source["id"])
own = agent.knowledge.add(name="FAQ", text="We ship on weekdays.")
changed = agent.knowledge.update(
own["id"], text="We ship Monday to Thursday.",
if_version=own["version"],
)
agent.knowledge.delete(own["id"], if_version=changed["version"])| Method | What it manages |
|---|---|
| agent.knowledge.add/list/get/update/delete/retry | Documents owned by this agent |
| agent.space.knowledge.add/list/get/update/delete/retry | The shared Space library |
| agent.knowledge.connections/connect/disconnect | Which Space documents this agent searches |
| agent.space.knowledge.usage() | 30-day preparation and search embedding totals |
wait_until_ready(source, timeout=120) waits for the exact version returned by add or update, using metadata reads. Timeout is seconds. On an async client, await it; cancelling the task cancels waiting and the in-flight read.
add and update return dictionaries containing id, revision and version. get returns the text and preparation state: preparing, ready or failed. Updates and deletes require if_version; 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. All network methods are awaited on an async agent.
Request a search on the operation
result = agent.extract(
"Within how many days can unused goods be returned?",
{"days": "number"},
knowledge=True,
)
if not result.success:
raise RuntimeError(result.error)
print(result.data)
print(result.knowledge)Use the agent inside the client context. All four operations accept this option. With knowledge=True, the query comes from the task input. Omitted or False means no search.
Choose what to look for
result = 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.knowledge_usage. 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.