Skip to content

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

fix(agent): propagate webhook terminal states (#18758)

Guofang.Tang5827620a61bb
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 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.go
index 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(
return
case "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)
return
case "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.go
new file mode 100644
index 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.go
index 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.go
index 624a23f080..7408cdab3a 100644
--- a/internal/handler/agent_webhook_test.go
+++ b/internal/handler/agent_webhook_test.go
@@ -19,10 +19,12 @@ package handler
import (
"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.UserCanvas
err error
+ runErr error
events []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{