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
fix: add json output alias on Retrieval node (#20394)
ciel9766c8c5483b
diff --git a/internal/agent/canvas/retrieval_json_output_test.go b/internal/agent/canvas/retrieval_json_output_test.gonew file mode 100644index 0000000000..0a5d4c5ef4--- /dev/null+++ b/internal/agent/canvas/retrieval_json_output_test.go@@ -0,0 +1,104 @@+//+// 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.+//++// retrieval_json_output_test.go — end-to-end regression for the Retrieval+// node's `json` output on a zero-hit search.+//+// The tool envelope drops its chunk array when the search returns nothing, so+// the node's `json` output used to be missing outright and a downstream+// {{<id>@json}} template failed the run with "Can't find variable". This test+// drives a full Begin → Retrieval → Message canvas so the component's output+// contract and the template resolution are exercised together — the failure+// the Agent chat surfaced.+package canvas++import (+ "context"+ "testing"++ // Blank-import to trigger component init(), which installs the real+ // component factory (same wiring as loop_semantics_test.go). Without it+ // BuildWorkflow falls back to its placeholder echo body and the canvas+ // never invokes the real Retrieval / Message components.+ _ "ragflow/internal/agent/component"+ "ragflow/internal/agent/runtime"++ "gorm.io/gorm"+)++type zeroHitRetrievalService struct{}++func (zeroHitRetrievalService) Search(context.Context, *gorm.DB, runtime.RetrievalRequest) ([]runtime.RetrievalChunk, error) {+ return nil, nil+}++func TestRetrievalJSONOutputResolvesOnEmptySearch(t *testing.T) {+ previous := runtime.GetRetrievalService()+ runtime.SetRetrievalService(zeroHitRetrievalService{})+ t.Cleanup(func() { runtime.SetRetrievalService(previous) })++ dsl := &Canvas{+ Components: map[string]CanvasComponent{+ "begin": {+ Obj: CanvasComponentObj{ComponentName: "Begin", Params: map[string]any{}},+ Downstream: []string{"retrieval_0"},+ },+ "retrieval_0": {+ Obj: CanvasComponentObj{ComponentName: "Retrieval", Params: map[string]any{+ "retrieval_from": "dataset",+ "kb_ids": []any{"kb-1"},+ "query": "love",+ }},+ Upstream: []string{"begin"},+ Downstream: []string{"message_0"},+ },+ "message_0": {+ Obj: CanvasComponentObj{ComponentName: "Message", Params: map[string]any{+ "text": "chunks: {retrieval_0@json}",+ }},+ Upstream: []string{"retrieval_0"},+ Downstream: []string{},+ },+ },+ Path: []string{"begin", "retrieval_0", "message_0"},+ }++ ctx := t.Context()+ compiled, err := Compile(ctx, dsl)+ if err != nil {+ t.Fatalf("Compile: %v", err)+ }+ state := NewCanvasState("run-retrieval-json", "task-retrieval-json")+ if _, runErr := compiled.Workflow.Invoke(withState(ctx, state), map[string]any{"query": "love"}); runErr != nil {+ t.Fatalf("Invoke: %v", runErr)+ }++ chunks, err := state.GetVar("retrieval_0@json")+ if err != nil {+ t.Fatalf("GetVar(retrieval_0@json): %v", err)+ }+ values, ok := chunks.([]any)+ if !ok || len(values) != 0 {+ t.Fatalf("retrieval_0@json = %#v, want an empty array", chunks)+ }+ content, err := state.GetVar("message_0@content")+ if err != nil {+ t.Fatalf("GetVar(message_0@content): %v", err)+ }+ if content != "chunks: []" {+ t.Fatalf("message_0@content = %#v, want %q", content, "chunks: []")+ }+}diff --git a/internal/agent/component/retrieval_empty_response_test.go b/internal/agent/component/retrieval_empty_response_test.goindex d65686e3ee..b75c5c3b1f 100644--- a/internal/agent/component/retrieval_empty_response_test.go+++ b/internal/agent/component/retrieval_empty_response_test.go@@ -18,6 +18,7 @@ package componentimport ("context"+ "reflect""testing"agenttool "ragflow/internal/agent/tool"@@ -31,12 +32,59 @@ func (emptyRetrievalService) Search(context.Context, *gorm.DB, agenttool.Retrievreturn []agenttool.RetrievalChunk{}, nil}-func TestRetrievalComponent_PreservesConfiguredEmptyResponse(t *testing.T) {+// assertEmptyRetrievalOutputs pins the declared outputs of a Retrieval node+// that produced no chunks: both names must resolve to an empty array so a+// downstream {{<id>@json}} / {{<id>@chunks}} template does not fail with+// "Can't find variable".+func assertEmptyRetrievalOutputs(t *testing.T, output map[string]any) {+ t.Helper()+ for _, key := range []string{"json", "chunks"} {+ value, ok := output[key].([]any)+ if !ok {+ t.Fatalf("%s = %#v, want an empty array", key, output[key])+ }+ if len(value) != 0 {+ t.Fatalf("%s = %#v, want an empty array", key, value)+ }+ }+}++// TestRetrievalComponent_EmptyResultPreservesConfiguredEmptyResponse covers+// the tool's early-return envelope (no retrieval_from configured): the+// configured empty_response reaches formalized_content and the chunk outputs+// stay resolvable.+func TestRetrievalComponent_EmptyResultPreservesConfiguredEmptyResponse(t *testing.T) {+ previous := agenttool.GetRetrievalService()+ agenttool.SetRetrievalService(emptyRetrievalService{})+ t.Cleanup(func() { agenttool.SetRetrievalService(previous) })++ component, err := newRetrievalComponent(map[string]any{+ "empty_response": "No relevant content.",+ })+ if err != nil {+ t.Fatalf("newRetrievalComponent: %v", err)+ }+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "love"})+ if err != nil {+ t.Fatalf("Invoke: %v", err)+ }+ if output["formalized_content"] != "No relevant content." {+ t.Fatalf("formalized_content = %#v", output["formalized_content"])+ }+ assertEmptyRetrievalOutputs(t, output)+}++// TestRetrievalComponent_ZeroHitsExposeChunkOutputs covers the search path+// that returns no hit: the tool envelope drops its `chunks` key (omitempty),+// which previously left `json` unset and broke every downstream reference.+func TestRetrievalComponent_ZeroHitsExposeChunkOutputs(t *testing.T) {previous := agenttool.GetRetrievalService()agenttool.SetRetrievalService(emptyRetrievalService{})t.Cleanup(func() { agenttool.SetRetrievalService(previous) })component, err := newRetrievalComponent(map[string]any{+ "retrieval_from": "dataset",+ "kb_ids": []any{"kb-1"},"empty_response": "No relevant content.",})if err != nil {@@ -49,4 +97,65 @@ func TestRetrievalComponent_PreservesConfiguredEmptyResponse(t *testing.T) {if output["formalized_content"] != "No relevant content." {t.Fatalf("formalized_content = %#v", output["formalized_content"])}+ assertEmptyRetrievalOutputs(t, output)+}++// TestRetrievalComponent_MissingDatasetExposeChunkOutputs covers the+// no-dataset-selected early return: the node reports the configuration error+// while still resolving every declared output.+func TestRetrievalComponent_MissingDatasetExposeChunkOutputs(t *testing.T) {+ component, err := newRetrievalComponent(map[string]any{+ "retrieval_from": "dataset",+ })+ if err != nil {+ t.Fatalf("newRetrievalComponent: %v", err)+ }+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "love"})+ if err != nil {+ t.Fatalf("Invoke: %v", err)+ }+ if output["_ERROR"] != "No dataset is selected." {+ t.Fatalf("_ERROR = %#v", output["_ERROR"])+ }+ if output["formalized_content"] != "" {+ t.Fatalf("formalized_content = %#v, want empty string", output["formalized_content"])+ }+ assertEmptyRetrievalOutputs(t, output)+}++// TestRetrievalComponent_JSONOutputMirrorsChunks pins the alias itself: `json`+// is the DSL-declared name for the same chunk array the tool reports as+// `chunks`, so downstream templates see identical data under either name.+func TestRetrievalComponent_JSONOutputMirrorsChunks(t *testing.T) {+ previous := agenttool.GetRetrievalService()+ agenttool.SetSimpleRetrievalService()+ t.Cleanup(func() { agenttool.SetRetrievalService(previous) })++ component, err := newRetrievalComponent(map[string]any{+ "retrieval_from": "dataset",+ "kb_ids": []any{"kb-1"},+ "top_n": 1,+ })+ if err != nil {+ t.Fatalf("newRetrievalComponent: %v", err)+ }+ output, err := component.Invoke(t.Context(), nil, map[string]any{"query": "ragflow"})+ if err != nil {+ t.Fatalf("Invoke: %v", err)+ }+ chunks, ok := output["chunks"].([]any)+ if !ok || len(chunks) != 1 {+ t.Fatalf("chunks = %#v, want one chunk", output["chunks"])+ }+ first, ok := chunks[0].(map[string]any)+ if !ok || first["id"] != "simple-0" || first["content"] == "" {+ t.Fatalf("chunk payload = %#v", chunks[0])+ }+ jsonOutput, ok := output["json"].([]any)+ if !ok {+ t.Fatalf("json = %#v, want an array", output["json"])+ }+ if !reflect.DeepEqual(jsonOutput, chunks) {+ t.Fatalf("json = %#v, want the chunks array %#v", jsonOutput, chunks)+ }}diff --git a/internal/agent/component/universe_a_wrappers.go b/internal/agent/component/universe_a_wrappers.goindex 2deb391735..2aec9db2b6 100644--- a/internal/agent/component/universe_a_wrappers.go+++ b/internal/agent/component/universe_a_wrappers.go@@ -195,6 +195,7 @@ func (c *retrievalComponent) GetInputForm() map[string]any {func (c *retrievalComponent) Outputs() map[string]string {return map[string]string{"formalized_content": "Rendered chunks for downstream LLM prompts.",+ "json": "Chunk payloads under the DSL-declared output name (Array<Object>).","chunks": "Raw chunk payloads (id, document_id, content, score).",}}@@ -218,7 +219,10 @@ func (c *retrievalComponent) Invoke(ctx context.Context, db *gorm.DB, inputs mapemptySelection = len(ids) == 0}if emptySelection {- return map[string]any{"_ERROR": "No dataset is selected."}, nil+ return normalizeRetrievalOutputs(map[string]any{+ "_ERROR": "No dataset is selected.",+ "formalized_content": "",+ }), nil}}common.Debug("agent retrieval component: invoke",@@ -233,13 +237,9 @@ func (c *retrievalComponent) Invoke(ctx context.Context, db *gorm.DB, inputs mapcommon.Debug("agent retrieval component: output",zap.String("tool_output", out),)- decoded := parseToolEnvelope(out)- if chunks, ok := decoded["chunks"]; ok {- if _, has := decoded["json"]; !has {- decoded["json"] = chunks- }- }- return decoded, nil++ return normalizeRetrievalOutputs(parseToolEnvelope(out)), nil+}func (c *retrievalComponent) Stream(_ context.Context, _ *gorm.DB, _ map[string]any) (<-chan map[string]any, error) {@@ -254,6 +254,33 @@ func (c *retrievalComponent) Stream(_ context.Context, _ *gorm.DB, _ map[string]return nil, nil}+// normalizeRetrievalOutputs pins the Retrieval node's chunk array under both+// output names the canvas resolves: `json` (the DSL-declared output, typed+// Array<Object> by the frontend) and `chunks` (the tool envelope's name).+//+// The tool marshals its envelope with `chunks` tagged omitempty, so a+// zero-hit search drops the key outright, as does every early-return+// envelope (empty query, search error, GraphRAG opt-in) and+// parseToolEnvelope's `_raw` fallback. Without this, a downstream+// {{<id>@json}} reference dies in ResolveTemplate with "Can't find variable"+// instead of seeing the empty result set. Emptying the array — rather than+// leaving the key absent or nil — is what every other tool-backed search+// component emits unconditionally, and it is the shape callers iterate over.+func normalizeRetrievalOutputs(decoded map[string]any) map[string]any {+ if decoded == nil {+ decoded = make(map[string]any, 3)+ }+ chunks, ok := decoded["chunks"]+ if !ok || chunks == nil {+ chunks = []any{}+ }+ decoded["chunks"] = chunks+ if existing, has := decoded["json"]; !has || existing == nil {+ decoded["json"] = chunks+ }+ return decoded+}+// applyDefaults folds the node-level params into the per-call// input map. Per-call values always win; node-level values fill// the gaps. This mirrors Python's RetrievalParam semantics where