Skip to content

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

fix(agentic-rag): make the finalize and claims budgets configurable (#21879)

CCLUCKYb09efb780b41
diff --git a/internal/agentic_rag/agent.go b/internal/agentic_rag/agent.go
index ab70f87260..776d99635e 100644
--- a/internal/agentic_rag/agent.go
+++ b/internal/agentic_rag/agent.go
@@ -21,6 +21,7 @@ import (
"errors"
"fmt"
"io"
+ "os"
"regexp"
"strings"
"sync"
@@ -860,7 +861,12 @@ func emit(
// expired mid-investigation, so inheriting that deadline would guarantee its
// failure — q268 shipped a 60-char narration sentence because the final
// synthesis call was itself killed by the budget that had just run out.
-const finalizeTimeout = 90 * time.Second
+//
+// A local LLM over a large evidence block can legitimately need more than the
+// default to produce its first token (#21829), so operators can raise the
+// budget with AGENTIC_FINALIZE_TIMEOUT (Go duration, e.g. "5m"); the default
+// stays 90s.
+var finalizeTimeout = durationFromEnv("AGENTIC_FINALIZE_TIMEOUT", 90*time.Second)
// finalizeEvidenceMaxRunes caps the evidence block handed to the synthesis
// call. Tool outputs accumulate 4KB each; without a cap a long investigation
@@ -877,8 +883,30 @@ const finalizeEvidenceMaxRunes = 40000
// claimAnswerTimeout bounds the claims path as a whole: an answer call over
// evidence that was already retrieved and, only if it produced an answer, its
// verification. Both are non-streaming and need a fraction of the loop's budget -
-// and a hung provider must not eat the turn.
-const claimAnswerTimeout = 90 * time.Second
+// and a hung provider must not eat the turn. AGENTIC_CLAIM_ANSWER_TIMEOUT
+// raises it for a provider that legitimately needs longer than the 90s
+// default to start answering (#21829).
+var claimAnswerTimeout = durationFromEnv("AGENTIC_CLAIM_ANSWER_TIMEOUT", 90*time.Second)
+
+// durationFromEnv parses one Go-duration environment variable, falling back to
+// the default when unset or malformed so a typo cannot zero out a budget.
+func durationFromEnv(name string, fallback time.Duration) time.Duration {
+ if raw := strings.TrimSpace(os.Getenv(name)); raw != "" {
+ if d, err := time.ParseDuration(raw); err == nil && d > 0 {
+ return d
+ }
+ // Package-level vars evaluate before main installs the logger, so
+ // WarnCtx would drop this warning on every startup path; stderr is
+ // the only channel that exists that early.
+ if common.Logger != nil {
+ common.WarnCtx(context.Background(), "agentic_rag: ignoring malformed duration override",
+ zap.String("env", name), zap.String("value", raw), zap.Duration("default", fallback))
+ } else {
+ fmt.Fprintf(os.Stderr, "agentic_rag: ignoring malformed duration override %s=%q, using default %s\n", name, raw, fallback)
+ }
+ }
+ return fallback
+}
// synthModelFor picks the model that answers without tools: the caller's
// dedicated synthesis instance when it supplied one, else the agent's own model.
diff --git a/internal/agentic_rag/agent_env_timeout_test.go b/internal/agentic_rag/agent_env_timeout_test.go
new file mode 100644
index 0000000000..a123471ecb
--- /dev/null
+++ b/internal/agentic_rag/agent_env_timeout_test.go
@@ -0,0 +1,81 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package agentic_rag
+
+import (
+ "io"
+ "os"
+ "strings"
+ "testing"
+ "time"
+
+ "ragflow/internal/common"
+)
+
+func TestDurationFromEnv(t *testing.T) {
+ t.Setenv("AGENTIC_TEST_TIMEOUT", "5m")
+ if got := durationFromEnv("AGENTIC_TEST_TIMEOUT", 90*time.Second); got != 5*time.Minute {
+ t.Fatalf("override = %s, want 5m", got)
+ }
+
+ for name, raw := range map[string]string{"unset": "", "malformed": "soon", "zero": "0s", "negative": "-1m"} {
+ t.Run(name, func(t *testing.T) {
+ t.Setenv("AGENTIC_TEST_TIMEOUT", raw)
+ if got := durationFromEnv("AGENTIC_TEST_TIMEOUT", 90*time.Second); got != 90*time.Second {
+ t.Fatalf("override %q = %s, want the 90s default", raw, got)
+ }
+ })
+ }
+
+ if finalizeTimeout <= 0 || claimAnswerTimeout <= 0 {
+ t.Fatalf("package budgets must stay positive: finalize=%s claim=%s", finalizeTimeout, claimAnswerTimeout)
+ }
+}
+
+// TestDurationFromEnvWarnsOnStderrBeforeLoggerInit verifies the malformed
+// override warning reaches stderr while the logger is still nil: the two
+// package budgets are parsed during package initialization, before the server
+// installs its logger, and WarnCtx returns without logging on a nil logger.
+func TestDurationFromEnvWarnsOnStderrBeforeLoggerInit(t *testing.T) {
+ t.Setenv("AGENTIC_TEST_TIMEOUT", "soon")
+ saved := common.Logger
+ common.Logger = nil
+ t.Cleanup(func() { common.Logger = saved })
+
+ r, w, err := os.Pipe()
+ if err != nil {
+ t.Fatalf("pipe: %v", err)
+ }
+ savedStderr := os.Stderr
+ os.Stderr = w
+ got := durationFromEnv("AGENTIC_TEST_TIMEOUT", 90*time.Second)
+ w.Close()
+ os.Stderr = savedStderr
+
+ if got != 90*time.Second {
+ t.Fatalf("override = %s, want the 90s default", got)
+ }
+ out, err := io.ReadAll(r)
+ if err != nil {
+ t.Fatalf("read captured stderr: %v", err)
+ }
+ for _, want := range []string{"AGENTIC_TEST_TIMEOUT", `"soon"`, "1m30s"} {
+ if !strings.Contains(string(out), want) {
+ t.Fatalf("stderr warning missing %s: %q", want, string(out))
+ }
+ }
+}