Skip to content

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

fix(agent): preserve loop variables across interrupted resumes (#20283)

Sbaaoui Idriss322aba7d40c7
diff --git a/internal/agent/canvas/loop_subgraph.go b/internal/agent/canvas/loop_subgraph.go
index 0398c29bad..cb22da2b9b 100644
--- a/internal/agent/canvas/loop_subgraph.go
+++ b/internal/agent/canvas/loop_subgraph.go
@@ -36,6 +36,7 @@ package canvas
import (
"context"
+ "encoding/json"
"fmt"
"slices"
"strings"
@@ -53,6 +54,8 @@ type loopExpansion struct {
ShouldQuit workflowx.LoopCondition[map[string]any]
MaxIters int
Members map[string]bool // cpn_ids consumed by the sub-graph; caller skips these in the main pass.
+ snapshot func(context.Context) ([]byte, error)
+ restore func(context.Context, []byte) error
}
// buildLoopExpansion constructs the sub-workflow + termination condition
@@ -107,6 +110,12 @@ func buildLoopExpansion(ctx context.Context, c *Canvas, loopID string) (*loopExp
ShouldQuit: shouldQuit,
MaxIters: maxIters,
Members: members,
+ snapshot: func(ctx context.Context) ([]byte, error) {
+ return snapshotLoopVariables(ctx, loopID)
+ },
+ restore: func(ctx context.Context, data []byte) error {
+ return restoreLoopVariables(ctx, loopID, data)
+ },
}, nil
}
@@ -339,6 +348,29 @@ func buildSubWorkflow(
return sub, nil
}
+func snapshotLoopVariables(ctx context.Context, loopID string) ([]byte, error) {
+ state, err := GetStateFromContext(ctx)
+ if err != nil || state == nil {
+ return nil, err
+ }
+ return json.Marshal(state.Snapshot()[loopID])
+}
+
+func restoreLoopVariables(ctx context.Context, loopID string, data []byte) error {
+ state, err := GetStateFromContext(ctx)
+ if err != nil || state == nil {
+ return err
+ }
+ var values map[string]any
+ if err := json.Unmarshal(data, &values); err != nil {
+ return err
+ }
+ for name, value := range values {
+ state.SetVar(loopID, name, value)
+ }
+ return nil
+}
+
func subCanvasForMembers(c *Canvas, members map[string]bool) *Canvas {
if c == nil {
return nil
diff --git a/internal/agent/canvas/scheduler.go b/internal/agent/canvas/scheduler.go
index 80003f176f..2b17c06021 100644
--- a/internal/agent/canvas/scheduler.go
+++ b/internal/agent/canvas/scheduler.go
@@ -466,6 +466,7 @@ func BuildWorkflow(ctx context.Context, c *Canvas) (*compose.Workflow[map[string
}
var opts []workflowx.LoopOption
opts = append(opts, workflowx.WithLoopStream(workflowx.LoopStreamEveryIteration))
+ opts = append(opts, workflowx.WithLoopStatePersistence(exp.snapshot, exp.restore))
opts = append(opts, workflowx.WithLoopLifecycleHooks(
func(ctx context.Context, input any) {
state, _ := runtime.GetStateFromContext(ctx)
diff --git a/internal/agent/workflowx/loop.go b/internal/agent/workflowx/loop.go
index 2019584ce3..8d78b54b81 100644
--- a/internal/agent/workflowx/loop.go
+++ b/internal/agent/workflowx/loop.go
@@ -150,6 +150,8 @@ type loopOptions struct {
enableSubCheckpoint bool
onStart func(context.Context, any)
onFinish func(context.Context, error)
+ snapshotState func(context.Context) ([]byte, error)
+ restoreState func(context.Context, []byte) error
}
// WithLoopMaxIterations caps the loop at n iterations. The cap is checked
@@ -186,6 +188,15 @@ func WithLoopLifecycleHooks(onStart func(context.Context, any), onFinish func(co
}
}
+// WithLoopStatePersistence preserves caller-owned state across an interrupted
+// loop execution.
+func WithLoopStatePersistence(snapshot func(context.Context) ([]byte, error), restore func(context.Context, []byte) error) LoopOption {
+ return func(o *loopOptions) {
+ o.snapshotState = snapshot
+ o.restoreState = restore
+ }
+}
+
// WithLoopRunOptions appends run options to every nested sub-workflow
// Invoke / Stream call. Use this to forward run-level options such as
// per-iteration callbacks or extra callbacks.
@@ -281,6 +292,7 @@ type loopInterruptState struct {
SubCheckpointID string `json:"sub_checkpoint_id"`
SubCheckpoints map[string][]byte `json:"sub_checkpoints,omitempty"`
ReplayChunks [][]byte `json:"replay_chunks,omitempty"`
+ RuntimeState []byte `json:"runtime_state,omitempty"`
}
// AddLoopNode appends a loop node to the outer workflow `wf`. The
@@ -373,6 +385,7 @@ type loopSnapshot struct {
subCheckID string
subCheckpoints map[string][]byte
replayChunks [][]byte
+ runtimeState []byte
}
// loadLoopSnapshot reads the loop state from the context if the
@@ -407,6 +420,7 @@ func loadLoopSnapshot[T any](ctx context.Context, defaultMode LoopStreamMode) (l
subCheckID: st.SubCheckpointID,
subCheckpoints: cloneCheckpointMap(st.SubCheckpoints),
replayChunks: cloneByteSlices(st.ReplayChunks),
+ runtimeState: append([]byte(nil), st.RuntimeState...),
}, nil
}
@@ -419,9 +433,31 @@ func encodeState(s loopSnapshot) ([]byte, error) {
SubCheckpointID: s.subCheckID,
SubCheckpoints: cloneCheckpointMap(s.subCheckpoints),
ReplayChunks: cloneByteSlices(s.replayChunks),
+ RuntimeState: append([]byte(nil), s.runtimeState...),
})
}
+func encodeInterruptState(ctx context.Context, options *loopOptions, snap loopSnapshot) ([]byte, error) {
+ if options.snapshotState != nil {
+ state, err := options.snapshotState(ctx)
+ if err != nil {
+ return nil, fmt.Errorf("workflowx: snapshot loop state: %w", err)
+ }
+ snap.runtimeState = state
+ }
+ return encodeState(snap)
+}
+
+func restoreInterruptState(ctx context.Context, options *loopOptions, snap loopSnapshot) error {
+ if len(snap.runtimeState) == 0 || options.restoreState == nil {
+ return nil
+ }
+ if err := options.restoreState(ctx, snap.runtimeState); err != nil {
+ return fmt.Errorf("%w: restore runtime state: %w", ErrLoopResumeStateInvalid, err)
+ }
+ return nil
+}
+
// runLoopInvoke executes the loop on the invoke path. It is the
// body of the loop lambda's Invoke handler. See the package doc and
// plan §"Invoke path" for the documented state machine.
@@ -432,6 +468,9 @@ func runLoopInvoke[T any](ctx context.Context, nodeKey string, sub compose.Runna
if err != nil {
return zero, err
}
+ if err := restoreInterruptState(ctx, options, snap); err != nil {
+ return zero, err
+ }
// Resolve the starting input. On a fresh run it is the outer
// lambda input. On a resume it is the JSON blob we persisted.
@@ -475,7 +514,7 @@ func runLoopInvoke[T any](ctx context.Context, nodeKey string, sub compose.Runna
// resume via the standard eino
// ResumeWithData / BatchResumeWithData
// primitives.
- state, mErr := encodeState(loopSnapshot{
+ state, mErr := encodeInterruptState(ctx, options, loopSnapshot{
startIteration: iteration,
current: currentJSON,
streamMode: snap.streamMode,
@@ -564,6 +603,9 @@ func runLoopStream[T any](
if err != nil {
return nil, err
}
+ if err := restoreInterruptState(ctx, options, snap); err != nil {
+ return nil, err
+ }
var current T
if snap.startIteration == 1 && snap.current == nil {
@@ -626,7 +668,7 @@ func runLoopStream[T any](
reader, serr := sub.Stream(subCtx, current, withSubCheckpoint(options.runOpts, subCheckID, options.enableSubCheckpoint)...)
if serr != nil {
if isInterruptError(serr) {
- state, mErr := encodeState(loopSnapshot{
+ state, mErr := encodeInterruptState(ctx, options, loopSnapshot{
startIteration: iteration,
current: currentJSON,
streamMode: streamMode,
@@ -653,7 +695,7 @@ func runLoopStream[T any](
collected, cerr := readAllStream(reader)
if cerr != nil {
if isInterruptError(cerr) {
- state, mErr := encodeState(loopSnapshot{
+ state, mErr := encodeInterruptState(ctx, options, loopSnapshot{
startIteration: iteration,
current: currentJSON,
streamMode: streamMode,
diff --git a/internal/service/agent_run_e2e_test.go b/internal/service/agent_run_e2e_test.go
index 99fab5090a..f2c47c1375 100644
--- a/internal/service/agent_run_e2e_test.go
+++ b/internal/service/agent_run_e2e_test.go
@@ -1002,6 +1002,13 @@ func TestRunAgent_AllFixture_LoopInterruptResume(t *testing.T) {
if err := json.Unmarshal(raw, &dsl); err != nil {
t.Fatalf("parse all.json: %v", err)
}
+ components := dsl["components"].(map[string]any)
+ loopParams := components["Loop:InputUntil1"].(map[string]any)["obj"].(map[string]any)["params"].(map[string]any)
+ loopParams["loop_variables"] = []any{
+ map[string]any{"variable": "vlaue", "input_mode": "constant", "value": "1", "type": "string"},
+ }
+ messageParams := components["Message:LoopDone"].(map[string]any)["obj"].(map[string]any)["params"].(map[string]any)
+ messageParams["content"] = []any{"loop={Loop:InputUntil1@vlaue}; input={UserFillUp:LoopInput@value}"}
makeCanvasWithDSL(t, "canvas-all", "user-1", "tenant-1", "v-all", dsl)
tracker, mr := newRunTrackerForTest(t, 30*24*time.Hour)
@@ -1090,11 +1097,8 @@ func TestRunAgent_AllFixture_LoopInterruptResume(t *testing.T) {
if len(messages2) != 1 {
t.Fatalf("run 3: expected 1 message event after resume, got %d", len(messages2))
}
- if !strings.Contains(messages2[0].Content, "循环结束") {
- t.Errorf("run 2: Content = %q, want substring %q", messages2[0].Content, "循环结束")
- }
- if !strings.Contains(messages2[0].Content, "1") {
- t.Errorf("run 2: Content = %q, want substring %q", messages2[0].Content, "1")
+ if messages2[0].Content != "loop=1; input=1" {
+ t.Errorf("run 3: Content = %q, want %q", messages2[0].Content, "loop=1; input=1")
}
}