Agents

How knowledge works

Knowledge sources belong to the workspace, each agent picks the ones it may use, and retrieval pulls matching passages into the turn.

Knowledge is the material your agent can quote from: files you upload, text you paste, and web pages you point it at. Sources belong to the workspace, not to a single agent. Each agent picks which of them it is allowed to use, and retrieval decides, turn by turn, which passages are worth putting in front of the model.

One library, many agents

Every source you add lands in the workspace library. You open it from Knowledge base in the left navigation. A source is always one of two kinds:

Kind What it is
file An uploaded document. Pasted text is stored this way too, as a Markdown file.
web A single page or a crawled site.

Sources can sit loose at the root of the library, or inside a folder. A folder is a named group inside the workspace; it has a name and nothing else.

Because the library is workspace-wide, the same handbook or price list is uploaded once and used by every agent that needs it. Deleting a source from the library removes it from every agent that used it.

What each agent uses

An agent keeps two lists: the folders it selected and the loose sources it selected. You edit both on the agent's Knowledge tab.

  • Selecting a folder is a live reference. The agent gets whatever is in that folder at the time of the call, so a file added to the folder next week is picked up with no change to the agent. The portal says this in the folder row: Live folder: always reflects its current contents.
  • Selecting a source works for a loose source. A source that lives inside a folder is covered by selecting its folder, and moving a source into a folder drops it from every agent's individual picks.

If someone deletes a folder, the agents that selected it are updated rather than left pointing at nothing.

What happens at a turn

Retrieval is per agent, and it is off until you turn it on. It has three settings:

Setting Portal label Default Accepted range
enabled Enable retrieval false on or off
topK Top documents 5 1 to 50 in the API, 1 to 20 on the slider
minSimilarity Relevance threshold 0.7 0 to 1

When retrieval is off, the agent ignores every source you selected. The portal says so on the tab: Retrieval is off and This agent ignores all selected knowledge, so nothing below is used.

When retrieval is on, the agent searches the sources it can use on every turn and keeps the passages that clear Relevance threshold, up to Top documents of them. Those passages are what the model answers from.

Only ready sources count

A source is used only once it shows Ready. A document still indexing, or one that failed, is simply not part of the turn: nothing is queued and nothing waits.

That is why a selected folder on the agent's Knowledge tab reads All ready only when every source inside it is ready, and otherwise shows how many are still indexing. It is telling you how much of what you selected can be used right now.

A ready source also carries a chunk count, shown in the Chunks column: how many passages the source was split into. A source that is ready with very few chunks usually had very little extractable text.

Get it right

Retrieval competes: only Top documents passages reach a turn, so a few focused sources beat one folder holding everything the workspace has ever uploaded.

Recommended

  • A Returns and refunds folder on the returns agent, holding the policy and the FAQ.
  • One folder per job, selected by the agent that does that job.

Less effective

  • One Company documents folder holding contracts, slide decks and the handbook, selected by every agent.
  • Individually picking forty loose sources so that the right one is "in there somewhere".

When a change takes effect

Adding, removing or replacing an agent's knowledge applies to the next conversation at once. Changing Enable retrieval, Top documents or Relevance threshold, and a source turning Ready, can take up to a minute to reach a new conversation. A conversation already running keeps the settings it started with.

After any change, start a new conversation to test it.

FAQ

Why does my agent ignore a document I attached?

Retrieval starts off on a new agent. Turn on Enable retrieval on the Knowledge tab, then work through the checklist.

Does knowledge go into the prompt?

No. The prompt is your Personality text. Knowledge is searched during the conversation and only matching passages reach the model, which is why reference material costs less here than in the prompt.

Can one agent's knowledge be private to it?

No. Every source is in the workspace library and visible to the workspace. Selection is per agent; storage is shared.

How many sources can one agent select?

There is no limit on the selection. The practical limit is Top documents, since only that many passages reach any one turn.

Does the agent tell me which source it used?

Not on the knowledge screens. Compare the answer against the sources you selected, and use the Chunks count to check a source has usable text in it.