A Knowledge block searches a knowledge base and hands the matching passages to a later block, so an Agent can answer from your documents instead of the model's memory alone. It works like asking a librarian for the most relevant excerpts on a topic: you give it a question and get back a ranked, source-labeled list. This page covers searching, narrowing with tags, reranking, and reading the results.
In this workflow, the Knowledge block searches a base of product docs for the customer's question, and the Agent answers from the passages it returns.
Search
A Knowledge block set to Search takes a query, compares it against the chunks in a base, and returns the closest matches. (The block can also manage documents and chunks, but Search is what a workflow uses to retrieve context.) You point it at a knowledge base and give it a query; in our example the query is <start.input>, the customer's question.
Search is semantic, not keyword matching. The block turns the query into a vector and finds the chunks whose meaning is closest, so "refund timelines" can match a passage that says "we process returns within 14 days" with no shared words.
Number of Results (topK) sets how many chunks come back, 10 by default. Fewer give the agent a tight, focused set; more widen the net at the cost of noise and tokens.
You can also search by tags, instead of or alongside a query:
| What you provide | What it does |
|---|---|
| Query only | Semantic search across every document in the base. The default. |
| Tags only | Returns documents that match the tags, with no ranking by meaning. |
| Query and tags | Tags narrow the document set first, then semantic search runs within it. The most precise. |
Tag Filters
Tag Filters restrict a search to documents carrying specific tags. Each filter has three parts: a Tag (a tag defined on the base, like Department), an Operator (equals, contains, greater than, and others depending on the tag's type), and a Value to match.
In our example, adding Department equals "Billing" makes the search consider only billing documents. Add more filters with the + button; multiple filters combine with AND, so a document must match all of them. A filter value can be a fixed string or a reference like <start.department>, so the scope can change per run.
Filters run before the vector comparison, so they make a search both more precise and cheaper. See Tags and filtering for the full operator list by tag type.
Rerank Results
Rerank Results is an optional second pass. Vector search ranks by raw similarity; reranking re-scores the top matches with a dedicated relevance model (Cohere's rerank models) and reorders them, which sharpens the ordering when the best answer isn't the literal closest vector.
Leave it off for most searches. Turn it on when retrieval returns roughly the right documents but in the wrong order. When enabled, you pick a Rerank Model; self-hosted deployments also supply a Cohere API key.
Retrieved chunks
The Search operation produces an output stored under the block's name, the same as any other block. Its main value is results: an array of the matched chunks, ranked best first. A later block reads it by reference, for example <knowledge.results>.
Each result in the array is an object with these fields:
| Field | What it is |
|---|---|
content | The chunk's text. This is what the agent reads. |
documentName | The source document's filename, for citation. |
sourceUrl | A link to the original, if the document came from a connector. null for uploaded files. |
chunkIndex | The chunk's position within its document. |
similarity | How close the chunk is to the query, higher is better. For example 0.92. |
metadata | The document's attributes, including its tags. |
documentId | The source document's identifier. |
The output also carries query (the text that was searched) and totalResults (the count).
To ground an answer, wire the Knowledge block before an Agent block and reference the chunks in the Agent's prompt with <knowledge.results>. The agent reads the content of each result and can cite documentName and sourceUrl. See how blocks reference output for how one block reads another's output by name.
When retrieval looks wrong
When the agent's answer is off, the cause is usually in retrieval, not the agent. Read the Knowledge block's output in the run logs and check the chunks it actually returned:
- No results, or wrong documents. A tag filter may be excluding what you want, or the documents may not be indexed yet. A document is only searchable once its processing status is
completed; while it ispending,processing, orfailed, its chunks won't appear. - Low similarity scores across the board. The query is too vague, or the information simply isn't in the base. Rewrite the query to match how the documents phrase things.
- Right documents, wrong order. Turn on Rerank Results, or raise Number of Results so the relevant chunk is included.
See debugging retrieval for the full diagnostic path, and chunking strategies for how chunk boundaries shape what a search can return.