Retrieval

How a question is matched against chunks, what the query settings change, which ones do nothing yet, and the two ways an agent reaches a knowledge base.

How a passage is scored

The question is embedded with the same model the chunks were, and chunks are ranked by cosine distance between the two vectors. The score you see is 1 - distance, so it runs from 0 to 1 and larger is closer.

confidence 0.82   the chunk is about what you asked
confidence 0.55   related subject, probably not an answer
confidence 0.31   shares vocabulary and little else

Those boundaries are not thresholds the platform enforces, they are what the numbers tend to mean in practice. Scores are only comparable within one knowledge base: a different embedding model or different chunk sizes shift the whole range.

Two properties follow from this being a vector comparison rather than a search:

Every query returns something. There is no "no match". Ask an unrelated question and you get the least unrelated chunks, with low scores. Whatever consumes the results has to look at the scores.
Negation does not work. "Policies that are not about refunds" embeds close to policies about refunds, because that is what the sentence is about.

What the settings actually do

This is worth being precise about, because the configuration offers more than the retrieval path currently reads.

Setting	Range	Effect
`defaultTopK`	1 to 50	Used. How many chunks to retrieve, when the caller does not say.
`similarityThreshold`	0 to 1	Not read during retrieval. See below.
`maxContextLength`	500 to 16000	Not read during retrieval.
`rerankEnabled`	boolean	Not read anywhere. There is no reranking step.

Three of those four are recorded and have no effect on what a search returns. The RAG tool reads defaultTopK and nothing else from this configuration, caps the result count at 25 whatever you set, and applies a confidence floor of 0.3 that comes from the tool call rather than from the knowledge base. If you have tuned similarityThreshold and seen no change, that is why.

So in practice, to change retrieval behaviour today:

Fewer or more passages: set defaultTopK, or pass a result count on the tool call. Either way 25 is the ceiling.
A stricter floor: pass a confidence threshold on the tool call. The knowledge base's own similarityThreshold will not do it.
Better matches: change the chunking and re-index. This is the lever that actually moves results, and it is covered in Documents.

Reaching a knowledge base from an agent

A RAG tool

A tool of type rag is bound to exactly one knowledge base, by id. The agent calls it like any other tool, with a query and optionally a result count and confidence floor.

Each result carries the passage, the document it came from, a page or section when the extraction captured one, and its confidence score. Those fields are what let an agent cite a source rather than assert something.

This is the option to prefer. The call appears in the agent's trace with its arguments and its results, so when an answer is wrong you can see whether retrieval or the model was at fault. A knowledge base attached invisibly gives you no such split.

Attached to the agent

A knowledge base can also be bound to a specific agent version, with an optional expression. The expression decides whether that base applies to a given conversation, so one agent can draw on different material depending on context, for example the caller's region or product line.

The binding is per agent version, not per agent. Publishing a new version carries the bindings of the draft it came from, and an older published version keeps the bindings it had, which is what makes a published agent reproducible.

Testing retrieval on its own

The knowledge base test box does the full retrieval and then has a model answer from it. Use it to separate the two failures:

Symptom	Where to look
Passages are right, answer is wrong	The agent's prompt, or the model
Passages are wrong or thin, answer is confident anyway	Chunking, or the document did not extract
Every score is low	The material is not in this base at all
Scores are high but the passages are off-topic	Chunks too large, so the vectors are vague

A model given poor passages will still produce a fluent answer. Reading the passages is the only way to tell the difference, which is why the test box shows them.