RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
feat(agent): support document_ids in retrieval node and tool (#16938)
天海蒼灆ebbdd5028a3a
diff --git a/agent/tools/retrieval.py b/agent/tools/retrieval.pyindex 1ab7a6522e..137dd9e48b 100644--- a/agent/tools/retrieval.py+++ b/agent/tools/retrieval.py@@ -16,6 +16,7 @@import asynciofrom functools import partialimport json+import loggingimport osimport refrom abc import ABC@@ -85,6 +86,7 @@ class RetrievalParam(ToolParamBase):self.cross_languages = []self.toc_enhance = Falseself.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.goindex 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 stringKbIDs []stringMemoryIDs []string+ DocumentIDs []stringUserID stringTopN intTopK 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]anyif _, 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.goindex 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.goindex 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 stringcommon.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 stringreturn "", err}args.DatasetIDs = resolvedDatasetIDs+ resolvedDocumentIDs, err := resolveRetrievalDocumentIDs(ctx, args.DocumentIDs)+ if err != nil {+ return "", err+ }+ args.DocumentIDs = resolvedDocumentIDsresolvedFilter, err := resolveRetrievalFilter(ctx, args.MetaDataFilter)if err != nil {return "", err@@ -217,6 +229,7 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON stringTOCEnhance: 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) ([]strreturn 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, nildiff --git a/internal/agent/tool/retrieval_service.go b/internal/agent/tool/retrieval_service.goindex 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]float64MetaDataFilter map[string]anyRetrievalFrom 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 fromdiff --git a/test/unit_test/agent/test_retrieval_document_ids.py b/test/unit_test/agent/test_retrieval_document_ids.pynew file mode 100644index 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.tsindex 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.tsindex 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 variableswitchPromptMessage:'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.tsindex d2883f2a82..d7f458c4a1 100644--- a/web/src/locales/zh.ts+++ b/web/src/locales/zh.ts@@ -2894,6 +2894,8 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 Rquery: '查询变量',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.tsxindex 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.tsxindex 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.tsxindex 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>