Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

feat(agent): support document_ids in retrieval node and tool (#16938)

天海蒼灆ebbdd5028a3a
diff --git a/agent/tools/retrieval.py b/agent/tools/retrieval.py
index 1ab7a6522e..137dd9e48b 100644
--- a/agent/tools/retrieval.py
+++ b/agent/tools/retrieval.py
@@ -16,6 +16,7 @@
import asyncio
from functools import partial
import json
+import logging
import os
import re
from abc import ABC
@@ -85,6 +86,7 @@ class RetrievalParam(ToolParamBase):
self.cross_languages = []
self.toc_enhance = False
self.meta_data_filter = {}
+ self.document_ids = ""
def check(self):
self.check_decimal_float(self.similarity_threshold, "[Retrieval] Similarity threshold")
@@ -92,7 +94,10 @@ class RetrievalParam(ToolParamBase):
self.check_positive_number(self.top_n, "[Retrieval] Top N")
def get_input_form(self) -> dict[str, dict]:
- return {"query": {"name": "Query", "type": "line"}}
+ return {
+ "query": {"name": "Query", "type": "line"},
+ "document_ids": {"name": "Document IDs", "type": "line"},
+ }
class Retrieval(ToolBase, ABC):
@@ -103,6 +108,30 @@ class Retrieval(ToolBase, ABC):
"""Get dataset IDs with backward compatibility for kb_ids."""
return self._param.dataset_ids or getattr(self._param, "kb_ids", None) or []
+ @staticmethod
+ def _normalize_document_ids(value) -> list[str]:
+ if value is None or value == "" or value == []:
+ return []
+ if isinstance(value, list):
+ return [str(v) for v in value if v]
+ if isinstance(value, str):
+ value = value.strip()
+ if not value:
+ return []
+ return [value]
+ return []
+
+ def _resolve_document_ids(self, kwargs_document_ids=None) -> list[str]:
+ doc_ids = self._normalize_document_ids(kwargs_document_ids)
+ if doc_ids:
+ return doc_ids
+ raw = getattr(self._param, "document_ids", None)
+ if raw is None or raw == "" or raw == []:
+ return []
+ if isinstance(raw, str) and self._canvas.is_reff(raw):
+ return self._normalize_document_ids(self._canvas.get_variable_value(raw))
+ return self._normalize_document_ids(raw)
+
def _resolve_manual_filter(self, flt: dict) -> dict:
# Return a new dict instead of mutating `flt` in place. The caller
# passes filters straight out of self._param.meta_data_filter, so
@@ -124,7 +153,7 @@ class Retrieval(ToolBase, ABC):
resolved["value"] = self._replace_template_matches(pat, content, replace)
return resolved
- async def _retrieve_kb(self, query_text: str):
+ async def _retrieve_kb(self, query_text: str, document_ids=None):
kb_ids: list[str] = []
for id in self._dataset_ids:
if id.find("@") < 0:
@@ -164,7 +193,13 @@ class Retrieval(ToolBase, ABC):
vars = {k: o["value"] for k, o in vars.items()}
query = self.string_format(query_text, vars)
- doc_ids = []
+ doc_ids = self._resolve_document_ids(document_ids)
+ if doc_ids:
+ logging.info("Retrieval resolved document_ids=%s", doc_ids)
+ kb_doc_ids = KnowledgebaseService.list_documents_by_ids(filtered_kb_ids)
+ for doc_id in doc_ids:
+ if doc_id not in kb_doc_ids:
+ raise Exception(f"The datasets don't own the document {doc_id}")
if self._param.meta_data_filter != {}:
# Defer the (potentially expensive) metadata table load — manual
# filters served by ES push-down never need it. The loader is
@@ -307,12 +342,13 @@ class Retrieval(ToolBase, ABC):
self.set_output("formalized_content", self._param.empty_response)
return
+ document_ids = self._resolve_document_ids(kwargs.get("document_ids"))
if hasattr(self._param, "retrieval_from") and self._param.retrieval_from == "dataset":
- return await self._retrieve_kb(kwargs["query"])
+ return await self._retrieve_kb(kwargs["query"], document_ids)
elif hasattr(self._param, "retrieval_from") and self._param.retrieval_from == "memory":
return await self._retrieve_memory(kwargs["query"])
elif self._dataset_ids:
- return await self._retrieve_kb(kwargs["query"])
+ return await self._retrieve_kb(kwargs["query"], document_ids)
elif hasattr(self._param, "memory_ids") and self._param.memory_ids:
return await self._retrieve_memory(kwargs["query"])
else:
diff --git a/internal/agent/component/universe_a_wrappers.go b/internal/agent/component/universe_a_wrappers.go
index 999916c3b1..504dc56dfd 100644
--- a/internal/agent/component/universe_a_wrappers.go
+++ b/internal/agent/component/universe_a_wrappers.go
@@ -68,6 +68,7 @@ type retrievalParams struct {
Query string
KbIDs []string
MemoryIDs []string
+ DocumentIDs []string
UserID string
TopN int
TopK int
@@ -109,6 +110,13 @@ func parseRetrievalParams(params map[string]any) retrievalParams {
out.KbIDs = append(out.KbIDs, v...)
}
out.MemoryIDs = toStringSlice(params["memory_ids"])
+ if v, ok := params["document_ids"].(string); ok {
+ if strings.TrimSpace(v) != "" {
+ out.DocumentIDs = []string{v}
+ }
+ } else {
+ out.DocumentIDs = toStringSlice(params["document_ids"])
+ }
if v, ok := params["user_id"].(string); ok {
out.UserID = v
}
@@ -170,10 +178,11 @@ func (c *retrievalComponent) Name() string { return "Retrieval" }
func (c *retrievalComponent) Inputs() map[string]string {
return map[string]string{
- "query": "Natural-language search query.",
- "dataset_ids": "Optional list of dataset IDs to restrict the search to (overrides node-level kb_ids).",
- "top_n": "Maximum chunks to return (default 8, overrides node-level top_n).",
- "use_kg": "GraphRAG toggle (returns ErrKGRetrievalServiceMissing until a kg adapter is registered).",
+ "query": "Natural-language search query.",
+ "dataset_ids": "Optional list of dataset IDs to restrict the search to (overrides node-level kb_ids).",
+ "document_ids": "Optional list of document IDs to restrict retrieval scope.",
+ "top_n": "Maximum chunks to return (default 8, overrides node-level top_n).",
+ "use_kg": "GraphRAG toggle (returns ErrKGRetrievalServiceMissing until a kg adapter is registered).",
}
}
@@ -183,6 +192,10 @@ func (c *retrievalComponent) GetInputForm() map[string]any {
"name": "Query",
"type": "line",
},
+ "document_ids": map[string]any{
+ "name": "Document IDs",
+ "type": "line",
+ },
}
}
@@ -294,6 +307,16 @@ func (c *retrievalComponent) applyDefaults(inputs map[string]any) map[string]any
if _, ok := out["memory_ids"]; !ok && len(c.params.MemoryIDs) > 0 {
out["memory_ids"] = append([]string(nil), c.params.MemoryIDs...)
}
+ if _, ok := out["document_ids"]; !ok && len(c.params.DocumentIDs) > 0 {
+ out["document_ids"] = append([]string(nil), c.params.DocumentIDs...)
+ }
+ if s, ok := out["document_ids"].(string); ok {
+ if strings.TrimSpace(s) == "" {
+ delete(out, "document_ids")
+ } else {
+ out["document_ids"] = []string{s}
+ }
+ }
if _, ok := out["user_id"]; !ok && c.params.UserID != "" {
out["user_id"] = c.params.UserID
}
diff --git a/internal/agent/tool/registry.go b/internal/agent/tool/registry.go
index 7781eadcaa..76ee35c691 100644
--- a/internal/agent/tool/registry.go
+++ b/internal/agent/tool/registry.go
@@ -399,7 +399,7 @@ func buildRetrievalTool(params map[string]any) (einotool.BaseTool, error) {
"keywords_similarity_weight", "use_kg", "rerank_id", "empty_response",
"toc_enhance", "meta_data_filter", "retrieval_from", "memory_ids",
"kb_vars", "cross_languages", "function_name", "description", "meta",
- "inputs", "outputs", "user_id":
+ "inputs", "outputs", "user_id", "document_ids":
default:
return nil, fmt.Errorf("agent tool: retrieval tool does not accept node-level param %s", key)
}
@@ -423,6 +423,15 @@ func buildRetrievalTool(params map[string]any) (einotool.BaseTool, error) {
} else if ok {
defaults.MemoryIDs = ids
}
+ if v, ok := params["document_ids"].(string); ok {
+ if strings.TrimSpace(v) != "" {
+ defaults.DocumentIDs = []string{v}
+ }
+ } else if ids, ok, err := stringSliceParam(params, "document_ids"); err != nil {
+ return nil, fmt.Errorf("agent tool: retrieval config: %w", err)
+ } else if ok {
+ defaults.DocumentIDs = ids
+ }
if v, ok := stringParam(params, "user_id"); ok {
defaults.UserID = v
}
diff --git a/internal/agent/tool/retrieval.go b/internal/agent/tool/retrieval.go
index f4d3b2bb51..db399e6a48 100644
--- a/internal/agent/tool/retrieval.go
+++ b/internal/agent/tool/retrieval.go
@@ -60,6 +60,7 @@ type retrievalArgs struct {
DatasetIDs []string `json:"dataset_ids,omitempty"`
KBIDs []string `json:"kb_ids,omitempty"`
MemoryIDs []string `json:"memory_ids,omitempty"`
+ DocumentIDs []string `json:"document_ids,omitempty"`
UserID string `json:"user_id,omitempty"`
TopN int `json:"top_n,omitempty"`
RerankCandidatesCount int `json:"rerank_candidates_count,omitempty"`
@@ -131,6 +132,11 @@ func (r *RetrievalTool) Info(_ context.Context) (*schema.ToolInfo, error) {
Desc: "The keywords to search the dataset. The keywords should be the most important words/terms (including synonyms) from the original request.",
Required: true,
},
+ "document_ids": {
+ Type: schema.Array,
+ Desc: "Optional list of document IDs to restrict retrieval scope.",
+ Required: false,
+ },
}),
}, nil
}
@@ -160,6 +166,7 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
common.Debug("agent retrieval tool: parsed arguments",
zap.String("query", args.Query),
zap.Strings("dataset_ids", args.DatasetIDs),
+ zap.Strings("document_ids", args.DocumentIDs),
zap.Int("top_n", args.TopN),
zap.Int("top_k", args.TopK),
zap.Float64p("keywords_similarity_weight", args.KeywordsSimilarityWeight),
@@ -191,6 +198,11 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
return "", err
}
args.DatasetIDs = resolvedDatasetIDs
+ resolvedDocumentIDs, err := resolveRetrievalDocumentIDs(ctx, args.DocumentIDs)
+ if err != nil {
+ return "", err
+ }
+ args.DocumentIDs = resolvedDocumentIDs
resolvedFilter, err := resolveRetrievalFilter(ctx, args.MetaDataFilter)
if err != nil {
return "", err
@@ -217,6 +229,7 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
TOCEnhance: args.TOCEnhance,
MetaDataFilter: cloneStringAnyMap(args.MetaDataFilter),
RetrievalFrom: args.RetrievalFrom,
+ DocScope: append([]string(nil), args.DocumentIDs...),
UserID: args.UserID,
TenantID: retrievalTenantID(ctx),
}
@@ -280,6 +293,9 @@ func (r *RetrievalTool) mergeDefaults(args retrievalArgs) retrievalArgs {
if len(args.MemoryIDs) == 0 && len(r.defaults.MemoryIDs) != 0 {
args.MemoryIDs = append([]string(nil), r.defaults.MemoryIDs...)
}
+ if len(args.DocumentIDs) == 0 && len(r.defaults.DocumentIDs) != 0 {
+ args.DocumentIDs = append([]string(nil), r.defaults.DocumentIDs...)
+ }
if args.TopN <= 0 {
args.TopN = r.defaults.TopN
}
@@ -433,6 +449,61 @@ func resolveRetrievalDatasetIDs(ctx context.Context, datasetIDs []string) ([]str
return compactStrings(resolved), nil
}
+func resolveRetrievalDocumentIDs(ctx context.Context, documentIDs []string) ([]string, error) {
+ state, _, err := runtime.GetStateFromContext[*runtime.CanvasState](ctx)
+ if err != nil || state == nil {
+ return compactStrings(documentIDs), nil
+ }
+ resolved := make([]string, 0, len(documentIDs))
+ for _, documentID := range documentIDs {
+ documentID = strings.TrimSpace(documentID)
+ if documentID == "" {
+ continue
+ }
+ if strings.Contains(documentID, "@") {
+ value, getErr := state.GetVar(documentID)
+ if getErr != nil {
+ return nil, fmt.Errorf("retrieval: resolve document variable %q: %w", documentID, getErr)
+ }
+ resolved = append(resolved, normalizeResolvedDocumentIDs(value)...)
+ continue
+ }
+ text, resolveErr := runtime.ResolveTemplateAuto(documentID, state)
+ if resolveErr != nil {
+ return nil, fmt.Errorf("retrieval: resolve document_ids template: %w", resolveErr)
+ }
+ resolved = append(resolved, normalizeResolvedDocumentIDs(text)...)
+ }
+ return compactStrings(resolved), nil
+}
+
+func normalizeResolvedDocumentIDs(value any) []string {
+ switch typed := value.(type) {
+ case nil:
+ return nil
+ case string:
+ typed = strings.TrimSpace(typed)
+ if typed == "" {
+ return nil
+ }
+ return []string{typed}
+ case []string:
+ return typed
+ case []any:
+ out := make([]string, 0, len(typed))
+ for _, item := range typed {
+ out = append(out, normalizeResolvedDocumentIDs(item)...)
+ }
+ return out
+ default:
+ text := strings.TrimSpace(fmt.Sprint(typed))
+ if text == "" || text == "<nil>" {
+ return nil
+ }
+ return []string{text}
+ }
+}
+
func resolveRetrievalFilter(ctx context.Context, filter map[string]any) (map[string]any, error) {
if filter == nil {
return nil, nil
diff --git a/internal/agent/tool/retrieval_service.go b/internal/agent/tool/retrieval_service.go
index a4ccfdbf55..a064f89bc9 100644
--- a/internal/agent/tool/retrieval_service.go
+++ b/internal/agent/tool/retrieval_service.go
@@ -71,8 +71,8 @@ type RetrievalRequest struct {
RankFeature *map[string]float64
MetaDataFilter map[string]any
RetrievalFrom string
- // DocScope restricts retrieval to a set of document ids (the doc_id list
- // routed by the dataset_navigation_by_tree tool). Empty = no doc filter.
+ // DocScope restricts retrieval to a set of document ids (from document_ids
+ // on the retrieval node/tool, or dataset_navigation_by_tree). Empty = no doc filter.
DocScope []string
// TenantID is the calling tenant (== user_id in RAGFlow's data model).
// It is used for dataset-name resolution and memory access. Reads from
diff --git a/test/unit_test/agent/test_retrieval_document_ids.py b/test/unit_test/agent/test_retrieval_document_ids.py
new file mode 100644
index 0000000000..7e8964acea
--- /dev/null
+++ b/test/unit_test/agent/test_retrieval_document_ids.py
@@ -0,0 +1,33 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+from types import SimpleNamespace
+
+from agent.tools.retrieval import Retrieval
+
+
+class TestNormalizeDocumentIds:
+ def test_empty_values(self):
+ assert Retrieval._normalize_document_ids(None) == []
+ assert Retrieval._normalize_document_ids("") == []
+ assert Retrieval._normalize_document_ids([]) == []
+
+ def test_list(self):
+ assert Retrieval._normalize_document_ids(["a", "b"]) == ["a", "b"]
+ assert Retrieval._normalize_document_ids(["a", "", "b"]) == ["a", "b"]
+
+ def test_single_string(self):
+ assert Retrieval._normalize_document_ids("doc-1") == ["doc-1"]
+
+
+class TestResolveDocumentIds:
+ def test_prefers_kwargs(self):
+ tool = Retrieval.__new__(Retrieval)
+ tool._param = SimpleNamespace(document_ids="doc-config")
+ assert tool._resolve_document_ids(["doc-runtime"]) == ["doc-runtime"]
+
+ def test_falls_back_to_param(self):
+ tool = Retrieval.__new__(Retrieval)
+ tool._param = SimpleNamespace(document_ids=["doc-config"])
+ tool._canvas = SimpleNamespace(is_reff=lambda _exp: False)
+ assert tool._resolve_document_ids(None) == ["doc-config"]
diff --git a/web/src/interfaces/database/agent.ts b/web/src/interfaces/database/agent.ts
index 9be9bc43fd..b114b0b193 100644
--- a/web/src/interfaces/database/agent.ts
+++ b/web/src/interfaces/database/agent.ts
@@ -170,6 +170,7 @@ export interface IRetrievalForm {
rerank_id?: string;
tenant_rerank_id?: string;
dataset_ids?: string[];
+ document_ids?: string | string[];
}
export interface ICodeForm {
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index c54adb2907..eaee6a2204 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -3315,6 +3315,9 @@ This process aggregates variables from multiple branches into a single variable
switchPromptMessage:
'The prompt words will change. Please confirm whether you want to discard the existing prompt words?',
queryRequired: 'Query is required',
+ documentIds: 'Document IDs',
+ documentIdsTip:
+ 'Optional list of document IDs to restrict retrieval scope. Supports upstream variable references.',
queryTip: 'Select the variable you want to use',
agent: 'Agent',
addAgent: 'Add agent',
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index d2883f2a82..d7f458c4a1 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -2894,6 +2894,8 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
query: '查询变量',
queryRequired: '查询变量是必填项',
queryTip: '选择您想要使用的变量',
+ documentIds: '文档 ID 列表',
+ documentIdsTip: '可选,限制检索范围的文档 ID 列表,支持引用上游变量',
agent: '智能体',
addAgent: '添加智能体',
agentDescription: '构建具备推理、工具调用和多智能体协同的智能体组件。',
diff --git a/web/src/pages/agent/constant/index.tsx b/web/src/pages/agent/constant/index.tsx
index ec806fbb76..180e47f7ce 100644
--- a/web/src/pages/agent/constant/index.tsx
+++ b/web/src/pages/agent/constant/index.tsx
@@ -94,6 +94,7 @@ export const initialRetrievalValues = {
...initialKeywordsSimilarityWeightValue,
cross_languages: [],
retrieval_from: RetrievalFrom.Dataset,
+ document_ids: '',
outputs: {
formalized_content: {
type: 'string',
diff --git a/web/src/pages/agent/form/retrieval-form/next.tsx b/web/src/pages/agent/form/retrieval-form/next.tsx
index 481886d855..11fd2d99ee 100644
--- a/web/src/pages/agent/form/retrieval-form/next.tsx
+++ b/web/src/pages/agent/form/retrieval-form/next.tsx
@@ -55,6 +55,7 @@ export const RetrievalPartialSchema = {
memory_ids: z.array(z.string()).optional(),
retrieval_from: z.string(),
user_id: z.string().optional(),
+ document_ids: z.string().optional(),
};
export const FormSchema = z
@@ -133,6 +134,20 @@ export function useHideKnowledgeGraphField(form: UseFormReturn<any>) {
return retrievalFrom === RetrievalFrom.Memory;
}
+export function DocumentIdsFormField() {
+ const { t } = useTranslation();
+
+ return (
+ <RAGFlowFormItem
+ name="document_ids"
+ label={t('flow.documentIds')}
+ tooltip={t('flow.documentIdsTip')}
+ >
+ <PromptEditor multiLine={false} showToolbar={false}></PromptEditor>
+ </RAGFlowFormItem>
+ );
+}
+
function RetrievalForm({ node }: INextOperatorForm) {
const { t } = useTranslation();
const ownerTenantId = useOwnerTenantId();
@@ -175,6 +190,7 @@ function RetrievalForm({ node }: INextOperatorForm) {
<RAGFlowFormItem name="query" label={t('flow.query')}>
<PromptEditor></PromptEditor>
</RAGFlowFormItem>
+ <DocumentIdsFormField></DocumentIdsFormField>
<MemoryDatasetForm></MemoryDatasetForm>
<Collapse defaultOpen title={<div>{t('flow.advancedSettings')}</div>}>
<section className="space-y-5">
diff --git a/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx b/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
index 624102ec6d..8b1338bb6b 100644
--- a/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
+++ b/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
@@ -22,6 +22,7 @@ import { useOwnerTenantId } from '../../../context';
import { DescriptionField } from '../../components/description-field';
import { FormWrapper } from '../../components/form-wrapper';
import {
+ DocumentIdsFormField,
MemoryDatasetForm,
RetrievalPartialSchema,
useHideKnowledgeGraphField,
@@ -60,6 +61,7 @@ const RetrievalForm = () => {
<Form {...form}>
<FormWrapper>
<DescriptionField></DescriptionField>
+ <DocumentIdsFormField></DocumentIdsFormField>
<MemoryDatasetForm></MemoryDatasetForm>
<Collapse defaultOpen title={<div>{t('flow.advancedSettings')}</div>}>
<FormContainer>