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): make single-component debug match real-run state (#20807)
ciel1d151d10f88a
diff --git a/internal/agent/runtime/state.go b/internal/agent/runtime/state.goindex 1e43468bb7..a95e7de0b3 100644--- a/internal/agent/runtime/state.go+++ b/internal/agent/runtime/state.go@@ -114,6 +114,30 @@ func (s *CanvasState) EnsureSysDate() {s.Sys["date"] = time.Now().Format("2006-01-02 15:04:05")}+// SeedIdentity writes the trusted caller identity into Sys. Both the normal+// run bootstrap (service layer) and the single-component debug endpoint+// (handler layer) call it so components depending on sys.user_id /+// sys.tenant_id — in particular the retrieval authorization check — see the+// same identity contract. Empty values are skipped so a missing caller+// tenant does not materialize an empty-string key. The caller owns the+// source of the values; request-supplied fields must never reach here.+func (s *CanvasState) SeedIdentity(userID, tenantID string) {+ if s == nil {+ return+ }+ s.mu.Lock()+ defer s.mu.Unlock()+ if s.Sys == nil {+ s.Sys = make(map[string]any)+ }+ if userID != "" {+ s.Sys["user_id"] = userID+ }+ if tenantID != "" {+ s.Sys["tenant_id"] = tenantID+ }+}+// init registers CanvasState with eino's internal type registry so// that eino's StatePre/Post handler chain (which uses its own// InternalSerializer, NOT stdlib encoding/json) recognises thediff --git a/internal/agent/runtime/state_test.go b/internal/agent/runtime/state_test.goindex 5546579b8b..6227dd34f5 100644--- a/internal/agent/runtime/state_test.go+++ b/internal/agent/runtime/state_test.go@@ -342,6 +342,38 @@ func TestCanvasState_EnsureSysDate(t *testing.T) {}}+func TestCanvasState_SeedIdentity(t *testing.T) {+ t.Parallel()++ state := NewCanvasState("r", "t")+ state.SeedIdentity("user-1", "tenant-1")+ if got := state.Sys["user_id"]; got != "user-1" {+ t.Fatalf("sys.user_id = %v, want user-1", got)+ }+ if got := state.Sys["tenant_id"]; got != "tenant-1" {+ t.Fatalf("sys.tenant_id = %v, want tenant-1", got)+ }++ // Empty values must not materialize empty-string keys.+ state = NewCanvasState("r", "t")+ state.SeedIdentity("", "")+ if _, ok := state.Sys["user_id"]; ok {+ t.Fatal("empty user_id should not be written")+ }+ if _, ok := state.Sys["tenant_id"]; ok {+ t.Fatal("empty tenant_id should not be written")+ }++ // A second call overwrites the previously seeded identity.+ state.SeedIdentity("user-2", "tenant-2")+ if got := state.Sys["user_id"]; got != "user-2" {+ t.Fatalf("sys.user_id = %v, want user-2", got)+ }+ if got := state.Sys["tenant_id"]; got != "tenant-2" {+ t.Fatalf("sys.tenant_id = %v, want tenant-2", got)+ }+}+func TestCanvasState_SetRetrievalReferencesMergesCalls(t *testing.T) {t.Parallel()diff --git a/internal/handler/agent_component.go b/internal/handler/agent_component.goindex 8c9fb2dd67..fab237ce67 100644--- a/internal/handler/agent_component.go+++ b/internal/handler/agent_component.go@@ -203,16 +203,30 @@ func (h *AgentHandler) DebugComponent(c *gin.Context) {// debug works on a single component without standing up the// full canvas compile.//- // Seed state.Sys["tenant_id"] with the canvas owner so that- // components which resolve LLM credentials from the tenant- // tables (e.g. AgentComponent) can find the API key in single-- // component debug mode. Mirrors Python's @add_tenant_id_to_kwargs- // decorator for the debug endpoint.+ // Seed the authenticated caller identity (sys.user_id / sys.tenant_id)+ // through the same entry the run bootstrap uses, so components that+ // authorize against it (e.g. knowledge retrieval) and components that+ // resolve LLM credentials from the tenant tables (e.g. AgentComponent)+ // behave in single-component debug mode exactly as they do in a real+ // run. Mirrors Python's @add_tenant_id_to_kwargs decorator and keeps the+ // two paths from drifting. The request body must not override either key.+ //+ // Also seed cpnID@param inputs into state.Outputs so a single-component+ // debug can resolve the {{cpn@param}} references its prompt/template+ // declares (e.g. Agent reading an upstream Retrieval's+ // formalized_content) without running the upstream components. Split on+ // the first '@' because cpn IDs may contain ':' but never '@'; SetVar+ // nests any dotted tail the same way getVarLocked reads it back.debugState := canvas.NewCanvasState("debug-"+componentID, "debug-task")- debugState.Sys["tenant_id"] = user.ID+ debugState.SeedIdentity(user.ID, user.ID)for key, value := range inputs {- if strings.HasPrefix(key, "sys.") && key != "sys.tenant_id" {+ switch {+ case strings.HasPrefix(key, "sys.") && key != "sys.tenant_id" && key != "sys.user_id":debugState.Sys[strings.TrimPrefix(key, "sys.")] = value+ case strings.Contains(key, "@"):+ if idx := strings.Index(key, "@"); idx > 0 && idx < len(key)-1 {+ debugState.SetVar(key[:idx], key[idx+1:], value)+ }}}// Permission checks in Retrieval use the authenticated caller and thediff --git a/internal/handler/agent_component_test.go b/internal/handler/agent_component_test.goindex fb841e47a4..c48f6b8363 100644--- a/internal/handler/agent_component_test.go+++ b/internal/handler/agent_component_test.go@@ -338,8 +338,8 @@ func (s *sysEchoComponent) Invoke(ctx context.Context, _ *gorm.DB, _ map[string]return map[string]any{"query": state.Sys["query"],"tenant_id": state.Sys["tenant_id"],- "canvas_id": state.Sys["canvas_id"],"user_id": state.Sys["user_id"],+ "canvas_id": state.Sys["canvas_id"],}, nil}@@ -397,6 +397,161 @@ func TestDebugComponent_SeedsSysInputsIntoCanvasState(t *testing.T) {}}+// templateEchoComponent resolves a template from its params against the+// CanvasState carried on the invoke context. It pins the debug endpoint's+// cpn@param -> state.Outputs seeding: without it, ResolveTemplate returns+// "Can't find variable".+type templateEchoComponent struct{ template string }++func (c *templateEchoComponent) Invoke(ctx context.Context, _ *gorm.DB, _ map[string]any) (map[string]any, error) {+ state, err := agentruntime.GetStateFromContext(ctx)+ if err != nil {+ return nil, err+ }+ resolved, err := agentruntime.ResolveTemplate(c.template, state)+ if err != nil {+ return nil, err+ }+ return map[string]any{"content": resolved}, nil+}++// debugWithTemplate runs the DebugComponent endpoint against a Probe+// component whose params.template is `template`, and returns the decoded+// response data map.+func debugWithTemplate(t *testing.T, template, body string) map[string]interface{} {+ t.Helper()++ origFactory := agentruntime.DefaultFactory()+ agentruntime.SetDefaultFactory(func(name string, params map[string]any) (agentruntime.Component, error) {+ if name != "Probe" {+ return nil, errors.New("unexpected component name: " + name)+ }+ tpl, _ := params["template"].(string)+ return &templateEchoComponent{template: tpl}, nil+ })+ t.Cleanup(func() { agentruntime.SetDefaultFactory(origFactory) })++ cv := &entity.UserCanvas{+ ID: "c1",+ DSL: map[string]any{+ "components": map[string]any{+ "probe": map[string]any{+ "obj": map[string]any{+ "component_name": "Probe",+ "params": map[string]any{"template": template},+ },+ },+ },+ },+ }+ h := &AgentHandler{loader: &fakeCanvasLoader{canvas: cv}}++ c, w := componentCtx(t, "POST", "/api/v1/agents/c1/components/probe/debug", body)+ c.Params = gin.Params{+ {Key: "canvas_id", Value: "c1"},+ {Key: "component_id", Value: "probe"},+ }+ h.DebugComponent(c)++ if w.Code != 200 {+ t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())+ }+ var env struct {+ Code int `json:"code"`+ Data map[string]interface{} `json:"data"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil {+ t.Fatalf("decode: %v (body=%s)", err, w.Body.String())+ }+ if env.Code != 0 {+ t.Fatalf("code = %d, want 0; body=%s", env.Code, w.Body.String())+ }+ return env.Data+}++func TestDebugComponent_SeedsRefInputsIntoCanvasState(t *testing.T) {+ data := debugWithTemplate(t,+ "{{Retrieval:FewLinesCry@formalized_content}}",+ `{"params":{"Retrieval:FewLinesCry@formalized_content":{"value":"doc body"}}}`,+ )+ if data["content"] != "doc body" {+ t.Fatalf("data.content = %v, want 'doc body'", data["content"])+ }+}++func TestDebugComponent_SeedsDottedRefInputsIntoCanvasState(t *testing.T) {+ data := debugWithTemplate(t,+ "{{Retrieval:[email protected]}}",+ `{"params":{"Retrieval:[email protected]":{"value":"nested hit"}}}`,+ )+ if data["content"] != "nested hit" {+ t.Fatalf("data.content = %v, want 'nested hit'", data["content"])+ }+}++func TestDebugComponent_MalformedRefKeyIsIgnored(t *testing.T) {+ data := debugWithTemplate(t,+ "{{ok@ref}}",+ `{"params":{"@leading":{"value":"x"},"trailing@":{"value":"y"},"ok@ref":{"value":"z"}}}`,+ )+ if data["content"] != "z" {+ t.Fatalf("data.content = %v, want 'z'", data["content"])+ }+}++func TestDebugComponent_SeedsUserIDIntoCanvasState(t *testing.T) {+ origFactory := agentruntime.DefaultFactory()+ agentruntime.SetDefaultFactory(func(name string, _ map[string]any) (agentruntime.Component, error) {+ if name != "Probe" {+ return nil, errors.New("unexpected component name: " + name)+ }+ return &sysEchoComponent{}, nil+ })+ t.Cleanup(func() { agentruntime.SetDefaultFactory(origFactory) })++ cv := &entity.UserCanvas{+ ID: "c1",+ DSL: map[string]any{+ "components": map[string]any{+ "probe": map[string]any{+ "obj": map[string]any{+ "component_name": "Probe",+ "params": map[string]any{},+ },+ },+ },+ },+ }+ h := &AgentHandler{loader: &fakeCanvasLoader{canvas: cv}}++ // The body attempts to spoof sys.user_id; the authenticated caller+ // identity must win so retrieval authorization cannot be bypassed.+ body := `{"params":{"sys.user_id":{"value":"attacker-user"}}}`+ c, w := componentCtx(t, "POST", "/api/v1/agents/c1/components/probe/debug", body)+ c.Params = gin.Params{+ {Key: "canvas_id", Value: "c1"},+ {Key: "component_id", Value: "probe"},+ }+ h.DebugComponent(c)++ if w.Code != 200 {+ t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())+ }+ var env struct {+ Code int `json:"code"`+ Data map[string]interface{} `json:"data"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil {+ t.Fatalf("decode: %v (body=%s)", err, w.Body.String())+ }+ if env.Data["user_id"] != "u-1" {+ t.Fatalf("data.user_id = %v, want u-1", env.Data["user_id"])+ }+ if env.Data["tenant_id"] != "u-1" {+ t.Fatalf("data.tenant_id = %v, want u-1", env.Data["tenant_id"])+ }+}+func TestDebugComponent_RejectsSysTenantIDOverride(t *testing.T) {origFactory := agentruntime.DefaultFactory()agentruntime.SetDefaultFactory(func(name string, _ map[string]any) (agentruntime.Component, error) {diff --git a/internal/service/agent.go b/internal/service/agent.goindex 90ba841412..7e1944a5f4 100644--- a/internal/service/agent.go+++ b/internal/service/agent.go@@ -2127,18 +2127,17 @@ func (s *AgentService) buildRunFunc(canvasID string, versionRow *entity.UserCanvstate.Sys["query"] = querystate.AppendCurrentUser(query)state.AppendSysHistory("user: " + renderUserHistoryValue(query))- if uid, ok := root["user_id"].(string); ok && uid != "" {- state.Sys["user_id"] = uid- }+ // Trusted caller identity is seeded through the same entry the debug+ // endpoint uses, so both paths agree on sys.user_id / sys.tenant_id.+ seedUserID, _ := root["user_id"].(string)+ seedTenantID, _ := root["tenant_id"].(string)+ state.SeedIdentity(seedUserID, seedTenantID)if canvasID != "" {state.Sys["canvas_id"] = canvasID}if sessionID != "" {state.Sys["session_id"] = sessionID}- if tid, ok := root["tenant_id"].(string); ok && tid != "" {- state.Sys["tenant_id"] = tid- }if rawFiles, ok := root["files"].([]map[string]interface{}); ok && len(rawFiles) > 0 {// Only used for ParseAgentUploads (read-only); nil DocRemover means// this FileService MUST NOT be used for DeleteFiles.