How agents use knowledge
Loading a knowledge base does not make an agent use it. Two things have to be true: the agent has to have it selected, and the content has to reach the model. These are separate mechanisms, and most reports of "the agent ignored my knowledge" come down to one of them rather than to the model.
Two paths into the prompt
The type of a knowledge base decides how its content travels:
| Type | How the model sees it |
|---|---|
form, singlePage | Inlined. Every record is written into the system prompt, on every request. |
files | Retrieved. Only the passages most similar to the current message are pulled in. |
Inline knowledge is always considered and takes up room in the prompt on every message. Retrieved knowledge scales to a document library but is present only when the question resembles it.
That asymmetry drives the design decision. A twelve-line refund policy that must never be missed belongs inline. Three hundred PDFs cannot go inline, because there is not room, so they go in a files base and are retrieved.
A files-type base contributes its name and description only, as a pointer telling the
model that a library exists and what is in it; the passages themselves arrive separately,
per message. This is why ds_description matters: it is the model's only guide to when a
knowledge base is worth drawing on.
GET /agents/{id}/preview-system-prompt shows what a specific agent resolved, without
running anything. Check it first when an agent behaves oddly: if a knowledge base is not in
the output, the problem is selection rather than the model.
How selection resolves
Two fields, and they are not alternatives: one is a default and the other an override.
| Field | Contains | Set by |
|---|---|---|
agent_ds | Knowledge base names, kebab-case | The agent's own definition |
agent_tenant_ds | Knowledge base ids | Your workspace, layered on top |
Code
When agent_tenant_ds is set, it takes precedence outright and agent_ds is not
consulted. Send null to drop the override and fall back to the agent's own set.
An empty array is not the same as null. agent_tenant_ds: [] means "this workspace
selects no knowledge", and the agent runs with none at all. null means "use the agent's
default." Sending [] when you meant to clear the override is the most common way to
silently strip an agent of everything it knew.
Why names are matched loosely
agent_ds holds names in kebab-case, but ds_name accepts only letters, numbers and
spaces. They meet in the middle: each agent_ds entry is lowercased and its hyphens
become spaces, then matched against the lowercased ds_name.
Code
The naming rule on knowledge bases exists to keep this mapping unambiguous. If an agent's
knowledge silently does not appear, check this first: a base named Product Catalog 2026
cannot be referenced as product-catalog, and a rename breaks the link with no error
anywhere.
Selecting by id through agent_tenant_ds avoids the issue entirely, and is what an
integration should prefer.
Only active knowledge bases resolve. Deactivating one silently removes it from every agent that referenced it.
How retrieval works
For files-type knowledge, each message triggers a similarity search, and the passages that come back are added to the model's context for that message, marked as retrieved reference material rather than as part of the conversation.
Documents are split into overlapping chunks, on paragraph breaks where possible and on smaller boundaries when a paragraph runs long. The overlap exists so that a fact straddling a chunk boundary survives whole in at least one chunk. That is why chunks are not a clean paragraph split.
The mechanics are fixed rather than configurable per request. A small number of passages is retrieved per message, and passages that are not similar enough are dropped rather than included to fill the quota.
That budget is the constraint to design against. A question whose answer is spread across forty pages will not be answered well by retrieval, which is a sign the knowledge should be restructured into a knowledge template, where it is all present at once.
Retrieval fails soft. If the similarity search errors, the conversation continues without knowledge rather than returning an error. The agent still answers, but from the model alone. An answer that looks as though the knowledge base does not exist is consistent with retrieval having failed, not only with nothing matching.
Attach knowledge to one message
Knowledge selection is agent-level, but a single message can point at specific files. A
reference part in msg_content names a file to retrieve against for that message only:
Code
A reference is retrieved against, while a file part attaches the document whole. Use a
reference for something long, and a file for something the model should read end to end.
Threads carry this too: thread_ref scopes retrieval for a whole conversation, and spaces
contribute their own knowledge to every thread inside them.
Why an agent ignores your knowledge
Work down this list, which is roughly ordered by how often each is the cause.
| Check | |
|---|---|
| Is it selected? | GET /agents/{id}/preview-system-prompt. Not in the output means not selected. |
Is agent_tenant_ds an empty array? | That means "no knowledge", not "default". |
| Do the names match? | agent_ds kebab-case must map onto ds_name exactly once hyphens become spaces. |
| Is the knowledge base active? | Inactive bases resolve to nothing. |
For files: is the file ready? | Text extraction and embedding happen after finalize. Documents mid-processing are invisible to retrieval. |
| For files: is anything close enough? | Below 0.2 similarity nothing is returned. Phrasing that shares no vocabulary with the document retrieves nothing. |
| Is the description specific? | The model decides relevance from ds_description, and "Misc data" gives it nothing to work with. |
The first check needs agent:edit. For a platform-published agent it returns only the parts
your own workspace contributed, with the base prompt withheld. The knowledge section is one
of those parts, so it still answers this question.
Knowledge outside chat
Two uses of knowledge bases have nothing to do with agents answering questions:
- Analysis vocabulary. The Media Tags and Flags knowledge bases are the closed vocabulary image analysis may use. Editing them changes how every future upload is described.
- Brand identity. A base with
ds_category: "brand-identity"feeds design and brand tooling rather than only chat.
A knowledge base is closer to shared organizational data than to a chatbot feature, which is why it is its own resource rather than part of the agent.
Next steps
- Knowledge bases covers creating and filling the three kinds.
- Agents and conversations covers the agent that consumes it.
- AI enrichment covers vocabulary-driven image analysis.