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
feat(agentic-rag): support per-chat prompts and tool selection (#21211)
Sbaaoui Idriss52fa88b828d8
diff --git a/internal/agentic_rag/agent.go b/internal/agentic_rag/agent.goindex dbd3c82500..5e61d1239f 100644--- a/internal/agentic_rag/agent.go+++ b/internal/agentic_rag/agent.go@@ -35,6 +35,7 @@ import ("ragflow/internal/agent/runtime""ragflow/internal/common"+ "ragflow/internal/engine""ragflow/internal/entity/models""ragflow/internal/tokenizer")@@ -94,6 +95,8 @@ type Input struct {// request's agent_mode. It is mandatory: an empty or unknown id fails the// run with a clear error — there is no default/env/first-template fallback.TemplateID string+ // Template is the per-run resolved configuration, shared with model setup.+ Template *Template// OnDelta, when non-nil, receives each incremental (content, reasoning)// delta as it streams. When nil, deltas fall back to runtime.EmitAgentMessage.OnDelta func(contentDelta, thinkingDelta string)@@ -331,10 +334,16 @@ func Run(ctx context.Context, in Input) (string, error) {defer forgetConversation(convKey)}- tmpl, errT := resolveTemplateFor(in.TemplateID)- if errT != nil {- common.ErrorCtx(ctx, "agentic_rag: resolve template", errT)- return "", errT+ var tmpl Template+ if in.Template != nil {+ tmpl = *in.Template+ } else {+ var err error+ tmpl, err = ResolveTemplate(in.TemplateID, nil)+ if err != nil {+ common.ErrorCtx(ctx, "agentic_rag: resolve template", err)+ return "", err+ }}// Shared per-run duration tally: every tool invocation is timed and@@ -345,35 +354,7 @@ func Run(ctx context.Context, in Input) (string, error) {// With no explicit tools, use the requested template. The config reloads// when its mtime changes so operators can change the tool list and prompt.- tools := toolsFor(ctx, tmpl, in.TenantID, in.DatasetIDs, in.Tools)- // The compiled-knowledge tools are injected, never declared: they only make- // sense when the bound datasets have produced knowledge-compilation products- // (navigation tree / compiled structure / knowledge graph / per-document- // panorama), so an uncompiled corpus never offers - or pays for - them. A- // caller that passes explicit tools owns its own set and is left untouched.- //- // The decision is logged on every run. The injection is otherwise silent, so- // "the tool was never offered" would be indistinguishable from "the tool was- // offered and the model ignored it" in the server log - which is exactly the- // question a tool-usage review asks.- compiledInjected := false- if len(in.Tools) != 0 {- common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",- zap.Strings("datasets", in.DatasetIDs),- zap.String("reason", "caller supplied an explicit tool list"))- } else if datasetsHaveCompiledKnowledge(ctx, in.TenantID, in.DatasetIDs) {- compiled := compiledKnowledgeTools(in.TenantID, in.DatasetIDs)- tools = append(tools, compiled...)- compiledInjected = true- common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools injected",- zap.Strings("datasets", in.DatasetIDs),- zap.String("reason", "compile_kwd rows present in the bound datasets"),- zap.Int("tools", len(compiled)))- } else {- common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",- zap.Strings("datasets", in.DatasetIDs),- zap.String("reason", "no compile_kwd row in the bound datasets"))- }+ tools := toolsForRun(ctx, tmpl, in, engine.Get())agentModel, err := modelForTools(ctx, in.Model, tools, in.DatasetIDs)if err != nil {return "", err@@ -397,7 +378,7 @@ func Run(ctx context.Context, in Input) (string, error) {// A recall that does not cover the question is discarded here. The loop then// runs exactly as it would have without the recall, and navigate_structure// stays available for the model to call on demand.- if compiledInjected {+ if len(in.Tools) == 0 && !tmpl.strictTools {pf := recallCompiledClaims(ctx, in.TenantID, in.DatasetIDs, in.Messages)if pf.sufficient {answer, aerr := answerFromClaims(ctx, synthModelFor(in), tmpl.Content, in.Messages, pf)@@ -458,6 +439,14 @@ func Run(ctx context.Context, in Input) (string, error) {}tools = kept}+ names := make([]string, 0, len(tools))+ for _, t := range tools {+ if info, err := t.Info(ctx); err == nil && info != nil {+ names = append(names, info.Name)+ }+ }+ common.InfoCtx(ctx, "agentic_rag: configured runtime tools",+ zap.String("template", tmpl.ID), zap.Bool("strict_tools", tmpl.strictTools), zap.Strings("tools", names))common.DebugCtx(ctx, "agentic_rag: run start",zap.Int("max_iterations", maxIter),@@ -560,7 +549,11 @@ func Run(ctx context.Context, in Input) (string, error) {synthCtx, synthCancel := context.WithTimeout(context.WithoutCancel(ctx), finalizeTimeout)defer synthCancel()synthCtx = tokenizer.WithUsagePhase(synthCtx, "synth")- synth, synthErr := finalizeAnswer(synthCtx, synthModelFor(in), in.Messages, final, evidence)+ synthMessages := in.Messages+ if tmpl.customContent {+ synthMessages = append([]*schema.Message{schema.SystemMessage(tmpl.Content)}, synthMessages...)+ }+ synth, synthErr := finalizeAnswer(synthCtx, synthModelFor(in), synthMessages, final, evidence)if synthErr != nil {// Without this an empty final is completely silent: the run looks// healthy in every other log line and the user simply gets nothing.diff --git a/internal/agentic_rag/compiled_knowledge.go b/internal/agentic_rag/compiled_knowledge.goindex b81b4fdac9..e3fc4b816b 100644--- a/internal/agentic_rag/compiled_knowledge.go+++ b/internal/agentic_rag/compiled_knowledge.go@@ -63,11 +63,10 @@ func compiledKnowledgeTools(tenantID string, datasetIDs []string) []tool.BaseToo// carry compile_kwd; ordinary chunks do not (that is what the default retriever// excludes with must_not/exists compile_kwd), so a single existence read answers// it. A missing engine or an empty scope is false, leaving the tools undeclared.-func datasetsHaveCompiledKnowledge(ctx context.Context, tenantID string, datasetIDs []string) bool {+func datasetsHaveCompiledKnowledge(ctx context.Context, de engine.DocEngine, tenantID string, datasetIDs []string) bool {if len(datasetIDs) == 0 {return false}- de := engine.Get()if de == nil {return false}@@ -92,6 +91,27 @@ func datasetsHaveCompiledKnowledge(ctx context.Context, tenantID string, datasetreturn len(res.Chunks) > 0}+func toolsForRun(ctx context.Context, tmpl Template, in Input, de engine.DocEngine) []tool.BaseTool {+ tools := toolsFor(ctx, tmpl, in.TenantID, in.DatasetIDs, in.Tools)+ if len(in.Tools) != 0 || tmpl.strictTools {+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",+ zap.Strings("datasets", in.DatasetIDs),+ zap.String("reason", "explicit tool selection"))+ } else if datasetsHaveCompiledKnowledge(ctx, de, in.TenantID, in.DatasetIDs) {+ compiled := compiledKnowledgeTools(in.TenantID, in.DatasetIDs)+ tools = append(tools, compiled...)+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools injected",+ zap.Strings("datasets", in.DatasetIDs),+ zap.String("reason", "compile_kwd rows present in the bound datasets"),+ zap.Int("tools", len(compiled)))+ } else {+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",+ zap.Strings("datasets", in.DatasetIDs),+ zap.String("reason", "no compile_kwd row in the bound datasets"))+ }+ return tools+}+// datasetsHaveClaims reports whether any bound dataset carries knowledge-compiled// CLAIM rows (entity_type_kwd="claim").//diff --git a/internal/agentic_rag/config.go b/internal/agentic_rag/config.goindex 5c404c6059..4561119513 100644--- a/internal/agentic_rag/config.go+++ b/internal/agentic_rag/config.go@@ -22,6 +22,7 @@ import ("fmt""os""path/filepath"+ "slices""strings""sync""time"@@ -47,9 +48,11 @@ type Template struct {// model-default runs proved noisier than the exploration its sampling// buys. An undeclared template leaves the field unset: the model's own// default applies.- Temperature *float64 `json:"temperature" yaml:"temperature"`- Tools []string `json:"tools" yaml:"tools"`- Content string `json:"content" yaml:"content"`+ Temperature *float64 `json:"temperature" yaml:"temperature"`+ Tools []string `json:"tools" yaml:"tools"`+ Content string `json:"content" yaml:"content"`+ strictTools bool+ customContent bool}// configFile is the on-disk shape: a plain list of templates. Which template@@ -193,6 +196,10 @@ func resolveTemplateFor(id string) (Template, error) {if strings.TrimSpace(t.Content) == "" {return Template{}, fmt.Errorf("agentic_rag: template %q has no prompt content in %s", id, defaultConfigPath())}+ t.Tools = slices.Clone(t.Tools)+ if t.Temperature != nil {+ t.Temperature = new(*t.Temperature)+ }return t, nil}}@@ -219,16 +226,17 @@ func TemplateTemperature(templateID string) *float64 {// skipped with a warning. The conversation's web capability is added here so// all retrieval tools use the same agent dispatch path.func toolsFor(ctx context.Context, t Template, tenantID string, datasetIDs []string, tools []tool.BaseTool) []tool.BaseTool {- if len(tools) > 0 {+ if len(tools) > 0 && !t.strictTools {return append(append([]tool.BaseTool(nil), tools...), webSearchTools(ctx)...)}reg := toolRegistry()names := t.Tools- if len(names) == 0 {+ if len(names) == 0 && !t.strictTools {names = make([]string, 0, len(reg))for n := range reg {names = append(names, n)}+ slices.Sort(names)}out := make([]tool.BaseTool, 0, len(names))for _, name := range names {diff --git a/internal/agentic_rag/override.go b/internal/agentic_rag/override.gonew file mode 100644index 0000000000..63680c7592--- /dev/null+++ b/internal/agentic_rag/override.go@@ -0,0 +1,188 @@+package agentic_rag++import (+ "context"+ "fmt"+ "slices"+ "strings"+ "unicode/utf8"+)++// Override contains only the per-chat fields that replace template values.+type Override struct {+ Content *string `json:"content,omitempty"`+ Tools *[]string `json:"tools,omitempty"`+}++// ParseOverride validates the decoded prompt_config.agentic_rag value.+// A nil value resets inheritance; omitted fields continue to inherit.+func ParseOverride(raw any) (*Override, error) {+ if raw == nil {+ return nil, nil+ }+ object, ok := raw.(map[string]any)+ if !ok {+ return nil, fmt.Errorf("agentic_rag must be an object or null")+ }+ result := &Override{}+ for key, value := range object {+ switch key {+ case "content":+ content, ok := value.(string)+ if !ok {+ return nil, fmt.Errorf("agentic_rag.content must be a string")+ }+ result.Content = &content+ case "tools":+ var names []string+ switch values := value.(type) {+ case []string:+ names = slices.Clone(values)+ case []any:+ names = make([]string, len(values))+ for i, item := range values {+ name, ok := item.(string)+ if !ok {+ return nil, fmt.Errorf("agentic_rag.tools[%d] must be a string", i)+ }+ names[i] = name+ }+ default:+ return nil, fmt.Errorf("agentic_rag.tools must be an array of strings")+ }+ result.Tools = &names+ default:+ return nil, fmt.Errorf("agentic_rag has unknown field %q", key)+ }+ }+ if err := validateOverride(result); err != nil {+ return nil, err+ }+ return result, nil+}++func validateOverride(override *Override) error {+ if override == nil {+ return nil+ }+ if override.Content != nil {+ content := *override.Content+ switch {+ case !utf8.ValidString(content):+ return fmt.Errorf("agentic_rag.content must be valid UTF-8")+ case strings.ContainsRune(content, 0):+ return fmt.Errorf("agentic_rag.content must not contain NUL")+ case strings.TrimSpace(content) == "":+ return fmt.Errorf("agentic_rag.content must not be empty")+ case utf8.RuneCountInString(content) > 32768:+ return fmt.Errorf("agentic_rag.content must contain at most 32768 characters")+ }+ }+ if override.Tools == nil {+ return nil+ }+ registry := toolRegistry()+ seen := make(map[string]bool, len(*override.Tools))+ hasSearch := false+ for _, name := range *override.Tools {+ if _, ok := registry[name]; !ok {+ return fmt.Errorf("agentic_rag.tools contains unknown tool %q", name)+ }+ if seen[name] {+ return fmt.Errorf("agentic_rag.tools contains duplicate tool %q", name)+ }+ seen[name] = true+ switch name {+ case "grep_chunks", "search_chunks", "search_bm25_chunks", "search_semantic_chunks":+ hasSearch = true+ }+ }+ if !hasSearch {+ return fmt.Errorf("agentic_rag.tools requires at least one corpus search tool: grep_chunks, search_chunks, search_bm25_chunks, or search_semantic_chunks")+ }+ if !seen["list_chunks"] {+ return fmt.Errorf("agentic_rag.tools requires list_chunks to read document evidence")+ }+ return nil+}++// ResolveTemplate applies a chat override to a private copy of the selected+// current YAML template. It never changes the cached defaults.+func ResolveTemplate(id string, override *Override) (Template, error) {+ if err := validateOverride(override); err != nil {+ return Template{}, err+ }+ template, err := resolveTemplateFor(id)+ if err != nil {+ return template, err+ }+ return applyOverride(template, override), nil+}++func applyOverride(template Template, override *Override) Template {+ template.Tools = slices.Clone(template.Tools)+ if template.Temperature != nil {+ template.Temperature = new(*template.Temperature)+ }+ if override == nil {+ return template+ }+ if override.Content != nil {+ template.Content = *override.Content+ template.customContent = true+ }+ if override.Tools != nil {+ template.Tools = slices.Clone(*override.Tools)+ template.strictTools = true+ }+ return template+}++type ToolDescription struct {+ Name string `json:"name"`+ Description string `json:"description"`+}++// Settings describes configured tools, whose execution still depends on the+// dataset capabilities and request authorization.+type Settings struct {+ BaseTemplate string `json:"base_template"`+ Defaults Template `json:"defaults"`+ Override *Override `json:"override"`+ Effective Template `json:"effective"`+ AvailableTools []ToolDescription `json:"available_tools"`+ UsingDefaults bool `json:"using_defaults"`+}++func GetSettings(ctx context.Context, override *Override) (*Settings, error) {+ defaults, err := ResolveTemplate("smart-reasoning", nil)+ if err != nil {+ return nil, err+ }+ if err := validateOverride(override); err != nil {+ return nil, err+ }+ effective := applyOverride(defaults, override)+ registry := toolRegistry()+ names := make([]string, 0, len(registry))+ for name := range registry {+ names = append(names, name)+ }+ slices.Sort(names)+ available := make([]ToolDescription, 0, len(names))+ for _, name := range names {+ info, err := registry[name]("", nil).Info(ctx)+ if err != nil {+ return nil, fmt.Errorf("agentic_rag: describe tool %q: %w", name, err)+ }+ if info == nil {+ return nil, fmt.Errorf("agentic_rag: tool %q has no description", name)+ }+ available = append(available, ToolDescription{Name: name, Description: info.Desc})+ }+ return &Settings{+ BaseTemplate: defaults.ID, Defaults: defaults, Override: override,+ Effective: effective, AvailableTools: available,+ UsingDefaults: override == nil || (override.Content == nil && override.Tools == nil),+ }, nil+}diff --git a/internal/agentic_rag/override_test.go b/internal/agentic_rag/override_test.gonew file mode 100644index 0000000000..10481b98e5--- /dev/null+++ b/internal/agentic_rag/override_test.go@@ -0,0 +1,302 @@+package agentic_rag++import (+ "context"+ "fmt"+ "os"+ "slices"+ "strings"+ "sync"+ "testing"+ "time"++ "github.com/cloudwego/eino/components/tool"+ "github.com/cloudwego/eino/schema"++ "ragflow/internal/agent/runtime"+ "ragflow/internal/entity/models"+)++func TestParseOverride(t *testing.T) {+ for _, tc := range []struct {+ name string+ raw any+ want string+ }{+ {"reset", nil, ""},+ {"inherit", map[string]any{}, ""},+ {"prompt", map[string]any{"content": "custom instruction"}, ""},+ {"tools", map[string]any{"tools": []any{"grep_chunks", "list_chunks"}}, ""},+ {"structure", "prompt", "object"},+ {"unknown field", map[string]any{"temperature": 1}, "unknown"},+ {"null prompt", map[string]any{"content": nil}, "string"},+ {"blank prompt", map[string]any{"content": " \n"}, "empty"},+ {"large prompt", map[string]any{"content": strings.Repeat("界", 32769)}, "32768"},+ {"NUL", map[string]any{"content": "bad\x00prompt"}, "NUL"},+ {"UTF8", map[string]any{"content": string([]byte{0xff})}, "UTF-8"},+ {"null tools", map[string]any{"tools": nil}, "array"},+ {"tools type", map[string]any{"tools": "grep_chunks"}, "array"},+ {"tool type", map[string]any{"tools": []any{1}}, "string"},+ {"unknown tool", map[string]any{"tools": []any{"unknown"}}, "unknown"},+ {"privileged web", map[string]any{"tools": []any{"web_search"}}, "unknown"},+ {"duplicate", map[string]any{"tools": []any{"grep_chunks", "grep_chunks", "list_chunks"}}, "duplicate"},+ {"empty", map[string]any{"tools": []any{}}, "corpus search"},+ {"missing search", map[string]any{"tools": []any{"list_chunks"}}, "corpus search"},+ {"missing deep read", map[string]any{"tools": []any{"grep_chunks"}}, "list_chunks"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ _, err := ParseOverride(tc.raw)+ if tc.want == "" && err != nil {+ t.Fatal(err)+ }+ if tc.want != "" && (err == nil || !strings.Contains(err.Error(), tc.want)) {+ t.Fatalf("error = %v, want %q", err, tc.want)+ }+ })+ }+}++func TestResolveOverrideInheritanceIsolationAndReload(t *testing.T) {+ setupTestConfig(t)+ content := "custom instruction"+ names := []string{"grep_chunks", "list_chunks"}+ override := &Override{Content: &content, Tools: &names}+ effective, err := ResolveTemplate("smart-grep", override)+ if err != nil {+ t.Fatal(err)+ }+ if effective.ID != "smart-grep" || effective.Content != content || !slices.Equal(effective.Tools, names) || !effective.strictTools {+ t.Fatalf("resolved template: %+v", effective)+ }+ effective.Tools[0] = "think"+ original, err := ResolveTemplate("smart-grep", nil)+ if err != nil || original.Content != "GREP-ONLY PROMPT\n" || original.Tools[0] != "think" || names[0] != "grep_chunks" {+ t.Fatalf("resolution mutated input/cache: %+v, %v, %v", original, names, err)+ }+ original.Tools[0] = "mutated"+ cached, err := ResolveTemplate("smart-grep", nil)+ if err != nil || cached.Tools[0] != "think" {+ t.Fatalf("returned default aliases YAML cache: %+v, %v", cached, err)+ }+ var wg sync.WaitGroup+ for i := range 20 {+ wg.Go(func() {+ prompt := strings.Repeat("x", i+1)+ got, err := ResolveTemplate("smart-reasoning", &Override{Content: &prompt})+ if err != nil || got.Content != prompt || !slices.Equal(got.Tools, []string{"think", "grep_chunks", "search_chunks", "list_chunks"}) {+ t.Errorf("concurrent resolution: %+v, %v", got, err)+ }+ })+ }+ wg.Wait()+ path := os.Getenv("AGENTIC_RAG_CONFIG")+ updated := strings.ReplaceAll(twoTemplateYAML, "FULL-MODE PROMPT", "RELOADED PROMPT")+ updated = strings.ReplaceAll(updated, " - search_chunks\n", " - search_bm25_chunks\n")+ if err := os.WriteFile(path, []byte(updated), 0o600); err != nil {+ t.Fatal(err)+ }+ future := time.Now().Add(time.Second)+ if err := os.Chtimes(path, future, future); err != nil {+ t.Fatal(err)+ }+ got, err := ResolveTemplate("smart-reasoning", &Override{Content: &content})+ if err != nil || got.Content != content || !slices.Contains(got.Tools, "search_bm25_chunks") {+ t.Fatalf("partial override failed to inherit reload: %+v, %v", got, err)+ }+ got, err = ResolveTemplate("smart-reasoning", nil)+ if err != nil || got.Content != "RELOADED PROMPT\n" {+ t.Fatalf("reset failed to inherit reload: %+v, %v", got, err)+ }+ got, err = ResolveTemplate("smart-reasoning", &Override{Tools: &names})+ if err != nil || got.Content != "RELOADED PROMPT\n" || !slices.Equal(got.Tools, names) {+ t.Fatalf("tools-only override failed to inherit reloaded prompt: %+v, %v", got, err)+ }+}++func TestSettingsRegistryAndDefaultIsolation(t *testing.T) {+ setupTestConfig(t)+ content := "custom"+ settings, err := GetSettings(t.Context(), &Override{Content: &content})+ if err != nil {+ t.Fatal(err)+ }+ if settings.BaseTemplate != "smart-reasoning" || settings.UsingDefaults || settings.Defaults.Content != "FULL-MODE PROMPT\n" || settings.Effective.Content != content {+ t.Fatalf("settings: %+v", settings)+ }+ if len(settings.AvailableTools) != len(toolRegistry()) {+ t.Fatalf("catalog length: %d", len(settings.AvailableTools))+ }+ var previous string+ for _, info := range settings.AvailableTools {+ if info.Name <= previous || info.Description == "" || info.Name == webSearchToolName {+ t.Fatalf("invalid registry description: %+v", info)+ }+ previous = info.Name+ }+ settings.Effective.Tools[0] = "changed"+ if settings.Defaults.Tools[0] == "changed" {+ t.Fatal("effective template aliases defaults")+ }+ defaults, err := GetSettings(t.Context(), nil)+ if err != nil || !defaults.UsingDefaults || defaults.Override != nil || defaults.Defaults.Content != defaults.Effective.Content {+ t.Fatalf("default settings: %+v, %v", defaults, err)+ }+}++func TestRunUsesOverridePromptAndExactTools(t *testing.T) {+ for _, stream := range []bool{false, true} {+ for _, web := range []bool{false, true} {+ t.Run(fmt.Sprintf("stream=%t/web=%t", stream, web), func(t *testing.T) {+ setupTestConfig(t)+ corpus := newCaptureService()+ runtime.SetRetrievalService(corpus)+ t.Cleanup(func() { runtime.SetRetrievalService(nil) })+ content := "CUSTOM SYSTEM INSTRUCTION"+ names := []string{"search_chunks", "list_chunks"}+ template, err := ResolveTemplate("smart-reasoning", &Override{Content: &content, Tools: &names})+ if err != nil {+ t.Fatal(err)+ }+ ctx := WithEvidenceRegistry(t.Context(), NewEvidenceRegistry())+ if web {+ ctx = WithWebSearch(ctx, func(context.Context, string) ([]WebResult, error) {+ return []WebResult{{Title: "web", URL: "https://example.com", Content: "evidence"}}, nil+ })+ }+ calls := 0+ driver := &retrievalToolDriver{respond: func(messages []models.Message, config *models.ChatConfig) *models.ChatResponse {+ calls+++ var system []string+ for _, message := range messages {+ if message.Role == "system" {+ system = append(system, fmt.Sprint(message.Content))+ }+ }+ if !strings.Contains(strings.Join(system, "\n"), content) || strings.Contains(strings.Join(system, "\n"), "FULL-MODE PROMPT") {+ t.Errorf("wrong executing instruction: %v", system)+ }+ advertised, _ := config.Tools.([]map[string]any)+ got := []string{}+ for _, definition := range advertised {+ function, _ := definition["function"].(map[string]any)+ got = append(got, fmt.Sprint(function["name"]))+ }+ want := slices.Clone(names)+ if web {+ want = append(want, webSearchToolName)+ }+ if !slices.Equal(got, want) {+ t.Errorf("actual tools = %v, want %v", got, want)+ }+ required := []string{"search_chunks"}+ if web {+ required = append(required, webSearchToolName)+ }+ if calls <= len(required) {+ name := required[calls-1]+ return &models.ChatResponse{ToolCalls: []map[string]any{{"id": name, "type": "function", "function": map[string]any{"name": name, "arguments": `{"queries":["evidence"]}`}}}}+ }+ answer := "custom answer [ID:0]"+ return &models.ChatResponse{Answer: &answer}+ }}+ modelName := driver.Name()+ counts := map[string]int{}+ answer, err := Run(ctx, Input{+ Model: models.NewEinoChatModel(models.NewChatModel(driver, &modelName, &models.APIConfig{}), nil),+ Template: &template, DatasetIDs: []string{"kb1"}, TenantID: "tenant",+ // A direct caller's tools must not bypass a saved restriction.+ Tools: []tool.BaseTool{NewThinkTool()},+ Messages: []*schema.Message{schema.UserMessage("question")},+ Stream: stream, MaxIterations: 4, OnDelta: func(string, string) {}, ToolCallCounts: counts,+ })+ if err != nil || answer != "custom answer [ID:0]" || len(corpus.reqs) != 1 || counts["search_chunks"] != 1 {+ t.Fatalf("Run: answer=%q error=%v requests=%d counts=%v", answer, err, len(corpus.reqs), counts)+ }+ })+ }+ }+}++func TestRunSynthesisUsesOverrideAndCannotExecuteDisabledTool(t *testing.T) {+ setupTestConfig(t)+ corpus := newCaptureService()+ runtime.SetRetrievalService(corpus)+ t.Cleanup(func() { runtime.SetRetrievalService(nil) })+ content := "CUSTOM SYNTHESIS INSTRUCTION"+ names := []string{"grep_chunks", "list_chunks"}+ template, err := ResolveTemplate("smart-reasoning", &Override{Content: &content, Tools: &names})+ if err != nil {+ t.Fatal(err)+ }+ driver := &retrievalToolDriver{respond: func([]models.Message, *models.ChatConfig) *models.ChatResponse {+ return &models.ChatResponse{ToolCalls: []map[string]any{{"id": "forbidden", "type": "function", "function": map[string]any{"name": "search_chunks", "arguments": `{"queries":["forbidden"]}`}}}}+ }}+ synthCalls := 0+ synthDriver := &retrievalToolDriver{respond: func(messages []models.Message, config *models.ChatConfig) *models.ChatResponse {+ synthCalls+++ if len(messages) == 0 || messages[0].Role != "system" || fmt.Sprint(messages[0].Content) != content {+ t.Errorf("synthesis lost custom instruction: %+v", messages)+ }+ if config.Tools != nil {+ t.Errorf("synthesis advertised tools: %+v", config.Tools)+ }+ answer := "custom fallback"+ return &models.ChatResponse{Answer: &answer}+ }}+ modelName := driver.Name()+ answer, err := Run(t.Context(), Input{+ Model: models.NewEinoChatModel(models.NewChatModel(driver, &modelName, &models.APIConfig{}), nil),+ SynthModel: models.NewEinoChatModel(models.NewChatModel(synthDriver, &modelName, &models.APIConfig{}), nil),+ Template: &template, DatasetIDs: []string{"kb1"}, TenantID: "tenant",+ Messages: []*schema.Message{schema.UserMessage("question")},+ MaxIterations: 2, OnDelta: func(string, string) {},+ })+ if err != nil || answer != "custom fallback" || synthCalls != 1 || len(corpus.reqs) != 0 {+ t.Fatalf("Run: answer=%q err=%v synth=%d forbidden executions=%d", answer, err, synthCalls, len(corpus.reqs))+ }+}++func TestStrictEmptyToolsNeverExpandToRegistry(t *testing.T) {+ got := toolsFor(t.Context(), Template{strictTools: true}, "tenant", nil, nil)+ if len(got) != 0 {+ t.Fatalf("empty explicit tools expanded to %d tools", len(got))+ }+}++func TestStrictToolsPreventCompiledInjection(t *testing.T) {+ setupTestConfig(t)+ de := &kgProbeFakeEngine{entityRows: []map[string]any{{"id": "compiled"}}}+ if !datasetsHaveCompiledKnowledge(t.Context(), de, "tenant", []string{"kb1"}) {+ t.Fatal("mock corpus must have compiled knowledge")+ }+ in := Input{TenantID: "tenant", DatasetIDs: []string{"kb1"}}+ defaults, err := ResolveTemplate("smart-reasoning", nil)+ if err != nil {+ t.Fatal(err)+ }+ defaultTools := toolsForRun(t.Context(), defaults, in, de)+ if len(defaultTools) != len(defaults.Tools)+len(compiledKnowledgeToolNames) {+ t.Fatalf("default tools lost automatic compilation capabilities: %d", len(defaultTools))+ }+ names := []string{"grep_chunks", "list_chunks"}+ strict, err := ResolveTemplate("smart-reasoning", &Override{Tools: &names})+ if err != nil {+ t.Fatal(err)+ }+ de.probeCalled = false+ selected := toolsForRun(t.Context(), strict, in, de)+ if de.probeCalled {+ t.Error("restricted configuration should not probe compiled capability")+ }+ var got []string+ for _, selectedTool := range selected {+ info, err := selectedTool.Info(t.Context())+ if err != nil {+ t.Fatal(err)+ }+ got = append(got, info.Name)+ }+ if !slices.Equal(got, names) {+ t.Fatalf("compiled tools bypassed restriction: %v", got)+ }+}diff --git a/internal/handler/chat.go b/internal/handler/chat.goindex 4c745bf113..12e27764cb 100644--- a/internal/handler/chat.go+++ b/internal/handler/chat.go@@ -405,6 +405,29 @@ func (h *ChatHandler) GetChat(c *gin.Context) {common.SuccessWithData(c, result, "success")}+// GetAgenticRAGConfig returns defaults and effective Agentic RAG settings.+func (h *ChatHandler) GetAgenticRAGConfig(c *gin.Context) {+ user, errorCode, errorMessage := GetUser(c)+ if errorCode != common.CodeSuccess {+ common.ErrorWithCode(c, errorCode, errorMessage)+ return+ }+ chatID := c.Param("chat_id")+ if chatID == "" {+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeBadRequest, nil, "chat_id is required")+ return+ }+ settings, err := h.chatService.GetAgenticRAGConfig(c.Request.Context(), user.ID, chatID)+ if err != nil {+ if respondPermissionErrorIf(c, err, true) {+ return+ }+ common.ErrorWithCode(c, common.CodeDataError, err.Error())+ return+ }+ common.SuccessWithData(c, settings, "success")+}+// UpdateChat updates a chat by ID using REST PUT semantics.func (h *ChatHandler) UpdateChat(c *gin.Context) {h.updateChatByMethod(c, false)diff --git a/internal/handler/chat_agentic_config_test.go b/internal/handler/chat_agentic_config_test.gonew file mode 100644index 0000000000..e3ee638257--- /dev/null+++ b/internal/handler/chat_agentic_config_test.go@@ -0,0 +1,55 @@+package handler++import (+ "encoding/json/v2"+ "net/http"+ "path/filepath"+ "testing"++ "github.com/gin-gonic/gin"++ "ragflow/internal/common"+ "ragflow/internal/service"+)++func TestGetAgenticRAGConfigHandler(t *testing.T) {+ for _, tc := range []struct {+ name string+ tenantID string+ wantCode common.ErrorCode+ }{+ {name: "owner", tenantID: "user-1", wantCode: common.CodeSuccess},+ {name: "other tenant", tenantID: "other-tenant", wantCode: common.CodeNotFound},+ } {+ t.Run(tc.name, func(t *testing.T) {+ db := setupChatHandlerTestDB(t)+ createChatHandlerTestChat(t, db, "chat-1", tc.tenantID)+ t.Setenv("AGENTIC_RAG_CONFIG", filepath.Join("..", "..", "conf", "agentic_rag.yaml"))+ h := NewChatHandler(service.NewChatService(), service.NewUserService())+ c, w := setupGinContextWithUser("GET", "/api/v1/chats/chat-1/agentic-rag", "")+ c.Params = []gin.Param{{Key: "chat_id", Value: "chat-1"}}++ h.GetAgenticRAGConfig(c)++ if w.Code != http.StatusOK {+ t.Fatalf("HTTP status = %d: %s", w.Code, w.Body.String())+ }+ var response struct {+ Code common.ErrorCode `json:"code"`+ Data map[string]any `json:"data"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatal(err)+ }+ if response.Code != tc.wantCode {+ t.Fatalf("response code = %d, want %d: %s", response.Code, tc.wantCode, w.Body.String())+ }+ if tc.wantCode == common.CodeSuccess && len(response.Data) == 0 {+ t.Fatal("missing settings response")+ }+ if tc.wantCode != common.CodeSuccess && response.Data != nil {+ t.Fatalf("unauthorized response exposes settings: %#v", response.Data)+ }+ })+ }+}diff --git a/internal/router/router.go b/internal/router/router.goindex 17ef76f8f9..288f061aec 100644--- a/internal/router/router.go+++ b/internal/router/router.go@@ -308,6 +308,7 @@ func (r *Router) Setup(engine *gin.Engine) {chats.DELETE("", r.chatHandler.BulkDeleteChats)chats.DELETE("/:chat_id", r.chatHandler.DeleteChat)chats.GET("/:chat_id", r.chatHandler.GetChat)+ chats.GET("/:chat_id/agentic-rag", r.chatHandler.GetAgenticRAGConfig)chats.PUT("/:chat_id", r.chatHandler.UpdateChat)chats.PATCH("/:chat_id", r.chatHandler.PatchChat)chats.GET("/:chat_id/sessions", r.chatSessionHandler.ListChatSessions)diff --git a/internal/service/agentic_config_resolution_test.go b/internal/service/agentic_config_resolution_test.gonew file mode 100644index 0000000000..29b4f9bc00--- /dev/null+++ b/internal/service/agentic_config_resolution_test.go@@ -0,0 +1,59 @@+package service++import (+ "os"+ "path/filepath"+ "testing"++ "ragflow/internal/entity"+)++func TestChatAgenticTemplateResolution(t *testing.T) {+ path := filepath.Join(t.TempDir(), "agentic.yaml")+ if err := os.WriteFile(path, []byte(`templates:+ - id: smart-reasoning+ content: default prompt+ temperature: 0.5+ tools: [grep_chunks, list_chunks, think]+ - id: alternate+ content: alternate prompt+ temperature: 0.2+ tools: [search_chunks, list_chunks]+`), 0600); err != nil {+ t.Fatal(err)+ }+ t.Setenv("AGENTIC_RAG_CONFIG", path)+ chat := &entity.Chat{PromptConfig: entity.JSONMap{+ "system": "standard RAG prompt",+ "agentic_rag": map[string]any{"content": "saved prompt"},+ }}+ for _, tc := range []struct {+ mode string+ temperature float64+ }{{"", 0.5}, {"alternate", 0.2}} {+ t.Run(tc.mode, func(t *testing.T) {+ tmpl, err := resolveChatAgenticTemplate(chat, map[string]any{+ "agent_mode": tc.mode,+ "agentic_rag": map[string]any{"content": "unsaved injection", "tools": []any{"web_search"}},+ })+ if err != nil {+ t.Fatal(err)+ }+ if tmpl.Content != "saved prompt" || tmpl.Temperature == nil || *tmpl.Temperature != tc.temperature {+ t.Fatalf("unexpected resolved template: %+v", tmpl)+ }+ })+ }+ chat.PromptConfig["agentic_rag"] = nil+ tmpl, err := resolveChatAgenticTemplate(chat, nil)+ if err != nil || tmpl.Content != "default prompt" {+ t.Fatalf("reset: %+v, %v", tmpl, err)+ }+ if _, err := resolveChatAgenticTemplate(chat, map[string]any{"agent_mode": "missing"}); err == nil {+ t.Fatal("unknown mode accepted")+ }+ chat.PromptConfig["agentic_rag"] = map[string]any{"tools": []any{"web_search"}}+ if _, err := resolveChatAgenticTemplate(chat, nil); err == nil {+ t.Fatal("invalid stored override accepted")+ }+}diff --git a/internal/service/agentic_pipeline.go b/internal/service/agentic_pipeline.goindex 9b7c17c561..84541db686 100644--- a/internal/service/agentic_pipeline.go+++ b/internal/service/agentic_pipeline.go@@ -44,6 +44,18 @@ const agenticRunTimeout = 15 * time.Minute// operator who removed or renamed the template.const defaultAgenticTemplateID = "smart-reasoning"+func resolveChatAgenticTemplate(chat *entity.Chat, kwargs map[string]interface{}) (agentic_rag.Template, error) {+ mode, _ := kwargs["agent_mode"].(string)+ if mode == "" {+ mode = defaultAgenticTemplateID+ }+ override, err := agentic_rag.ParseOverride(chat.PromptConfig["agentic_rag"])+ if err != nil {+ return agentic_rag.Template{}, err+ }+ return agentic_rag.ResolveTemplate(mode, override)+}+// agenticRag drives ONE conversation turn through the smart-reasoning agent// (internal/agentic_rag): an eino-ADK ReAct explorer whose toolset is the// corpus itself (grep / lexical / semantic locate, list_chunks deep read).@@ -65,6 +77,10 @@ func (s *ChatPipelineService) agenticRag(kwargs map[string]interface{},quote bool,) (<-chan AsyncChatResult, error) {+ tmpl, err := resolveChatAgenticTemplate(chat, kwargs)+ if err != nil {+ return nil, err+ }out := make(chan AsyncChatResult, 16)// Wire the document-metadata resolver the metadata_search tool needs. The// eino agentic_rag package must not import service (service imports it), so@@ -82,10 +98,7 @@ func (s *ChatPipelineService) agenticRag(//// AsyncChat only dispatches here with a non-empty KB scope, so the// citation lookup below is always kb_id-bounded.- mode, _ := kwargs["agent_mode"].(string)- if mode == "" {- mode = defaultAgenticTemplateID- }+ mode := tmpl.IDgo func() {defer close(out)@@ -156,7 +169,7 @@ func (s *ChatPipelineService) agenticRag(// like the regular AsyncChat path does, then let the template pin its// sampling when it declares one (smart-reasoning pins 0.5).chatCfg := BuildChatConfig(chat, kwargs)- if temp := agentic_rag.TemplateTemperature(mode); temp != nil {+ if temp := tmpl.Temperature; temp != nil {pinned := *chatCfgpinned.Temperature = tempchatCfg = &pinned@@ -196,6 +209,7 @@ func (s *ChatPipelineService) agenticRag(SynthModel: synth,Messages: agentMessages,TemplateID: mode,+ Template: &tmpl,TenantID: chat.TenantID,DatasetIDs: chatDatasetIDs(chat),DocIDs: docIDs,diff --git a/internal/service/chat.go b/internal/service/chat.goindex fc58020eb0..f584237e2b 100644--- a/internal/service/chat.go+++ b/internal/service/chat.go@@ -21,6 +21,7 @@ import ("encoding/json""errors""fmt"+ "ragflow/internal/agentic_rag""ragflow/internal/common""ragflow/internal/entity""ragflow/internal/permission"@@ -943,6 +944,9 @@ func (s *ChatService) updateChatREST(ctx context.Context, userID, chatID string,}func validatePromptConfigParameters(promptConfig map[string]interface{}) error {+ if _, err := agentic_rag.ParseOverride(promptConfig["agentic_rag"]); err != nil {+ return err+ }parameters, ok := promptConfig["parameters"].([]interface{})if !ok {return nildiff --git a/internal/service/chat_agentic_config.go b/internal/service/chat_agentic_config.gonew file mode 100644index 0000000000..2bb0c3b119--- /dev/null+++ b/internal/service/chat_agentic_config.go@@ -0,0 +1,21 @@+package service++import (+ "context"++ "ragflow/internal/agentic_rag"+ "ragflow/internal/permission"+)++// GetAgenticRAGConfig resolves the chat's saved override against current defaults.+func (s *ChatService) GetAgenticRAGConfig(ctx context.Context, userID, chatID string) (*agentic_rag.Settings, error) {+ chat, err := s.getChatForOperation(ctx, userID, chatID, permission.OperationRead)+ if err != nil {+ return nil, err+ }+ override, err := agentic_rag.ParseOverride(chat.PromptConfig["agentic_rag"])+ if err != nil {+ return nil, err+ }+ return agentic_rag.GetSettings(ctx, override)+}diff --git a/internal/service/chat_agentic_config_test.go b/internal/service/chat_agentic_config_test.gonew file mode 100644index 0000000000..527c511827--- /dev/null+++ b/internal/service/chat_agentic_config_test.go@@ -0,0 +1,171 @@+package service++import (+ "errors"+ "path/filepath"+ "reflect"+ "slices"+ "strings"+ "testing"++ "ragflow/internal/common"+ "ragflow/internal/dao"+ "ragflow/internal/entity"+ "ragflow/internal/permission"+)++func TestChatAgenticConfigPersistsAndResets(t *testing.T) {+ db := setupChatRESTUpdateServiceTestDB(t)+ createChatRESTUpdateServiceTestChat(t, db, "chat-1", "user-1")+ t.Setenv("AGENTIC_RAG_CONFIG", filepath.Join("..", "..", "conf", "agentic_rag.yaml"))+ svc := NewChatService()+ ctx := t.Context()++ for _, override := range []any{+ map[string]any{"content": "Use this saved instruction", "tools": []any{"grep_chunks", "list_chunks"}},+ map[string]any{"content": "Only content overrides defaults"},+ map[string]any{"tools": []any{"grep_chunks", "list_chunks"}},+ nil,+ } {+ _, err := svc.PatchChat(ctx, "user-1", "chat-1", map[string]any{+ "prompt_config": map[string]any{"agentic_rag": override},+ })+ if err != nil {+ t.Fatalf("PatchChat(%#v): %v", override, err)+ }+ // A new service and DAO read prove this is stored JSON, not process state.+ reloaded := NewChatService()+ chat, err := reloaded.chatDAO.GetByID(ctx, dao.DB, "chat-1")+ if err != nil {+ t.Fatal(err)+ }+ if !reflect.DeepEqual(chat.PromptConfig["agentic_rag"], override) {+ t.Fatalf("persisted override = %#v, want %#v", chat.PromptConfig["agentic_rag"], override)+ }+ if chat.PromptConfig["system"] != "old system" || chat.PromptConfig["quote"] != true {+ t.Fatalf("unrelated settings changed: %#v", chat.PromptConfig)+ }+ settings, err := reloaded.GetAgenticRAGConfig(ctx, "user-1", "chat-1")+ if err != nil || settings == nil {+ t.Fatalf("GetAgenticRAGConfig() = (%#v, %v)", settings, err)+ }+ if override == nil {+ if !settings.UsingDefaults || !reflect.DeepEqual(settings.Effective, settings.Defaults) || settings.Override != nil {+ t.Fatalf("reset did not restore defaults: %#v", settings)+ }+ continue+ }+ object := override.(map[string]any)+ if content, ok := object["content"]; ok {+ if settings.Effective.Content != content {+ t.Fatalf("effective content = %q, want %q", settings.Effective.Content, content)+ }+ } else if settings.Effective.Content != settings.Defaults.Content {+ t.Fatal("tools-only override did not inherit default content")+ }+ if _, hasTools := object["tools"]; !hasTools && !slices.Equal(settings.Effective.Tools, settings.Defaults.Tools) {+ t.Fatal("content-only override did not inherit default tools")+ }+ }+}++func TestChatAgenticConfigCreateAndPut(t *testing.T) {+ setupChatRESTUpdateServiceTestDB(t)+ svc := NewChatService()+ override := map[string]any{"content": "Created instruction", "tools": []any{"grep_chunks", "list_chunks"}}+ result, code, err := svc.Create(t.Context(), "user-1", map[string]any{+ "name": "Agentic configuration",+ "prompt_config": map[string]any{"agentic_rag": override},+ })+ if err != nil || code != common.CodeSuccess {+ t.Fatalf("Create() = (%d, %v)", code, err)+ }+ chatID := result["id"].(string)+ chat, err := svc.chatDAO.GetByID(t.Context(), dao.DB, chatID)+ if err != nil {+ t.Fatal(err)+ }+ if !reflect.DeepEqual(chat.PromptConfig["agentic_rag"], override) {+ t.Fatalf("create did not persist override: %#v", chat.PromptConfig)+ }+ _, err = svc.UpdateChat(t.Context(), "user-1", chatID, map[string]any{+ "prompt_config": map[string]any{"agentic_rag": nil, "system": "replacement"},+ })+ if err != nil {+ t.Fatal(err)+ }+ chat, err = svc.chatDAO.GetByID(t.Context(), dao.DB, chatID)+ if err != nil {+ t.Fatal(err)+ }+ if chat.PromptConfig["agentic_rag"] != nil || chat.PromptConfig["system"] != "replacement" || len(chat.PromptConfig) != 2 {+ t.Fatalf("PUT did not replace prompt config: %#v", chat.PromptConfig)+ }+}++func TestChatAgenticConfigRejectsInvalidWrites(t *testing.T) {+ for name, override := range map[string]any{+ "string": "invalid",+ "array": []any{},+ "prompt type": map[string]any{"content": 42},+ "empty prompt": map[string]any{"content": ""},+ "null prompt": map[string]any{"content": nil},+ "large prompt": map[string]any{"content": strings.Repeat("x", 32769)},+ "tools type": map[string]any{"tools": "grep_chunks"},+ "null tools": map[string]any{"tools": nil},+ "tool type": map[string]any{"tools": []any{42}},+ "empty tools": map[string]any{"tools": []any{}},+ "unknown tool": map[string]any{"tools": []any{"unknown_tool"}},+ "duplicate": map[string]any{"tools": []any{"grep_chunks", "grep_chunks"}},+ "web privilege": map[string]any{"tools": []any{"web_search"}},+ "unknown field": map[string]any{"temperature": 0.4},+ } {+ t.Run(name, func(t *testing.T) {+ db := setupChatRESTUpdateServiceTestDB(t)+ createChatRESTUpdateServiceTestChat(t, db, "chat-1", "user-1")+ svc := NewChatService()+ for _, method := range []string{"create", "put", "patch"} {+ payload := map[string]any{"prompt_config": map[string]any{"agentic_rag": override}}+ var err error+ switch method {+ case "create":+ payload["name"] = "Invalid configuration"+ _, _, err = svc.Create(t.Context(), "user-1", payload)+ case "put":+ _, err = svc.UpdateChat(t.Context(), "user-1", "chat-1", payload)+ case "patch":+ _, err = svc.PatchChat(t.Context(), "user-1", "chat-1", payload)+ }+ if err == nil {+ t.Fatalf("%s accepted invalid override %#v", method, override)+ }+ }+ chat, err := svc.chatDAO.GetByID(t.Context(), dao.DB, "chat-1")+ if err != nil {+ t.Fatal(err)+ }+ if _, exists := chat.PromptConfig["agentic_rag"]; exists {+ t.Fatalf("invalid override was persisted: %#v", chat.PromptConfig)+ }+ var count int64+ if err := db.Model(&entity.Chat{}).Count(&count).Error; err != nil || count != 1 {+ t.Fatalf("invalid create persisted a row: count=%d error=%v", count, err)+ }+ })+ }+}++func TestChatAgenticConfigEnforcesPermissions(t *testing.T) {+ db := setupChatRESTUpdateServiceTestDB(t)+ createChatRESTUpdateServiceTestChat(t, db, "other-chat", "other-tenant")+ svc := NewChatService()+ if _, err := svc.GetAgenticRAGConfig(t.Context(), "user-1", "other-chat"); !errors.Is(err, permission.ErrPermissionDenied) {+ t.Fatalf("cross-tenant read error = %v", err)+ }+ _, err := svc.PatchChat(t.Context(), "user-1", "other-chat", map[string]any{+ "prompt_config": map[string]any{"agentic_rag": map[string]any{"content": "Forbidden"}},+ })+ if !errors.Is(err, permission.ErrPermissionDenied) {+ t.Fatalf("cross-tenant update error = %v", err)+ }+}