Query Knowledge Base

What it is

Query Knowledge Base is the native tool that retrieves excerpts from the bases linked to an agent. It lets the agent answer from organization-owned material — such as products, pricing, policies, procedures, FAQs, and manuals — instead of relying only on the model’s general knowledge.

The tool is no longer added from the Tools section. It is enabled automatically when at least one base is selected under Knowledge and disabled when the last base is cleared.

Permissions and prerequisites

To configure the link, a person must be allowed to edit the agent (agents.write) and edit bases (bases.write). To create or review content first, open Knowledge Bases at /admin/bases; see the knowledge bases overview.

Each base should have:

• a name and description that clearly explain what it covers;
• items whose index processing has completed;
• current content without duplicates or conflicting instructions.

The base description is especially important: it enters the catalog the model reads when deciding whether to search. When a selected base has no description, the interface warns that the agent can see only its name.

Link bases to the agent

1. Open Agents, select the agent, and go to Knowledge.
2. In the Knowledge bases column labeled Searched on demand, select one or more bases.
3. Check the number of searchable items. It is the sum of items in selected bases, not the number of excerpts added to each answer.
4. Expand The instruction the agent receives to review the general rule and base catalog.
5. If needed, fill Rule for this agent only (optional).
6. To log unanswered questions, enable AutoLearn. This option appears only while at least one base is selected.
7. Select Save in the changes bar.

Selecting a base creates and enables the internal search_knowledge_base contract. The agent-specific rule is appended after the general guidance and wins in case of conflict; it does not replace or hide the base catalog.

How to instruct the agent

Without a specific rule, the agent receives an instruction to search before answering any question that company material could clarify. The only call parameter is query, containing a question or search terms.

Use the optional rule to restrict or prioritize concrete situations. For example:

Search the bases for questions about products, pricing, cancellations, and commercial policy. If the material does not support an answer, say that the information was not found; do not fill gaps from memory.

Reinforce three behaviors in the main prompt:

• search before asserting facts that belong to the organization;
• answer only what the retrieved excerpts support;
• when there is no relevant result, request context or acknowledge the absence instead of making up an answer.

How retrieval works

The default path uses hybrid retrieval: it combines semantic embeddings with lexical BM25 search, fuses and reranks candidates, and may try up to two deterministic spelling variants when the first pass is uncertain. Expansion by another model exists in the engine but is disabled in the audited production configuration.

Retrieval applies the organization ID and only the linked bases. Before replying, the engine also validates every excerpt’s provenance; a result outside that scope invalidates the context and triggers the legacy fallback.

The context delivered to the model:

• contains at most eight excerpts and 8,000 characters on the hybrid path;
• removes very short excerpts and strong overlap;
• prefixes each excerpt with the item name and, when available, its heading and subheading path;
• does not expose the similarity score or a source URL.

The agent may therefore mention the document and section it received, but it should offer a link only when that URL is present in the retrieved content itself. The entire base is not copied into the prompt: only selected excerpts enter each search.

No result, errors, and AutoLearn

When search succeeds but finds no sufficiently relevant material, the tool returns the canonical sentence “Nenhuma informação relevante encontrada na base de conhecimento.” This differs from a technical failure, which returns a search error message.

If AutoLearn is enabled, the agent also receives the gap-reporting tool and must use it when search returns that exact no-result state. Questions appear under Knowledge Bases → Learning Opportunities for review; see Report Gap.

AutoLearn does not turn the question into published content by itself. A person still reviews and approves what should feed the base.

Limits and troubleshooting

• It does not appear under Tools: this is expected. Manage the link under Knowledge.
• Save fails: confirm agents.write and bases.write. The agent editor is opened with the former, but the backend requires both.
• Search is not called: confirm a base is selected, each base description defines its scope, and the displayed instruction covers the actual use case.
• Search misses existing information: check item processing, title, headings, and terminology. Hybrid retrieval improves lexical and semantic matching, but it cannot guarantee recall for every existing answer.
• An outdated excerpt is returned: correct or remove the item in the base. Deleted-base validation fails open when its verification query fails, so do not treat a partial outage as proof of immediate index removal.
• Usage: bases are searched on demand. The text model consumes tokens for the query, selected excerpts, and answer; the entire base is not loaded on every turn. Context blocks, shown in the neighboring column, follow a different contract and are loaded on every reply.