Skip to content

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

fix(api): honor dialog system prompt in reasoning-enabled chat (#18842)

SYED ALI ABBAS RAHIL82e4147b8341
diff --git a/api/db/services/dialog_service.py b/api/db/services/dialog_service.py
index 53a6223986..9e0fc05d05 100644
--- a/api/db/services/dialog_service.py
+++ b/api/db/services/dialog_service.py
@@ -1942,6 +1942,39 @@ async def gen_mindmap(question, kb_ids, tenant_id, search_config={}):
return mind_map.output
+def _render_reasoning_system_prompt(dialog, prompt_config: dict, kwargs: dict) -> str:
+ """Render the dialog-level system prompt for the reasoning agent path.
+
+ Mirrors the substitutions ``async_chat`` performs for the non-reasoning path
+ so that configured system prompts are honored when reasoning is enabled.
+ The ``{knowledge}`` placeholder is defaulted to an empty string because the
+ agentic graph supplies retrieved evidence through its own evidence block.
+ """
+ system = prompt_config.get("system", "")
+ if not system:
+ return ""
+
+ sys_date = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+ kwargs["date"] = sys_date
+
+ param_keys = [p["key"] for p in prompt_config.get("parameters", [])]
+ if dialog.kb_ids and "knowledge" not in param_keys and "{knowledge}" in system:
+ param_keys.append("knowledge")
+ kwargs.setdefault("knowledge", "")
+
+ for p in prompt_config.get("parameters", []):
+ if p["key"] == "knowledge":
+ continue
+ if p["key"] not in kwargs and not p["optional"]:
+ raise KeyError("Miss parameter: " + p["key"])
+ if p["key"] not in kwargs:
+ system = system.replace("{%s}" % p["key"], " ")
+
+ fmt_kwargs = dict(kwargs)
+ fmt_kwargs.setdefault("knowledge", "")
+ return system.format(**fmt_kwargs)
+
+
async def rag_agent(dialog, messages, stream=True, **kwargs):
prompt_config = dialog.prompt_config or {}
assert messages[-1]["role"] == "user", "The last content of this conversation is not from user."
@@ -2005,6 +2038,7 @@ async def rag_agent(dialog, messages, stream=True, **kwargs):
do_refer=False,
thinking_mode=thinking_mode,
text_attachments_content=text_attachments_content,
+ system_prompt=_render_reasoning_system_prompt(dialog, prompt_config, kwargs),
)
async def decorate_answer(answer):
diff --git a/internal/agent/harness/agentic_rag.go b/internal/agent/harness/agentic_rag.go
index bf19d6e135..b449cdefcd 100644
--- a/internal/agent/harness/agentic_rag.go
+++ b/internal/agent/harness/agentic_rag.go
@@ -28,6 +28,7 @@ import (
type AgenticState struct {
Question string
Keywords string
+ SystemPrompt string
Route RouteDecision
SeedChunks []string
Plan WorkflowPlan
@@ -51,17 +52,18 @@ type AgenticState struct {
// and delegates to RunAgenticRAGWithRoute so production runners that need a
// route-aware search strategy (e.g. prefer wiki_query on a wiki suggestion) can
// reuse the same flow with a pre-computed route.
-func RunAgenticRAG(ctx context.Context, db *gorm.DB, question, keywords, modeLabel string, search SearchFn) AnswerResult {
- return RunAgenticRAGWithRoute(ctx, db, question, keywords, modeLabel, RouteNode(ctx, db, question, modeLabel), search)
+func RunAgenticRAG(ctx context.Context, db *gorm.DB, question, keywords, modeLabel string, search SearchFn, systemPrompt string) AnswerResult {
+ return RunAgenticRAGWithRoute(ctx, db, question, keywords, modeLabel, RouteNode(ctx, db, question, modeLabel), search, systemPrompt)
}
// RunAgenticRAGWithRoute is the route-aware core of RunAgenticRAG. It performs
// pre_search → planner → orchestrator → formalize_answer with the given route.
-func RunAgenticRAGWithRoute(ctx context.Context, db *gorm.DB, question, keywords, modeLabel string, route RouteDecision, search SearchFn) AnswerResult {
+func RunAgenticRAGWithRoute(ctx context.Context, db *gorm.DB, question, keywords, modeLabel string, route RouteDecision, search SearchFn, systemPrompt string) AnswerResult {
state := &AgenticState{
- Question: strings.TrimSpace(question),
- Keywords: keywords,
- Kbinfos: &Kbinfos{},
+ Question: strings.TrimSpace(question),
+ Keywords: keywords,
+ SystemPrompt: strings.TrimSpace(systemPrompt),
+ Kbinfos: &Kbinfos{},
}
if state.Question == "" {
return AnswerResult{FinalAnswer: emptyResultMessage, Empty: true}
@@ -99,7 +101,7 @@ func RunAgenticRAGWithRoute(ctx context.Context, db *gorm.DB, question, keywords
}
// ── formalize_answer ──
- res := FormalizeAnswer(ctx, db, state.Question, state.Kbinfos, state.PartialAnswer, state.Abstain, state.EmptyResult, orch.Caveat, orch.ForceLLM)
+ res := FormalizeAnswer(ctx, db, state.Question, state.Kbinfos, state.PartialAnswer, state.Abstain, state.EmptyResult, orch.Caveat, orch.ForceLLM, state.SystemPrompt)
// Log only the question length, never its content, to avoid persisting user
// input in logs.
log.Printf("agentic_rag: finished (qlen=%d, strategy=%s, chunks=%d, partial=%v, abstain=%v)",
diff --git a/internal/agent/harness/answer.go b/internal/agent/harness/answer.go
index df05dd5eec..8663de7bb0 100644
--- a/internal/agent/harness/answer.go
+++ b/internal/agent/harness/answer.go
@@ -65,7 +65,10 @@ type AnswerResult struct {
// we still want the model to attempt an answer or plainly state it cannot — not
// a canned "no evidence" string. Mirrors Python, which only short-circuits on
// empty evidence when an explicit empty_response is configured.
-func FormalizeAnswer(ctx context.Context, db *gorm.DB, question string, kb *Kbinfos, partial, abstain, empty bool, caveat string, forceLLM bool) AnswerResult {
+// systemPrompt, when non-empty, is prepended to the final-answer system prompt
+// so the agentic graph honors a configured dialog system prompt (mirrors Python
+// RAGTools.system_prompt + formalize_answer).
+func FormalizeAnswer(ctx context.Context, db *gorm.DB, question string, kb *Kbinfos, partial, abstain, empty bool, caveat string, forceLLM bool, systemPrompt string) AnswerResult {
if abstain {
return AnswerResult{FinalAnswer: abstainMessage, Abstained: true}
}
@@ -102,6 +105,9 @@ func FormalizeAnswer(ctx context.Context, db *gorm.DB, question string, kb *Kbin
}
system := strings.ReplaceAll(finalAnswerSystem, "{cite_rules}", defaultCiteRules)
+ if strings.TrimSpace(systemPrompt) != "" {
+ system = strings.TrimSpace(systemPrompt) + "\n\n" + system
+ }
inv := chat.GetDefaultInvoker()
if inv == nil {
return AnswerResult{FinalAnswer: "I'm sorry, the chat invoker is not configured."}
diff --git a/internal/agent/harness/answer_test.go b/internal/agent/harness/answer_test.go
index 4e5dbf1f2b..1b5773296e 100644
--- a/internal/agent/harness/answer_test.go
+++ b/internal/agent/harness/answer_test.go
@@ -4,12 +4,17 @@ import (
"context"
"strings"
"testing"
+
+ "github.com/cloudwego/eino/schema"
+ "gorm.io/gorm"
+
+ "ragflow/internal/agent/component"
)
// TestFormalizeAnswer_Abstain asserts abstain short-circuits to the abstain
// message without calling the model.
func TestFormalizeAnswer_Abstain(t *testing.T) {
- res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, true, false, "", false)
+ res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, true, false, "", false, "")
if !res.Abstained || res.FinalAnswer != abstainMessage {
t.Errorf("abstain result = %+v, want abstain message", res)
}
@@ -18,7 +23,7 @@ func TestFormalizeAnswer_Abstain(t *testing.T) {
// TestFormalizeAnswer_Empty asserts empty chunks short-circuit to the empty
// message.
func TestFormalizeAnswer_Empty(t *testing.T) {
- res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, false, false, "", false)
+ res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, false, false, "", false, "")
if !res.Empty || res.FinalAnswer != emptyResultMessage {
t.Errorf("empty result = %+v, want empty message", res)
}
@@ -29,7 +34,7 @@ func TestFormalizeAnswer_Empty(t *testing.T) {
func TestFormalizeAnswer_Generates(t *testing.T) {
installChat(t, "here is the final answer")
kb := &Kbinfos{Chunks: []map[string]interface{}{{"content_with_weight": "evidence alpha"}}}
- res := FormalizeAnswer(t.Context(), nil, "What is X?", kb, false, false, false, "", false)
+ res := FormalizeAnswer(t.Context(), nil, "What is X?", kb, false, false, false, "", false, "")
if res.FinalAnswer != "here is the final answer" {
t.Errorf("final answer = %q, want chat output", res.FinalAnswer)
}
@@ -40,7 +45,7 @@ func TestFormalizeAnswer_Generates(t *testing.T) {
func TestFormalizeAnswer_PartialPreamble(t *testing.T) {
installChat(t, "partial ans")
kb := &Kbinfos{Chunks: []map[string]interface{}{{"content_with_weight": "evidence"}}}
- res := FormalizeAnswer(t.Context(), nil, "Q", kb, true, false, false, "", false)
+ res := FormalizeAnswer(t.Context(), nil, "Q", kb, true, false, false, "", false, "")
if !strings.Contains(res.FinalAnswer, "partial ans") {
t.Errorf("final answer = %q", res.FinalAnswer)
}
@@ -50,7 +55,7 @@ func TestFormalizeAnswer_PartialPreamble(t *testing.T) {
// still calls the model, so the FALLBACK_LLM verdict reaches the direct LLM.
func TestFormalizeAnswer_ForceLLM(t *testing.T) {
installChat(t, "direct llm fallback answer")
- res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, false, true, "", true)
+ res := FormalizeAnswer(t.Context(), nil, "Q", &Kbinfos{}, false, false, true, "", true, "")
if res.Empty {
t.Error("forceLLM must not return the empty short-circuit")
}
@@ -66,7 +71,7 @@ func TestRunAgenticRAG_LowMode(t *testing.T) {
res := RunAgenticRAG(t.Context(), nil, "What is a rocket?", "", "low",
func(_ context.Context, _, _ string) ([]map[string]interface{}, []map[string]interface{}) {
return []map[string]interface{}{{"chunk_id": "a", "content_with_weight": "rocket evidence"}}, nil
- })
+ }, "")
if res.FinalAnswer != "final composed answer" {
t.Errorf("final answer = %q", res.FinalAnswer)
}
@@ -77,8 +82,49 @@ func TestRunAgenticRAG_EmptySearch(t *testing.T) {
res := RunAgenticRAG(t.Context(), nil, "Q", "", "low",
func(_ context.Context, _, _ string) ([]map[string]interface{}, []map[string]interface{}) {
return nil, nil
- })
+ }, "")
if !res.Empty || res.FinalAnswer != emptyResultMessage {
t.Errorf("empty result = %+v", res)
}
}
+
+// recordingChatInvoker records the system prompt it receives and returns a fixed
+// answer, so tests can assert the final-answer system message is composed
+// correctly.
+type recordingChatInvoker struct {
+ content string
+ system string
+}
+
+func (r *recordingChatInvoker) Invoke(_ context.Context, _ *gorm.DB, req component.ChatInvokeRequest) (*component.ChatInvokeResponse, error) {
+ for _, m := range req.Messages {
+ if m.Role == schema.System {
+ r.system = m.Content
+ break
+ }
+ }
+ return &component.ChatInvokeResponse{Content: r.content}, nil
+}
+
+// TestFormalizeAnswer_SystemPromptPrepended asserts that a non-empty dialog
+// system prompt is prepended to the final-answer system prompt.
+func TestFormalizeAnswer_SystemPromptPrepended(t *testing.T) {
+ inv := &recordingChatInvoker{content: "final composed answer"}
+ component.SetDefaultChatInvoker(inv)
+ t.Cleanup(func() { component.SetDefaultChatInvoker(nil) })
+
+ kb := &Kbinfos{Chunks: []map[string]interface{}{{"content_with_weight": "evidence"}}}
+ res := FormalizeAnswer(t.Context(), nil, "Q", kb, false, false, false, "", false, "Be concise and factual.")
+ if res.FinalAnswer != "final composed answer" {
+ t.Errorf("final answer = %q, want chat output", res.FinalAnswer)
+ }
+ if inv.system == "" {
+ t.Fatal("system prompt was not sent to the chat invoker")
+ }
+ if !strings.Contains(inv.system, "Be concise and factual.") {
+ t.Errorf("system prompt does not contain the dialog prompt: %q", inv.system)
+ }
+ if !strings.Contains(inv.system, "You are a smart agent") {
+ t.Errorf("system prompt does not contain the default final-answer prompt: %q", inv.system)
+ }
+}
diff --git a/internal/agent/harness/production.go b/internal/agent/harness/production.go
index 86094025bf..d93f5731c2 100644
--- a/internal/agent/harness/production.go
+++ b/internal/agent/harness/production.go
@@ -62,6 +62,9 @@ type ProductionRunner struct {
// by chatPipelineOnce against concurrent runSQLTool calls.
chatPipeline *service.ChatPipelineService
chatPipelineOnce sync.Once
+ // SystemPrompt, when non-empty, is prepended to the final-answer system
+ // prompt (mirrors Python RAGTools.system_prompt).
+ SystemPrompt string
}
// NewProductionRunner builds a ProductionRunner backed by the real tools. The
@@ -166,7 +169,7 @@ func newProductionRunnerWithTools(db *gorm.DB, tenantID string, datasetIDs []str
// tries wiki_query first and falls back to general hybrid search on an empty
// result; otherwise it uses hybrid search. Web fallback is only reachable when a
// web provider is configured (P8). Returns the final answer.
-func (r *ProductionRunner) Run(ctx context.Context, question, keywords, modeLabel string) AnswerResult {
+func (r *ProductionRunner) Run(ctx context.Context, question, keywords, modeLabel, systemPrompt string) AnswerResult {
if r.searchTool == nil {
log.Printf("agentic_rag: production runner not fully wired (search tool missing)")
return AnswerResult{FinalAnswer: emptyResultMessage, Empty: true}
@@ -196,15 +199,15 @@ func (r *ProductionRunner) Run(ctx context.Context, question, keywords, modeLabe
// not the SearchFn closure used by low/medium. This is the P5 strategy
// dispatch: high/ultra is a strict superset of medium.
if route.ExecutionStrategy == "agentic_research" || route.ExecutionStrategy == "deep_research" {
- return r.runAgentic(ctx, question, keywords, modeLabel, route)
+ return r.runAgentic(ctx, question, keywords, modeLabel, route, systemPrompt)
}
- return RunAgenticRAGWithRoute(ctx, r.db, question, keywords, modeLabel, route, searchFn)
+ return RunAgenticRAGWithRoute(ctx, r.db, question, keywords, modeLabel, route, searchFn, systemPrompt)
}
// runAgentic drives the high/ultra two-level loop over a Pipeline. It shares the
// same route/planner as RunAgenticRAGWithRoute but researches claims via the
// research agent (inner tool loop) rather than a single hybrid search.
-func (r *ProductionRunner) runAgentic(ctx context.Context, question, keywords, modeLabel string, route RouteDecision) AnswerResult {
+func (r *ProductionRunner) runAgentic(ctx context.Context, question, keywords, modeLabel string, route RouteDecision, systemPrompt string) AnswerResult {
mode, _ := GetMode(modeLabel)
if mode.Label == "" {
mode = THINKING_MODES["high"]
@@ -227,7 +230,7 @@ func (r *ProductionRunner) runAgentic(ctx context.Context, question, keywords, m
orch := AgenticResearch(ctx, r.db, pipeline, question, claims, mode)
- return FormalizeAnswer(ctx, r.db, question, orch.Kbinfos, orch.PartialAnswer, orch.Abstain, orch.EmptyResult, orch.Caveat, orch.ForceLLM)
+ return FormalizeAnswer(ctx, r.db, question, orch.Kbinfos, orch.PartialAnswer, orch.Abstain, orch.EmptyResult, orch.Caveat, orch.ForceLLM, systemPrompt)
}
// buildCompilationMap reports which compiled artifacts each bound KB carries,
diff --git a/internal/agent/harness/production_test.go b/internal/agent/harness/production_test.go
index 782545b056..48ffcd3c8a 100644
--- a/internal/agent/harness/production_test.go
+++ b/internal/agent/harness/production_test.go
@@ -91,7 +91,7 @@ func TestProductionRunner_E2E_RouteToScopedSearch(t *testing.T) {
// Multi-KB session: routing must cover every bound dataset, not just the
// first KB.
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1", "kb2"}, searchTool, navSvc)
- res := runner.Run(t.Context(), "Compare A and B", "", "medium")
+ res := runner.Run(t.Context(), "Compare A and B", "", "medium", "")
if res.FinalAnswer != "final scoped answer" {
t.Errorf("final answer = %q, want chat output", res.FinalAnswer)
@@ -117,7 +117,7 @@ func TestProductionRunner_E2E_NoRoute_SearchUnscoped(t *testing.T) {
// A nav service is provided but must NOT be consulted in low mode.
navSvc := &fakeNavSvcHarness{clusters: []nav.NavNode{{Name: "C1"}}}
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1"}, searchTool, navSvc)
- res := runner.Run(t.Context(), "What is X?", "", "low")
+ res := runner.Run(t.Context(), "What is X?", "", "low", "")
if res.FinalAnswer == "" {
t.Error("expected a final answer in low mode")
@@ -137,7 +137,7 @@ func TestProductionRunner_E2E_EmptyRoute_SearchUnscoped(t *testing.T) {
// Nav service with no clusters -> empty route.
navSvc := &fakeNavSvcHarness{clusters: nil}
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1"}, searchTool, navSvc)
- res := runner.Run(t.Context(), "Compare A and B", "", "medium")
+ res := runner.Run(t.Context(), "Compare A and B", "", "medium", "")
if res.FinalAnswer == "" {
t.Error("expected an answer even when nav routing returns no docs")
}
diff --git a/internal/agent/harness/production_wiki_test.go b/internal/agent/harness/production_wiki_test.go
index ec8bd466bc..764583dc2e 100644
--- a/internal/agent/harness/production_wiki_test.go
+++ b/internal/agent/harness/production_wiki_test.go
@@ -103,7 +103,7 @@ func TestProductionRunner_WikiPreferred_WhenSuggested(t *testing.T) {
}}
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1"}, hybrid, nil)
runner.wikiSvc = wikiSvc
- res := runner.Run(t.Context(), "What is Alpha?", "", "low")
+ res := runner.Run(t.Context(), "What is Alpha?", "", "low", "")
if res.FinalAnswer != "final wiki answer" {
t.Errorf("final answer = %q, want wiki chat output", res.FinalAnswer)
}
@@ -123,7 +123,7 @@ func TestProductionRunner_WikiEmpty_FallsBackToHybrid(t *testing.T) {
wikiSvc := &fakeWikiSvcHarness{available: true} // no pages
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1"}, hybrid, nil)
runner.wikiSvc = wikiSvc
- res := runner.Run(t.Context(), "What is Alpha?", "", "low")
+ res := runner.Run(t.Context(), "What is Alpha?", "", "low", "")
if len(wikiSvc.seenQueries()) == 0 {
t.Errorf("wiki service should have been attempted")
}
@@ -148,7 +148,7 @@ func TestProductionRunner_NoWikiWithoutSuggestion(t *testing.T) {
}}
runner := newProductionRunnerWithTools(nil, "t1", []string{"kb1"}, hybrid, nil)
runner.wikiSvc = wikiSvc
- runner.Run(t.Context(), "What is Alpha?", "", "low")
+ runner.Run(t.Context(), "What is Alpha?", "", "low", "")
if len(wikiSvc.seenQueries()) != 0 {
t.Errorf("wiki service must not be queried without a wiki suggestion; calls=%v", wikiSvc.seenQueries())
}
diff --git a/rag/advanced_rag/agentic_rag.py b/rag/advanced_rag/agentic_rag.py
index 4d8d854b78..64993d6059 100644
--- a/rag/advanced_rag/agentic_rag.py
+++ b/rag/advanced_rag/agentic_rag.py
@@ -208,6 +208,7 @@ class RAGTools:
do_refer: bool | None = True,
thinking_mode: str = "medium",
text_attachments_content: str = "",
+ system_prompt: str = "",
):
self.tenant_ids = tenant_ids
# P0 instrumentation: count LLM calls / token usage per harness phase.
@@ -244,6 +245,7 @@ class RAGTools:
self.empty_response = empty_response
self.do_refer = do_refer
self.text_attachments_content = text_attachments_content or ""
+ self.system_prompt = system_prompt or ""
# Optional sink used by the outer agent stream to preserve the final
# answer deltas produced by the inner research graph. The tool API
# still returns the complete string to the caller, but the stream
diff --git a/rag/advanced_rag/agentic_rag_graph.py b/rag/advanced_rag/agentic_rag_graph.py
index 743f486112..d00d529a66 100644
--- a/rag/advanced_rag/agentic_rag_graph.py
+++ b/rag/advanced_rag/agentic_rag_graph.py
@@ -434,6 +434,10 @@ def build_agentic_graph(tools, token_queue: asyncio.Queue, gen_conf: dict | None
rules = cp(tools.user_defined_prompts).strip()
system = FINAL_ANSWER_SYSTEM.format(cite_rules=rules)
+ # Honor the dialog-level system prompt in the reasoning path the same
+ # way async_chat does when reasoning is disabled.
+ if tools.system_prompt.strip():
+ system = f"{tools.system_prompt.strip()}\n\n{system}"
parts.append(f"Evidence:\n{evidence}")
user_content = "\n".join(parts)
diff --git a/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py
index 1dcf592e41..38d50d78da 100644
--- a/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py
+++ b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py
@@ -176,3 +176,32 @@ def test_rag_agent_preserves_multimodal_content_parts(monkeypatch):
chat_mdl = _drive_rag_agent(monkeypatch, messages)
assert chat_mdl.sent_messages[0]["content"] == content
+
+
+def test_render_reasoning_system_prompt_substitutes_date_and_knowledge():
+ """The reasoning path should honor the dialog system prompt like async_chat does."""
+ dialog = SimpleNamespace(kb_ids=["kb-1"])
+ prompt_config = {"system": "Role: pirate. Date: {date}. Context: '{knowledge}'."}
+ kwargs = {}
+
+ rendered = dialog_service._render_reasoning_system_prompt(dialog, prompt_config, kwargs)
+
+ assert rendered.startswith("Role: pirate. Date: 2")
+ assert "Context: ''." in rendered
+
+
+def test_render_reasoning_system_prompt_replaces_optional_missing_parameters():
+ """Optional parameters missing from kwargs are blanked out, not left as placeholders."""
+ dialog = SimpleNamespace(kb_ids=[])
+ prompt_config = {
+ "system": "Lang: {language}.",
+ "parameters": [{"key": "language", "optional": True}],
+ }
+ kwargs = {"date": "2026-08-27"}
+
+ rendered = dialog_service._render_reasoning_system_prompt(dialog, prompt_config, kwargs)
+
+ # Missing optional parameters are replaced with a space, matching async_chat.
+ assert rendered == "Lang: ."