Agent Retrieval#

The Retrieval node is a canvas component in RAGFlow agent workflows that connects one or more knowledge bases to a running agent graph. Its implementation lives in agent/tools/retrieval.py and, like every other retrieval entry point, converges on the shared engine Dealer.retrieval() in rag/nlp/search.py 1.

Configuration Parameters#

The RetrievalParam class 2 defines all configurable fields:

The single runtime input is a Query line field 3.

Dataset Selection#

Datasets are configured via dataset_ids (with kb_ids as a backward-compatible alias) 4. Each entry in the list can be:

• A literal KB UUID — added directly to the retrieval call 5.
• A {{cpn_id@var}} variable reference — resolved at runtime against canvas outputs, then looked up by name or ID via KnowledgebaseService.get_by_name() / get_by_id(). Variables may resolve to a single value or a list 6.

Before retrieval executes, the system validates that all selected datasets share the same embedding model 7.

Query Preprocessing Pipeline#

Inside _retrieve_kb(), the query passes through this fixed sequence before hitting Dealer.retrieval() 1:

1. Variable substitution — get_input_elements_from_text() + string_format() resolve {{...}} tokens in the query text 8.
2. "user:" prefix stripping — re.sub(r"^user[:：\s]*", "", query, re.IGNORECASE) removes any prefix a prior LLM step may have prepended 9.
3. Metadata filtering — apply_meta_data_filter() computes a doc_ids whitelist in one of three modes: auto (LLM-generated), semi_auto (LLM-restricted to specified keys), or manual (explicit conditions). A sentinel "-999" is passed when no docs match to prevent unfiltered fallback 10.
4. Cross-language expansion — cross_languages() translates the query into target languages and concatenates all variants into a single retrieval call 1.

Knowledge Graph Integration#

When use_kg=true, after the standard vector retrieval completes, settings.kg_retriever.retrieval() is called with the tenant ID, chat LLM config, embedding model, and KB IDs. The returned KG chunk is inserted at index 0 of the results list 11 — meaning it always appears first regardless of its vector similarity score 12.

Prerequisites for KG to work 13:

1. Build the KB's knowledge graph first (parse documents → Generate → Knowledge graph).
2. In the Retrieval node's Advanced settings, enable Use knowledge graph.
3. Use {retrieval_node_id@formalized_content} downstream as usual.

Note: the KG generation workflow changed in September 2025 — the "Knowledge Graph" chunk method was removed from dataset creation. KG is now a separate post-parsing step 14.

Divergence from Knowledge Retrieval Test#

The Knowledge Retrieval Test UI (the /api/v1/retrieval endpoint, handled by retrieval_test()) and the Agent Retrieval node both call Dealer.retrieval(), but with different hardcoded defaults 15:

Additional non-configurable differences:

• The Agent strips "user:" prefixes; the KB test does not.
• The Agent applies metadata filtering and variable substitution automatically; the KB test requires explicit document_ids.
• Rerank batching uses a dynamic window (~64 chunks) in the agent path vs. a single pass in the KB test, which can change score normalization and final ranking order even with a matched reranker 15.

Practical impact: The Retrieval Test is not a faithful replica of Agent Retrieval behavior. To minimize divergence when tuning, explicitly set vector_similarity_weight=0.5 and page_size=8 in the test, or match both sides manually 15.

Multi-KB Behavior and Known Issues#

When multiple datasets are selected, all are searched in a single Dealer.retrieval() call. A known historical issue (v0.17.x) caused the effective candidate pool (RERANK_LIMIT) to be insufficient when many KBs were selected, causing higher-relevance chunks from some KBs to be dropped before reranking 16. Subsequent releases addressed this.

Key Source Files#