<!-- BusyBot node reference — https://busybot.net/tools/search-knowledge-base/ -->

> Node: Search Knowledge Base (`search_knowledge_base`) · Action · v1
> Category: Data & Storage · Credentials: none
> Updated: 2026-08-16

# Search Knowledge Base

> AI search over a knowledge base

## Overview

Runs an agentic search over a BusyBot knowledge base. A search subagent greps, reads and semantically analyzes the knowledge base documents, records evidence, and returns findings (per-document extracted content with confidence), a written answer to the query, and a summary of how the search was conducted. Supports a fast mode (up to 20 iterations) and a deep-research mode (40 iterations across 8 phases).

**Category:** Data & Storage  
**Tool Name:** `search_knowledge_base`  
**Version:** 1

**Appearance:** Icon: `lucide-ScanSearch` | Color: `#7C3AED`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Query | `string` | Yes | — | What to find, in natural language. A full question works far better than keywords. Supports expressions. |
| Mode | `options` | No | `quick` | How thoroughly to search. |
| | | | | Options: `quick` (free-form search, up to 20 iterations — the engine agent chat uses), `deep` (40 iterations across 8 gated research phases; slow and expensive, best for background runs) |
| Max Iterations | `number` | No | `20` | Quick mode only — upper bound on search iterations. Deep mode always runs its 40-iteration phase plan. _(shown when Mode is `quick`)_ |
| Output Mode | `options` | No | `single` | How to shape the output items. |
| | | | | Options: `single` (one output item per input item, findings nested in an array), `perFinding` (fan out — one output item per finding) |
| Include Findings | `boolean` | No | `true` | Include per-document extracted content. Turn off to return only the answer and summary. _(shown when Output Mode is `single`)_ |
| Include Search Steps | `boolean` | No | `false` | Include the step-by-step trace of what the search agent did (useful for debugging a disappointing answer). |
| Fail If Nothing Found | `boolean` | No | `false` | Treat a search that returns no findings as an item error instead of a normal result. |
| Max Concurrency | `number` | No | `2` | Searches running at once. Each is a full LLM agent loop — keep this low. |

## Output Data

One search per input item. Results are written to `kbSearch` on the output item; the rest of the item JSON passes through unchanged, and binary data is forwarded.

```json
{
  "kbId": "kb_...", "kbName": "Product Manuals", "query": "...", "mode": "quick",
  "answer": "The direct answer synthesized from the findings",
  "searchSummary": "What was searched, which documents were examined, how the answer was reached",
  "findings": [{ "docId": "doc_...", "fileName": "manual.pdf", "relevantContent": "the actual extracted text", "confidence": "high" }],
  "findingCount": 3, "iterations": 6, "exitReason": "model",
  "documentsInKb": 42, "stale": false, "healthy": true, "durationMs": 18420
}
```

- `exitReason`: `model` (the agent finished on its own — the good case), `cap` (hit the iteration limit), `stall` (repeated itself and was cut short), `phased` (deep mode ran its full course).
- `stale: true` means documents changed since the knowledge base summary was regenerated; results may not reflect the latest content.
- `findings` is present in `single` output mode when Include Findings is on. In `perFinding` mode the node fans out instead: one output item per finding, each carrying `finding` and `findingIndex` with the answer and summary repeated. A search with no findings still emits one item, with `finding: null`.
- `steps` is added when Include Search Steps is on, and `phasesVisited` when Mode is `deep`.

Reference the result downstream by expression, e.g. `{{ $json.kbSearch.answer }}`.

## Usage Examples

- search the knowledge base for the payment terms
- ask my knowledge base what the maintenance interval is
- do deep research across the knowledge base on data retention commitments
- find every document mentioning the vendor and quote the relevant lines

## Example Configuration

Answer a question from a knowledge base:

```json
{
  "type": "search_knowledge_base",
  "parameters": {
    "knowledgeBase": "Product Manuals",
    "query": "What is the recommended maintenance interval for the {{ $json.model }} pump?",
    "mode": "quick"
  }
}
```

Deep background research, fanned out one item per finding:

```json
{
  "type": "search_knowledge_base",
  "parameters": {
    "knowledgeBase": "kb_1765432100000_ab12cd34",
    "query": "Every commitment we made about data retention, with the document it came from",
    "mode": "deep",
    "outputMode": "perFinding",
    "includeSteps": true
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Searches a knowledge base with an AI research subagent and returns what it found: per-document findings with the actual extracted content and a confidence level, a written answer to the query, and a summary of how the search was run. Use quick mode for normal lookups and deep mode for exhaustive background research — deep runs 40 phased iterations (map, synonym expansion, semantic deep-read, cross-checking, gap analysis, verification, synthesis) and costs substantially more time and tokens. Point it at a knowledge base by ID or name and give it a natural-language question rather than keywords.

### Choosing a mode

- **quick** — the default. Typical searches finish in 3–8 iterations. Use for lookups, enrichment inside a live pipeline, and anything a person is waiting on.
- **deep** — a scheduled/background research job over a large or high-stakes corpus: exhaustive enumeration, "is X mentioned anywhere", contradiction hunting, or literature-style review. It always runs its phases and can take many minutes.

### Behavior notes

- The knowledge base must be ready (ingested). Searching an empty or still-processing KB errors.
- The content bundle is downloaded once per knowledge base per node run and shared by every item targeting it, then deleted.
- Cost is real: `llm_search` sends document text to a model, and deep mode is designed to spend iterations. Prefer quick mode plus a narrow query.