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(agent): propagate webhook terminal states (#18758)
Guofang.Tang5827620a61bb
diff --git a/internal/handler/agent.go b/internal/handler/agent.goindex 123b4d4a17..1bcee2a1f6 100644--- a/internal/handler/agent.go+++ b/internal/handler/agent.go@@ -104,6 +104,9 @@ type AgentHandler struct {// miniredis-backed writer so runCanvasPipelineDebug can be exercised without a// live Redis.redisStore task.DebugLogStore+ // webhookTraceAppender records webhook test-run events. Production uses+ // appendWebhookTrace; tests inject a recorder without mutating global Redis.+ webhookTraceAppender func(context.Context, string, time.Time, canvas.RunEvent)// newExecutor builds the pipeline executor for a debug run. Defaults to// task.NewPipelineExecutor; tests inject a fake so the debug path can be// driven without a real canvas/DSL.diff --git a/internal/handler/agent_openai.go b/internal/handler/agent_openai.goindex abb957071c..3ba6439783 100644--- a/internal/handler/agent_openai.go+++ b/internal/handler/agent_openai.go@@ -20,7 +20,6 @@ import ("encoding/json""errors""net/http"- "strings""time""github.com/gin-gonic/gin"@@ -149,7 +148,7 @@ func (h *AgentHandler) streamOpenAICompat(for ev := range events {switch ev.Type {case "error":- message := openAICompatRunEventMessage(ev, "Agent run failed.")+ message := agentRunEventMessage(ev, "Agent run failed.")chunk := newOpenAICompatStreamChunk(completionID, model, "**ERROR**: "+message, "error")chunk.Choices[0].Delta.Error = map[string]string{"message": message,@@ -160,12 +159,12 @@ func (h *AgentHandler) streamOpenAICompat(returncase "waiting_for_user":chunk := newOpenAICompatStreamChunk(completionID, model, nil, "waiting_for_user")- chunk.Choices[0].Delta.WaitingForUser = openAICompatWaitingForUser(ev)+ chunk.Choices[0].Delta.WaitingForUser = agentWaitingForUser(ev)chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)_ = writeOpenAICompatSSE(c, chunk)returncase "cancelled":- message := openAICompatRunEventMessage(ev, "Agent run was cancelled.")+ message := agentRunEventMessage(ev, "Agent run was cancelled.")chunk := newOpenAICompatStreamChunk(completionID, model, nil, "cancelled")chunk.Choices[0].Delta.Cancelled = map[string]string{"message": message}chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)@@ -226,24 +225,16 @@ func collectOpenAICompatCompletion(if ev.Type == "error" {return openAICompatCompletion{}, common.NewCodedError(common.CodeServerError,- openAICompatRunEventMessage(ev, "Agent run failed."),+ agentRunEventMessage(ev, "Agent run failed."),)}if ev.Type == "waiting_for_user" {- waiting := openAICompatWaitingForUser(ev)- message := "Agent is waiting for user input."- if waiting.CpnID != "" {- message += " cpn_id: " + waiting.CpnID- }- if waiting.Tips != "" {- message += " " + waiting.Tips- }- return openAICompatCompletion{}, common.NewCodedError(common.CodeConflict, message)+ return openAICompatCompletion{}, common.NewCodedError(common.CodeConflict, agentWaitingForUserMessage(ev))}if ev.Type == "cancelled" {return openAICompatCompletion{}, common.NewCodedError(common.CodeConflict,- openAICompatRunEventMessage(ev, "Agent run was cancelled."),+ agentRunEventMessage(ev, "Agent run was cancelled."),)}if ev.Type != "message" && ev.Type != "message_end" {@@ -324,30 +315,6 @@ func openAICompatUsageForCompletion(promptTokens, completionTokens int) *openAIC}}-func openAICompatRunEventMessage(ev canvas.RunEvent, fallback string) string {- var payload canvas.ErrorEvent- if err := json.Unmarshal([]byte(ev.Data), &payload); err == nil {- if payload.Kind == canvas.RunErrorKindInternal {- return canvas.InternalRunErrorMessage- }- if payload.Message != "" {- return payload.Message- }- }- if message := strings.TrimSpace(ev.Data); message != "" {- return message- }- return fallback-}--func openAICompatWaitingForUser(ev canvas.RunEvent) canvas.WaitingForUserEvent {- var waiting canvas.WaitingForUserEvent- if err := json.Unmarshal([]byte(ev.Data), &waiting); err != nil {- return canvas.WaitingForUserEvent{}- }- return waiting-}-func writeOpenAICompatSSE(c *gin.Context, payload any) error {data, err := json.Marshal(payload)if err != nil {diff --git a/internal/handler/agent_run_event.go b/internal/handler/agent_run_event.gonew file mode 100644index 0000000000..3f9c12fc6b--- /dev/null+++ b/internal/handler/agent_run_event.go@@ -0,0 +1,58 @@+// 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 handler++import (+ "encoding/json"+ "strings"++ "ragflow/internal/agent/canvas"+)++func agentRunEventMessage(ev canvas.RunEvent, fallback string) string {+ var payload canvas.ErrorEvent+ if err := json.Unmarshal([]byte(ev.Data), &payload); err == nil {+ if payload.Kind == canvas.RunErrorKindInternal {+ return canvas.InternalRunErrorMessage+ }+ if payload.Message != "" {+ return payload.Message+ }+ }+ if message := strings.TrimSpace(ev.Data); message != "" {+ return message+ }+ return fallback+}++func agentWaitingForUser(ev canvas.RunEvent) canvas.WaitingForUserEvent {+ var waiting canvas.WaitingForUserEvent+ if err := json.Unmarshal([]byte(ev.Data), &waiting); err != nil {+ return canvas.WaitingForUserEvent{}+ }+ return waiting+}++func agentWaitingForUserMessage(ev canvas.RunEvent) string {+ waiting := agentWaitingForUser(ev)+ message := "Agent is waiting for user input."+ if waiting.CpnID != "" {+ message += " cpn_id: " + waiting.CpnID+ }+ if waiting.Tips != "" {+ message += " " + waiting.Tips+ }+ return message+}diff --git a/internal/handler/agent_webhook.go b/internal/handler/agent_webhook.goindex cff89ebe53..4b73cb3a3b 100644--- a/internal/handler/agent_webhook.go+++ b/internal/handler/agent_webhook.go@@ -520,7 +520,8 @@ func (h *AgentHandler) runWebhookDetached(zap.String("canvas", cv.ID),zap.Error(err))if isTest {- appendWebhookTrace(ctx, cv.ID, startTs, canvas.RunEvent{Type: "error", SessionID: sessionID, Data: mustJSON(map[string]any{"message": err.Error()})})+ h.appendWebhookRunTrace(ctx, cv.ID, startTs, webhookStartErrorEvent(err, sessionID))+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, false)}return}@@ -528,10 +529,20 @@ func (h *AgentHandler) runWebhookDetached(if ev.SessionID == "" {ev.SessionID = sessionID}+ terminal := isWebhookTerminalEvent(ev)if isTest {- appendWebhookTrace(ctx, cv.ID, startTs, ev)+ h.appendWebhookRunTrace(ctx, cv.ID, startTs, sanitizeWebhookTraceEvent(ev))+ }+ if terminal {+ if isTest {+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, false)+ }+ return}}+ if isTest {+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, true)+ }}// runWebhookSync drives the canvas in the non-Immediately (streaming)@@ -552,17 +563,13 @@ func (h *AgentHandler) runWebhookSync(ctx = service.WithAgentSessionID(ctx, sessionID)events, err := h.loader.RunAgentWithWebhook(ctx, cv.UserID, cv.ID, payload)if err != nil {+ errorEvent := webhookStartErrorEvent(err, sessionID)if isTest {- appendWebhookTrace(ctx, cv.ID, startTs, canvas.RunEvent{Type: "error", SessionID: sessionID, Data: mustJSON(map[string]any{"message": err.Error()})})- appendWebhookTrace(ctx, cv.ID, startTs, canvas.RunEvent{Type: "finished", SessionID: sessionID, Data: mustJSON(map[string]any{"success": false})})+ h.appendWebhookRunTrace(ctx, cv.ID, startTs, errorEvent)+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, false)}- return webhookSyncResult{status: http.StatusBadRequest, body: gin.H{- "code": 400,- "message": err.Error(),- "success": false,- "task_id": sessionID,- "session_id": sessionID,- }}+ code, message := mapAgentError(err)+ return newWebhookFailureResult(webhookHTTPStatusForAgentError(code, err), message, sessionID)}contents := []string{}@@ -570,8 +577,15 @@ func (h *AgentHandler) runWebhookSync(if ev.SessionID == "" {ev.SessionID = sessionID}+ if result, terminal := webhookTerminalResult(ev, sessionID); terminal {+ if isTest {+ h.appendWebhookRunTrace(ctx, cv.ID, startTs, sanitizeWebhookTraceEvent(ev))+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, false)+ }+ return result+ }if isTest {- appendWebhookTrace(ctx, cv.ID, startTs, ev)+ h.appendWebhookRunTrace(ctx, cv.ID, startTs, ev)}switch ev.Type {case "message":@@ -602,7 +616,7 @@ func (h *AgentHandler) runWebhookSync(}final := strings.Join(contents, "")if isTest {- appendWebhookTrace(ctx, cv.ID, startTs, canvas.RunEvent{Type: "finished", SessionID: sessionID, Data: mustJSON(map[string]any{"success": true})})+ h.appendWebhookFinishedTrace(ctx, cv.ID, startTs, sessionID, true)}return webhookSyncResult{status: status, body: gin.H{"message": final,@@ -613,6 +627,112 @@ func (h *AgentHandler) runWebhookSync(}}}+func webhookStartErrorEvent(err error, sessionID string) canvas.RunEvent {+ code, message := mapAgentError(err)+ payload := canvas.ErrorEvent{Message: message}+ if code == common.CodeServerError {+ payload.Kind = canvas.RunErrorKindInternal+ }+ return canvas.RunEvent{+ Type: "error",+ SessionID: sessionID,+ Data: mustJSON(payload),+ }+}++func webhookHTTPStatusForAgentError(code common.ErrorCode, err error) int {+ switch {+ case code == common.CodeServerError:+ return http.StatusInternalServerError+ case errors.Is(err, service.ErrAgentSessionBusy):+ return http.StatusConflict+ case code == common.CodeOperatingError:+ return http.StatusForbidden+ default:+ return http.StatusBadRequest+ }+}++func webhookTerminalResult(ev canvas.RunEvent, sessionID string) (webhookSyncResult, bool) {+ switch ev.Type {+ case "error":+ return newWebhookFailureResult(+ http.StatusInternalServerError,+ agentRunEventMessage(ev, "Agent run failed."),+ sessionID,+ ), true+ case "cancelled":+ return newWebhookFailureResult(+ http.StatusConflict,+ agentRunEventMessage(ev, "Agent run was cancelled."),+ sessionID,+ ), true+ case "waiting_for_user":+ return newWebhookFailureResult(+ http.StatusConflict,+ agentWaitingForUserMessage(ev),+ sessionID,+ ), true+ default:+ return webhookSyncResult{}, false+ }+}++func newWebhookFailureResult(status int, message, sessionID string) webhookSyncResult {+ return webhookSyncResult{status: status, body: gin.H{+ "code": status,+ "message": message,+ "success": false,+ "task_id": sessionID,+ "session_id": sessionID,+ }}+}++func isWebhookTerminalEvent(ev canvas.RunEvent) bool {+ switch ev.Type {+ case "error", "cancelled", "waiting_for_user":+ return true+ default:+ return false+ }+}++func sanitizeWebhookTraceEvent(ev canvas.RunEvent) canvas.RunEvent {+ if ev.Type != "error" {+ return ev+ }+ var payload canvas.ErrorEvent+ if err := json.Unmarshal([]byte(ev.Data), &payload); err != nil || payload.Kind != canvas.RunErrorKindInternal {+ return ev+ }+ payload.Message = canvas.InternalRunErrorMessage+ ev.Data = mustJSON(payload)+ return ev+}++func (h *AgentHandler) appendWebhookRunTrace(+ ctx context.Context, agentID string, startTs time.Time, ev canvas.RunEvent,+) {+ if h.webhookTraceAppender != nil {+ h.webhookTraceAppender(ctx, agentID, startTs, ev)+ return+ }+ appendWebhookTrace(ctx, agentID, startTs, ev)+}++func (h *AgentHandler) appendWebhookFinishedTrace(+ ctx context.Context, agentID string, startTs time.Time, sessionID string, success bool,+) {+ h.appendWebhookRunTrace(ctx, agentID, startTs, canvas.RunEvent{+ Type: "finished",+ SessionID: sessionID,+ Data: mustJSON(map[string]any{+ "elapsed_time": time.Since(startTs).Seconds(),+ "success": success,+ }),+ })+}+// mustJSON marshals v to a JSON object string. Used by trace appenders;// panics on marshal failure (acceptable because we only marshal// statically-typed map[string]any values).diff --git a/internal/handler/agent_webhook_test.go b/internal/handler/agent_webhook_test.goindex 624a23f080..7408cdab3a 100644--- a/internal/handler/agent_webhook_test.go+++ b/internal/handler/agent_webhook_test.go@@ -19,10 +19,12 @@ package handlerimport ("context""encoding/json"+ "errors""net/http""net/http/httptest""strings""testing"+ "time""github.com/gin-gonic/gin"@@ -30,6 +32,7 @@ import ("ragflow/internal/common""ragflow/internal/dao""ragflow/internal/entity"+ "ragflow/internal/service")// fakeCanvasLoader is a stand-in canvasLoader for webhook tests. It@@ -39,6 +42,7 @@ import (type fakeCanvasLoader struct {canvas *entity.UserCanvaserr error+ runErr errorevents []canvas.RunEvent}@@ -50,6 +54,9 @@ func (f *fakeCanvasLoader) LoadCanvasByID(_ context.Context, _, _ string) (*enti}func (f *fakeCanvasLoader) RunAgentWithWebhook(_ context.Context, _, _ string, _ map[string]any) (<-chan canvas.RunEvent, error) {+ if f.runErr != nil {+ return nil, f.runErr+ }out := make(chan canvas.RunEvent, len(f.events))for _, e := range f.events {out <- e@@ -487,6 +494,197 @@ func TestWebhook_DefaultModeAggregatesContent(t *testing.T) {}}+func TestWebhook_DefaultModePropagatesTerminalEvents(t *testing.T) {+ tests := []struct {+ name string+ event canvas.RunEvent+ wantStatus int+ wantMessage string+ forbidden string+ }{+ {+ name: "public error",+ event: canvas.RunEvent{Type: "error", Data: `{"message":"retrieval backend failed"}`},+ wantStatus: http.StatusInternalServerError,+ wantMessage: "retrieval backend failed",+ },+ {+ name: "internal error",+ event: canvas.RunEvent{Type: "error", Data: `{"message":"postgres password=secret","kind":"internal"}`},+ wantStatus: http.StatusInternalServerError,+ wantMessage: canvas.InternalRunErrorMessage,+ forbidden: "password=secret",+ },+ {+ name: "cancelled",+ event: canvas.RunEvent{Type: "cancelled", Data: `{"message":"Agent run was cancelled."}`},+ wantStatus: http.StatusConflict,+ wantMessage: "Agent run was cancelled.",+ },+ {+ name: "waiting for user",+ event: canvas.RunEvent{Type: "waiting_for_user", Data: `{"cpn_id":"input-1","tips":"Please choose an option."}`},+ wantStatus: http.StatusConflict,+ wantMessage: "Please choose an option.",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ cv := makeWebhookCanvas("c1", "u-1", "Webhook", map[string]any{+ "execution_mode": "Streaming",+ })+ h := &AgentHandler{loader: &fakeCanvasLoader{canvas: cv, events: []canvas.RunEvent{tt.event}}}+ var trace []canvas.RunEvent+ h.webhookTraceAppender = func(_ context.Context, _ string, _ time.Time, ev canvas.RunEvent) {+ trace = append(trace, ev)+ }+ c, w := webhookCtx("POST", "/api/v1/agents/c1/webhook/test", `{}`, "application/json")++ h.Webhook(c)++ if w.Code != tt.wantStatus {+ t.Fatalf("status = %d, want %d; body=%s", w.Code, tt.wantStatus, w.Body.String())+ }+ var body struct {+ Message string `json:"message"`+ Success bool `json:"success"`+ Code int `json:"code"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {+ t.Fatalf("decode: %v", err)+ }+ if body.Success {+ t.Fatal("terminal event must not be reported as success")+ }+ if body.Code != tt.wantStatus {+ t.Errorf("code = %d, want %d", body.Code, tt.wantStatus)+ }+ if !strings.Contains(body.Message, tt.wantMessage) {+ t.Errorf("message = %q, want contains %q", body.Message, tt.wantMessage)+ }+ if tt.forbidden != "" && strings.Contains(w.Body.String(), tt.forbidden) {+ t.Fatalf("response leaked internal error details: %s", w.Body.String())+ }+ if tt.forbidden != "" {+ for _, ev := range trace {+ if strings.Contains(ev.Data, tt.forbidden) {+ t.Fatalf("trace leaked internal error details: %+v", trace)+ }+ }+ }+ assertWebhookFinishedTrace(t, trace, false)+ })+ }+}++func TestWebhook_DefaultModeRedactsStartError(t *testing.T) {+ cv := makeWebhookCanvas("c1", "u-1", "Webhook", map[string]any{+ "execution_mode": "Streaming",+ })+ startErr := errors.Join(errors.New("dial mysql password=secret"), service.ErrAgentStorageError)+ h := &AgentHandler{loader: &fakeCanvasLoader{canvas: cv, runErr: startErr}}+ var trace []canvas.RunEvent+ h.webhookTraceAppender = func(_ context.Context, _ string, _ time.Time, ev canvas.RunEvent) {+ trace = append(trace, ev)+ }+ c, w := webhookCtx("POST", "/api/v1/agents/c1/webhook/test", `{}`, "application/json")++ h.Webhook(c)++ if w.Code != http.StatusInternalServerError {+ t.Fatalf("status = %d, want 500; body=%s", w.Code, w.Body.String())+ }+ if !strings.Contains(w.Body.String(), canvas.InternalRunErrorMessage) {+ t.Errorf("body missing safe internal error message: %s", w.Body.String())+ }+ if strings.Contains(w.Body.String(), "password=secret") {+ t.Fatalf("response leaked internal error details: %s", w.Body.String())+ }+ if len(trace) == 0 || strings.Contains(trace[0].Data, "password=secret") {+ t.Fatalf("trace leaked internal error details: %+v", trace)+ }+ assertWebhookFinishedTrace(t, trace, false)+}++func TestRunWebhookDetachedAppendsFinishedTrace(t *testing.T) {+ tests := []struct {+ name string+ events []canvas.RunEvent+ runErr error+ wantSuccess bool+ forbidden string+ }{+ {+ name: "success",+ events: []canvas.RunEvent{+ {Type: "message", Data: `{"content":"done"}`},+ {Type: "done"},+ },+ wantSuccess: true,+ },+ {+ name: "runner error",+ events: []canvas.RunEvent{{Type: "error", Data: `{"message":"LLM failed"}`}},+ wantSuccess: false,+ },+ {+ name: "start error",+ runErr: errors.Join(errors.New("redis password=secret"), service.ErrAgentStorageError),+ wantSuccess: false,+ forbidden: "password=secret",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ cv := makeWebhookCanvas("c1", "u-1", "Webhook", nil)+ h := &AgentHandler{loader: &fakeCanvasLoader{canvas: cv, events: tt.events, runErr: tt.runErr}}+ var trace []canvas.RunEvent+ h.webhookTraceAppender = func(_ context.Context, _ string, _ time.Time, ev canvas.RunEvent) {+ trace = append(trace, ev)+ }++ h.runWebhookDetached(t.Context(), cv, map[string]any{}, true, time.Now())++ assertWebhookFinishedTrace(t, trace, tt.wantSuccess)+ if tt.forbidden != "" {+ for _, ev := range trace {+ if strings.Contains(ev.Data, tt.forbidden) {+ t.Fatalf("trace leaked internal error details: %+v", trace)+ }+ }+ }+ })+ }+}++func assertWebhookFinishedTrace(t *testing.T, events []canvas.RunEvent, wantSuccess bool) {+ t.Helper()+ if len(events) == 0 || events[len(events)-1].Type != "finished" {+ t.Fatalf("trace must end with finished; trace=%+v", events)+ }+ finishedCount := 0+ for _, ev := range events {+ if ev.Type != "finished" {+ continue+ }+ finishedCount+++ var data struct {+ Success bool `json:"success"`+ }+ if err := json.Unmarshal([]byte(ev.Data), &data); err != nil {+ t.Fatalf("decode finished trace: %v; data=%q", err, ev.Data)+ }+ if data.Success != wantSuccess {+ t.Errorf("finished success = %v, want %v", data.Success, wantSuccess)+ }+ }+ if finishedCount != 1 {+ t.Fatalf("finished event count = %d, want 1; trace=%+v", finishedCount, events)+ }+}+// TestWebhook_InvalidResponseStatusRange rejects bad config (status 500).func TestWebhook_InvalidResponseStatusRange(t *testing.T) {cv := makeWebhookCanvas("c1", "u-1", "Webhook", map[string]any{