arch-knowledge-search

Knowledge and search

A wrong knowledge-base answer has one of four causes: the document never got indexed, the search did not return the right chunk, the chunk was cut by a budget, or the model ignored it. Find which one from the evidence before changing anything.

How an agent uses a knowledge base

• Each knowledge base is bound as a project tool, search_kb_<name>(query) with type: searchai. The binding can carry search_instructions, retrieval_profile and the release-dependent kb_fast_path. An agent file can set search_instructions, compaction: and kb_fast_path for the tool (its kb_fast_path choice wins); its search_instructions is ignored when the project tool already has some.
• The model picks between knowledge bases by their descriptions, so write a specific one for each.
• Search parameters (queryType, filters, topK, similarityThreshold) can be declared in the tool signature; the runtime may also add query type and filters when search instructions call for them. Filters the model chooses are kept only when grounded in the user's words, and filters must be an array. A filter that must always apply belongs in the tool's enforced inputs.
• Citations: when on, the model cites with [n] and text channels add a "Sources:" list. Citations are set per tool in current releases (in 1.7.3, one knowledge base with citations off turned them off for all).
• Automatic first search. For an agent whose only business tool is one knowledge base (not a router or orchestrator, no handoff or delegate tools, no GATHER fields with inline gather), the platform can search before the first model call and save a model round. In release 1.7.3 it is always on for agents that qualify, skips the tool's hooks and MODEL_CONTEXT, and shows the model only the last 5 earlier messages. Later releases make it opt-in per tool with kb_fast_path: on, run it as a normal tool call, and exclude tools with confirmation or on_result/on_error actions. Check which release the project runs.