Skip to content

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

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.go
index 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.go
index 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 string
KbIDs []string
MemoryIDs []string
+ UserID string
TopN int
TopK int
SimilarityThreshold *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]any
if _, 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.go
index 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.go
index 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.go
index 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 string
return "", err
}
args.Query = resolvedQuery
+ resolvedUserID, err := resolveRetrievalUserID(ctx, args.UserID)
+ if err != nil {
+ return "", err
+ }
+ args.UserID = resolvedUserID
common.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 string
TOCEnhance: 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.go
index 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.go
index 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"})