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
fix(agent): accept user_id node param on the Retrieval agent tool (#19090)
euvrea41d0d3a94eb
diff --git a/internal/agent/component/retrieval_params_test.go b/internal/agent/component/retrieval_params_test.goindex 96ebb0ecbc..f1736e1f96 100644--- a/internal/agent/component/retrieval_params_test.go+++ b/internal/agent/component/retrieval_params_test.go@@ -114,6 +114,37 @@ func TestRetrievalComponentForwardsAdvancedNodeParams(t *testing.T) {}}+func TestRetrievalComponentForwardsUserIDNodeParam(t *testing.T) {+ previous := agenttool.GetMemoryRetrievalService()+ recorder := &retrievalRequestRecorder{}+ agenttool.SetMemoryRetrievalService(recorder)+ t.Cleanup(func() { agenttool.SetMemoryRetrievalService(previous) })++ component, err := newRetrievalComponent(map[string]any{+ "memory_ids": []any{"memory-1"},+ "retrieval_from": "memory",+ "user_id": "user-7",+ })+ if err != nil {+ t.Fatalf("newRetrievalComponent: %v", err)+ }++ merged := component.(*retrievalComponent).applyDefaults(nil)+ if got := merged["user_id"]; got != "user-7" {+ t.Errorf("user_id = %#v, want user-7", got)+ }++ if _, err = component.Invoke(t.Context(), nil, map[string]any{"query": "remember"}); err != nil {+ t.Fatalf("Invoke: %v", err)+ }+ if recorder.request.UserID != "user-7" {+ t.Errorf("UserID = %q, want user-7", recorder.request.UserID)+ }+ if recorder.request.RetrievalFrom != "memory" {+ t.Errorf("RetrievalFrom = %q, want memory", recorder.request.RetrievalFrom)+ }+}+func TestRetrievalComponentForwardsExplicitZeroSimilarityParams(t *testing.T) {previous := agenttool.GetRetrievalService()recorder := &retrievalRequestRecorder{}diff --git a/internal/agent/component/universe_a_wrappers.go b/internal/agent/component/universe_a_wrappers.goindex bdfc87d12c..999916c3b1 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+ UserID stringTopN intTopK intSimilarityThreshold *float64@@ -108,6 +109,9 @@ func parseRetrievalParams(params map[string]any) retrievalParams {out.KbIDs = append(out.KbIDs, v...)}out.MemoryIDs = toStringSlice(params["memory_ids"])+ if v, ok := params["user_id"].(string); ok {+ out.UserID = v+ }if v, ok := params["top_n"]; ok {out.TopN = toIntParam(v)}@@ -290,6 +294,9 @@ 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["user_id"]; !ok && c.params.UserID != "" {+ out["user_id"] = c.params.UserID+ }if _, ok := out["cross_languages"]; !ok && len(c.params.CrossLanguages) > 0 {out["cross_languages"] = append([]string(nil), c.params.CrossLanguages...)}diff --git a/internal/agent/retrievalbridge/memory.go b/internal/agent/retrievalbridge/memory.goindex 503805957d..fb57f78e90 100644--- a/internal/agent/retrievalbridge/memory.go+++ b/internal/agent/retrievalbridge/memory.go@@ -59,10 +59,14 @@ func (a *MemoryAdapter) Search(if req.KeywordsSimilarityWeight != nil {keywordWeight = *req.KeywordsSimilarityWeight}+ filter := map[string]any{"memory_id": memoryIDs}+ if user := strings.TrimSpace(req.UserID); user != "" {+ filter["user_id"] = user+ }messages, _, err := a.svc.SearchMessage(ctx,req.TenantID,- map[string]any{"memory_id": memoryIDs},+ filter,map[string]any{"query": req.Query,"similarity_threshold": req.SimilarityThreshold,diff --git a/internal/agent/tool/registry.go b/internal/agent/tool/registry.goindex 6de113cd81..7781eadcaa 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":+ "inputs", "outputs", "user_id":default:return nil, fmt.Errorf("agent tool: retrieval tool does not accept node-level param %s", key)}@@ -423,6 +423,9 @@ func buildRetrievalTool(params map[string]any) (einotool.BaseTool, error) {} else if ok {defaults.MemoryIDs = ids}+ if v, ok := stringParam(params, "user_id"); ok {+ defaults.UserID = v+ }if v, ok := intParam(params, "top_n"); ok {defaults.TopN = v}diff --git a/internal/agent/tool/retrieval.go b/internal/agent/tool/retrieval.goindex c47c4ab2c3..f4d3b2bb51 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"`+ UserID string `json:"user_id,omitempty"`TopN int `json:"top_n,omitempty"`RerankCandidatesCount int `json:"rerank_candidates_count,omitempty"`TopK int `json:"top_k,omitempty"`@@ -151,6 +152,11 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON stringreturn "", err}args.Query = resolvedQuery+ resolvedUserID, err := resolveRetrievalUserID(ctx, args.UserID)+ if err != nil {+ return "", err+ }+ args.UserID = resolvedUserIDcommon.Debug("agent retrieval tool: parsed arguments",zap.String("query", args.Query),zap.Strings("dataset_ids", args.DatasetIDs),@@ -211,6 +217,7 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON stringTOCEnhance: args.TOCEnhance,MetaDataFilter: cloneStringAnyMap(args.MetaDataFilter),RetrievalFrom: args.RetrievalFrom,+ UserID: args.UserID,TenantID: retrievalTenantID(ctx),}@@ -291,6 +298,9 @@ func (r *RetrievalTool) mergeDefaults(args retrievalArgs) retrievalArgs {if args.EmptyResponse == "" {args.EmptyResponse = r.defaults.EmptyResponse}+ if args.UserID == "" {+ args.UserID = r.defaults.UserID+ }if args.RerankID == "" {args.RerankID = r.defaults.RerankID}@@ -337,6 +347,54 @@ func resolveRetrievalQuery(ctx context.Context, query string) (string, error) {return resolved, nil}+// resolveRetrievalUserID resolves the memory user_id filter. Mirrors Python's+// Retrieval._retrieve_memory: a variable reference — `{sys.user_id}` template+// or bare `sys.*` / `env.*` / `component@param` form — is looked up in the+// canvas state; anything else is a literal user id and passes through.+//+// Two deliberate divergences from Python, which resolves only the fully+// braced form and passes bare refs through literally (agent/tools/retrieval.py+// `_retrieve_memory`):+//+// - bare ref forms are resolved too, so a canvas storing `sys.user_id`+// unbraced still filters per user; as a corollary, a literal user id+// that collides with a live state variable name is substituted (RAGFlow+// user ids are UUID-like and never look like refs);+// - an unset bare `sys.*` / `env.*` ref resolves to "" (no user filter)+// instead of the literal ref string, which could never match a real user+// id and would silently empty the result. Bare `component@param` refs+// keep the literal fallback because an "@" in the value is ambiguous+// with an email-style literal user id.+func resolveRetrievalUserID(ctx context.Context, userID string) (string, error) {+ trimmed := strings.TrimSpace(userID)+ if trimmed == "" {+ return "", nil+ }+ state, _, err := runtime.GetStateFromContext[*runtime.CanvasState](ctx)+ if err != nil || state == nil {+ return trimmed, nil+ }+ if strings.ContainsAny(trimmed, "{}") {+ resolved, err := runtime.ResolveTemplateAuto(trimmed, state)+ if err != nil {+ return "", fmt.Errorf("retrieval: resolve user_id variable: %w", err)+ }+ return strings.TrimSpace(resolved), nil+ }+ if value, getErr := state.GetVar(trimmed); getErr == nil && value != nil {+ if text, ok := value.(string); ok {+ return text, nil+ }+ return fmt.Sprintf("%v", value), nil+ }+ if strings.HasPrefix(trimmed, "sys.") || strings.HasPrefix(trimmed, "env.") {+ // An unset sys./env. ref cannot be a literal user id; treat it as+ // "no user filter" per the RetrievalRequest.UserID contract.+ return "", nil+ }+ return trimmed, nil+}+func resolveRetrievalDatasetIDs(ctx context.Context, datasetIDs []string) ([]string, error) {state, _, err := runtime.GetStateFromContext[*runtime.CanvasState](ctx)if err != nil || state == nil {diff --git a/internal/agent/tool/retrieval_service.go b/internal/agent/tool/retrieval_service.goindex 85c16f0401..005591a338 100644--- a/internal/agent/tool/retrieval_service.go+++ b/internal/agent/tool/retrieval_service.go@@ -70,6 +70,11 @@ type RetrievalRequest struct {// CanvasState.Sys["user_id"] when empty (set by the Begin component at// internal/agent/component/begin.go:82).TenantID string+ // UserID optionally filters memory messages by the user_id they were+ // recorded with (the Retrieval node's "User ID" field, e.g. resolved+ // from sys.user_id). Empty = no user filter. Only meaningful for+ // retrieval_from=memory.+ UserID string}// RetrievalService is the knowledge-base search interface used by the tool.diff --git a/internal/agent/tool/retrieval_test.go b/internal/agent/tool/retrieval_test.goindex 3384d14194..1a897a742d 100644--- a/internal/agent/tool/retrieval_test.go+++ b/internal/agent/tool/retrieval_test.go@@ -317,6 +317,121 @@ func TestRetrieval_RoutesMemoryRequests(t *testing.T) {}}+func TestRetrieval_ParsesUserIDNodeParam(t *testing.T) {+ t.Parallel()++ // A memory-mode Retrieval node declared as an Agent tool carries user_id+ // in its node-level params; building the tool must accept it.+ built, err := BuildByName("retrieval", map[string]any{+ "retrieval_from": "memory",+ "memory_ids": []any{"memory-1"},+ "user_id": "sys.user_id",+ })+ if err != nil {+ t.Fatalf("BuildByName(retrieval) with user_id: %v", err)+ }+ rt, ok := built.(*RetrievalTool)+ if !ok {+ t.Fatalf("BuildByName(retrieval) returned %T, want *RetrievalTool", built)+ }+ if rt.defaults.UserID != "sys.user_id" {+ t.Fatalf("UserID = %q, want sys.user_id", rt.defaults.UserID)+ }+}++func TestRetrieval_RoutesMemoryRequestsWithUserFilter(t *testing.T) {+ previous := GetMemoryRetrievalService()+ memoryService := &capturingRetrievalService{}+ SetMemoryRetrievalService(memoryService)+ t.Cleanup(func() { SetMemoryRetrievalService(previous) })++ state := runtime.NewCanvasState("run-1", "session-1")+ state.Sys["user_id"] = "user-42"+ ctx := runtime.WithState(t.Context(), state)++ rt := NewRetrievalToolWithDefaults(retrievalArgs{+ MemoryIDs: []string{"memory-1"},+ UserID: "{sys.user_id}",+ })+ if _, err := rt.InvokableRun(ctx, `{"query":"remember this"}`); err != nil {+ t.Fatalf("InvokableRun: %v", err)+ }+ if memoryService.req.UserID != "user-42" {+ t.Fatalf("UserID = %q, want user-42 resolved from {sys.user_id}", memoryService.req.UserID)+ }++ // The bare `sys.user_id` form (no braces) resolves against the canvas+ // state as well.+ bare := NewRetrievalToolWithDefaults(retrievalArgs{+ MemoryIDs: []string{"memory-1"},+ UserID: "sys.user_id",+ })+ if _, err := bare.InvokableRun(ctx, `{"query":"remember this"}`); err != nil {+ t.Fatalf("InvokableRun(bare ref): %v", err)+ }+ if memoryService.req.UserID != "user-42" {+ t.Fatalf("UserID = %q, want user-42 resolved from bare sys.user_id", memoryService.req.UserID)+ }+}++func TestRetrieval_UnsetBareUserRefYieldsNoFilter(t *testing.T) {+ previous := GetMemoryRetrievalService()+ memoryService := &capturingRetrievalService{}+ SetMemoryRetrievalService(memoryService)+ t.Cleanup(func() { SetMemoryRetrievalService(previous) })++ // sys.user_id is deliberately left unset: an unresolvable bare ref must+ // mean "no user filter" (UserID == ""), not a literal "sys.user_id"+ // filter that matches no user.+ state := runtime.NewCanvasState("run-1", "session-1")+ ctx := runtime.WithState(t.Context(), state)++ rt := NewRetrievalToolWithDefaults(retrievalArgs{+ MemoryIDs: []string{"memory-1"},+ UserID: "sys.user_id",+ })+ if _, err := rt.InvokableRun(ctx, `{"query":"remember this"}`); err != nil {+ t.Fatalf("InvokableRun: %v", err)+ }+ if memoryService.req.UserID != "" {+ t.Fatalf("UserID = %q, want empty (no user filter) for unset sys.user_id", memoryService.req.UserID)+ }++ // The braced form of an unset ref keeps the loud failure — Python's+ // canvas.get_variable_value raises KeyError on missing globals.+ braced := NewRetrievalToolWithDefaults(retrievalArgs{+ MemoryIDs: []string{"memory-1"},+ UserID: "{sys.user_id}",+ })+ if _, err := braced.InvokableRun(ctx, `{"query":"remember this"}`); err == nil {+ t.Fatal("InvokableRun(braced unset ref): expected error, got nil")+ }+}++func TestRetrieval_LiteralUserIDPassesThrough(t *testing.T) {+ previous := GetMemoryRetrievalService()+ memoryService := &capturingRetrievalService{}+ SetMemoryRetrievalService(memoryService)+ t.Cleanup(func() { SetMemoryRetrievalService(previous) })++ // sys.user_id is set to prove a non-ref literal is never substituted+ // from state.+ state := runtime.NewCanvasState("run-1", "session-1")+ state.Sys["user_id"] = "user-42"+ ctx := runtime.WithState(t.Context(), state)++ rt := NewRetrievalToolWithDefaults(retrievalArgs{+ MemoryIDs: []string{"memory-1"},+ UserID: "user-77",+ })+ if _, err := rt.InvokableRun(ctx, `{"query":"remember this"}`); err != nil {+ t.Fatalf("InvokableRun: %v", err)+ }+ if memoryService.req.UserID != "user-77" {+ t.Fatalf("UserID = %q, want literal user-77", memoryService.req.UserID)+ }+}+func TestRetrieval_ResolvesCanvasVariables(t *testing.T) {state := runtime.NewCanvasState("run-1", "session-1")state.SetVar("source", "ids", []any{"kb-1", "kb-2"})