Skip to content

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

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.go
index 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 the
diff --git a/internal/agent/runtime/state_test.go b/internal/agent/runtime/state_test.go
index 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.go
index 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 the
diff --git a/internal/handler/agent_component_test.go b/internal/handler/agent_component_test.go
index 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.go
index 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.UserCanv
state.Sys["query"] = query
state.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.