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(agent): support OpenAI-compatible responses (#18316)
Guofang.Tang4304a3b7c6d3
diff --git a/internal/handler/agent.go b/internal/handler/agent.goindex 761f25dd02..f08ae37895 100644--- a/internal/handler/agent.go+++ b/internal/handler/agent.go@@ -1059,12 +1059,11 @@ func (h *AgentHandler) DeleteAgentSession(c *gin.Context) {// defaults to non-streaming): collects all canvas events and returns a// plain JSON response with `data.content` set to the concatenated// message content (matching Python's final_ans["data"]["content"]).-// - Openai-compatible path: requires `messages` (a non-empty list with at-// least one user message is needed to derive the question). The full-// OpenAI wire framing (delta + reference + token counts — see-// `completion_openai` at api/db/services/canvas_service.py:378-479) is-// still a Phase 5 TODO; until then the openai-compat branches return a-// hardcoded "hello" stub so the validation contracts keep passing.+// - OpenAI-compatible path: requires `messages` and returns the direct+// OpenAI chat-completion wire format, including streaming deltas,+// references, token usage, and the `[DONE]` terminator. The protocol+// adapter lives in agent_openai.go so the regular Agent event contract+// remains unchanged.type agentChatCompletionsRequest struct {AgentID string `json:"agent_id"`Query string `json:"query"`@@ -1126,8 +1125,9 @@ func extractLastUserContent(messages []map[string]interface{}) string {if role != "user" {continue}- if c, _ := messages[i]["content"].(string); c != "" {- return c+ content, err := service.NormalizeOpenAIMessageContent(messages[i]["content"])+ if err == nil && content != "" {+ return content}}return ""@@ -1235,19 +1235,8 @@ func (h *AgentHandler) AgentChatCompletions(c *gin.Context) {zap.Int("messages_count", len(req.Messages)),)- // TODO(phase5-openai-framing): the openai-compat branches below are- // stubs. They keep the existing "choices"-shape contract for the- // openai-compat tests, but the production wire format must mirror- // api/db/services/canvas_service.py:378-479 (`completion_openai`):- // per-token `delta.content`, cumulative token counts, `[DONE]`- // terminator, `reference` attached to the final choice. Land that- // once the chat path needs to interop with OpenAI clients.if req.OpenAICompat {- common.SuccessWithData(c, gin.H{- "choices": []map[string]interface{}{- {"message": gin.H{"content": "hello"}},- },- }, "success")+ h.handleOpenAICompat(c, user, &req)return}diff --git a/internal/handler/agent_openai.go b/internal/handler/agent_openai.gonew file mode 100644index 0000000000..a4c7155253--- /dev/null+++ b/internal/handler/agent_openai.go@@ -0,0 +1,398 @@+//+// 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"+ "errors"+ "net/http"+ "strings"+ "time"++ "github.com/gin-gonic/gin"++ "ragflow/internal/agent/canvas"+ "ragflow/internal/common"+ "ragflow/internal/entity"+ "ragflow/internal/service"+ "ragflow/internal/tokenizer"+ "ragflow/internal/utility"+)++// openAICompatUsage mirrors the usage object emitted by the Python+// completion_openai implementation. Agent runs can contain multiple LLM+// calls, so completion tokens are accumulated from the message deltas rather+// than inferred from the number of RunEvent frames.+type openAICompatUsage struct {+ PromptTokens int `json:"prompt_tokens"`+ CompletionTokens int `json:"completion_tokens"`+ TotalTokens int `json:"total_tokens"`+ CompletionTokensDetails openAICompatCompletionTokenDetails `json:"completion_tokens_details"`+}++type openAICompatCompletionTokenDetails struct {+ ReasoningTokens int `json:"reasoning_tokens"`+ AcceptedPredictionTokens int `json:"accepted_prediction_tokens"`+ RejectedPredictionTokens int `json:"rejected_prediction_tokens"`+}++type openAICompatStreamDelta struct {+ Content any `json:"content"`+ Role string `json:"role"`+ FunctionCall any `json:"function_call"`+ ToolCalls any `json:"tool_calls"`+ Reference any `json:"reference,omitempty"`+ Error any `json:"error,omitempty"`+ WaitingForUser any `json:"waiting_for_user,omitempty"`+}++type openAICompatStreamChoice struct {+ Delta openAICompatStreamDelta `json:"delta"`+ FinishReason any `json:"finish_reason"`+ Index int `json:"index"`+ Logprobs any `json:"logprobs"`+}++type openAICompatStreamChunk struct {+ ID string `json:"id"`+ Object string `json:"object"`+ Created int64 `json:"created"`+ Model string `json:"model"`+ SystemFingerprint string `json:"system_fingerprint"`+ Usage *openAICompatUsage `json:"usage"`+ Choices []openAICompatStreamChoice `json:"choices"`+}++type openAICompatMessage struct {+ Role string `json:"role"`+ Content string `json:"content"`+ Reference any `json:"reference,omitempty"`+}++type openAICompatCompletionChoice struct {+ Message openAICompatMessage `json:"message"`+ Logprobs any `json:"logprobs"`+ FinishReason string `json:"finish_reason"`+ Index int `json:"index"`+}++type openAICompatCompletion struct {+ ID string `json:"id"`+ Object string `json:"object"`+ Created int64 `json:"created"`+ Model string `json:"model"`+ Param any `json:"param"`+ Usage openAICompatUsage `json:"usage"`+ Choices []openAICompatCompletionChoice `json:"choices"`+}++// handleOpenAICompat adapts the Agent RunEvent stream to the direct OpenAI+// chat-completion wire format. It deliberately does not use the normal+// RAGFlow response helpers because those add the {code,data,message} REST+// envelope and are not accepted by OpenAI-compatible clients.+func (h *AgentHandler) handleOpenAICompat(c *gin.Context, user *entity.User, req *agentChatCompletionsRequest) {+ question := extractLastUserContent(req.Messages)+ if req.SessionID == "" {+ req.SessionID = utility.GenerateToken()+ }++ runContext := service.WithOpenAICompatMessages(c.Request.Context(), req.Messages)+ events, err := h.chatRunner.RunAgent(+ runContext, user.ID, req.AgentID, req.SessionID, "", question, req.Files,+ )+ if err != nil {+ writeOpenAICompatError(c, err)+ return+ }++ completionID := req.SessionID+ promptTokens := countOpenAICompatPromptTokens(req.Messages)+ if req.Stream {+ h.streamOpenAICompat(c, events, completionID, req.AgentID, promptTokens)+ return+ }++ response, err := collectOpenAICompatCompletion(events, completionID, req.AgentID, promptTokens)+ if err != nil {+ writeOpenAICompatError(c, err)+ return+ }+ c.JSON(http.StatusOK, response)+}++func (h *AgentHandler) streamOpenAICompat(+ c *gin.Context,+ events <-chan canvas.RunEvent,+ completionID, model string,+ promptTokens int,+) {+ c.Header("Content-Type", "text/event-stream")+ c.Header("Cache-Control", "no-cache")+ c.Header("Connection", "keep-alive")++ completionTokens := 0+ for ev := range events {+ switch ev.Type {+ case "error":+ message := openAICompatRunEventMessage(ev, "Agent run failed.")+ chunk := newOpenAICompatStreamChunk(completionID, model, "**ERROR**: "+message, "error")+ chunk.Choices[0].Delta.Error = map[string]string{+ "message": message,+ "type": "server_error",+ }+ chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)+ _ = writeOpenAICompatSSE(c, chunk)+ return+ case "waiting_for_user":+ chunk := newOpenAICompatStreamChunk(completionID, model, nil, "waiting_for_user")+ chunk.Choices[0].Delta.WaitingForUser = openAICompatWaitingForUser(ev)+ chunk.Usage = openAICompatUsageForCompletion(promptTokens, completionTokens)+ _ = writeOpenAICompatSSE(c, chunk)+ return+ }++ if ev.Type != "message" && ev.Type != "message_end" {+ continue+ }++ content := ""+ var reference any+ if ev.Data != "" {+ var data map[string]any+ if err := json.Unmarshal([]byte(ev.Data), &data); err == nil {+ if value, ok := data["content"].(string); ok {+ content = value+ }+ reference = data["reference"]+ }+ }+ completionTokens += tokenizer.NumTokensFromString(content)++ chunk := newOpenAICompatStreamChunk(completionID, model, content, nil)+ if reference != nil {+ chunk.Choices[0].Delta.Reference = reference+ }+ if err := writeOpenAICompatSSE(c, chunk); err != nil {+ return+ }+ }++ finalChunk := newOpenAICompatStreamChunk(completionID, model, nil, "stop")+ finalChunk.Usage = &openAICompatUsage{+ PromptTokens: promptTokens,+ CompletionTokens: completionTokens,+ TotalTokens: promptTokens + completionTokens,+ }+ if err := writeOpenAICompatSSE(c, finalChunk); err != nil {+ return+ }+ _, _ = c.Writer.Write([]byte("data: [DONE]\n\n"))+ if flusher, ok := c.Writer.(http.Flusher); ok {+ flusher.Flush()+ }+}++func collectOpenAICompatCompletion(+ events <-chan canvas.RunEvent,+ completionID, model string,+ promptTokens int,+) (openAICompatCompletion, error) {+ content := ""+ completionTokens := 0+ var reference any+ for ev := range events {+ if ev.Type == "error" {+ return openAICompatCompletion{}, common.NewCodedError(+ common.CodeServerError,+ openAICompatRunEventMessage(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)+ }+ if ev.Type != "message" && ev.Type != "message_end" {+ continue+ }++ if ev.Data == "" {+ continue+ }+ var data map[string]any+ if err := json.Unmarshal([]byte(ev.Data), &data); err != nil {+ continue+ }+ if ev.Type == "message" {+ if value, ok := data["content"].(string); ok {+ content += value+ }+ }+ if value := data["reference"]; value != nil {+ reference = value+ }+ }+ completionTokens = tokenizer.NumTokensFromString(content)++ message := openAICompatMessage{Role: "assistant", Content: content}+ if reference != nil {+ message.Reference = reference+ }+ return openAICompatCompletion{+ ID: completionID,+ Object: "chat.completion",+ Created: time.Now().Unix(),+ Model: model,+ Param: nil,+ Usage: openAICompatUsage{+ PromptTokens: promptTokens,+ CompletionTokens: completionTokens,+ TotalTokens: promptTokens + completionTokens,+ },+ Choices: []openAICompatCompletionChoice{{+ Message: message,+ Logprobs: nil,+ FinishReason: "stop",+ Index: 0,+ }},+ }, nil+}++func newOpenAICompatStreamChunk(+ completionID, model string, content any, finishReason any,+) openAICompatStreamChunk {+ return openAICompatStreamChunk{+ ID: completionID,+ Object: "chat.completion.chunk",+ Created: time.Now().Unix(),+ Model: model,+ SystemFingerprint: "",+ Usage: nil,+ Choices: []openAICompatStreamChoice{{+ Delta: openAICompatStreamDelta{+ Content: content,+ Role: "assistant",+ FunctionCall: nil,+ ToolCalls: nil,+ },+ FinishReason: finishReason,+ Index: 0,+ Logprobs: nil,+ }},+ }+}++func openAICompatUsageForCompletion(promptTokens, completionTokens int) *openAICompatUsage {+ return &openAICompatUsage{+ PromptTokens: promptTokens,+ CompletionTokens: completionTokens,+ TotalTokens: promptTokens + completionTokens,+ }+}++func openAICompatRunEventMessage(ev canvas.RunEvent, fallback string) string {+ var payload canvas.ErrorEvent+ if err := json.Unmarshal([]byte(ev.Data), &payload); err == nil && 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 {+ return err+ }+ if _, err := c.Writer.Write([]byte("data: ")); err != nil {+ return err+ }+ if _, err := c.Writer.Write(data); err != nil {+ return err+ }+ if _, err := c.Writer.Write([]byte("\n\n")); err != nil {+ return err+ }+ if flusher, ok := c.Writer.(http.Flusher); ok {+ flusher.Flush()+ }+ return nil+}++func writeOpenAICompatError(c *gin.Context, err error) {+ code, message := mapAgentError(err)+ var codedErr *common.CodedError+ if errors.As(err, &codedErr) {+ code, message = codedErr.Code, codedErr.Message+ }+ status, errorType := openAICompatErrorResponse(code, err)+ c.JSON(status, gin.H{+ "error": gin.H{+ "message": message,+ "type": errorType,+ },+ })+}++func openAICompatErrorResponse(code common.ErrorCode, err error) (int, string) {+ if errors.Is(err, service.ErrAgentSessionBusy) {+ return http.StatusConflict, "invalid_request_error"+ }++ switch code {+ case common.CodeArgumentError, common.CodeDataError, common.CodeBadRequest, common.CodeParamError:+ return http.StatusBadRequest, "invalid_request_error"+ case common.CodeUnauthorized, common.CodeAuthenticationError:+ return http.StatusUnauthorized, "authentication_error"+ case common.CodeOperatingError, common.CodeForbidden, common.CodePermissionError:+ return http.StatusForbidden, "permission_error"+ case common.CodeNotFound:+ return http.StatusNotFound, "not_found_error"+ case common.CodeConflict:+ return http.StatusConflict, "invalid_request_error"+ default:+ return http.StatusInternalServerError, "server_error"+ }+}++func countOpenAICompatPromptTokens(messages []map[string]interface{}) int {+ total := 0+ for _, message := range messages {+ content, err := service.NormalizeOpenAIMessageContent(message["content"])+ if err != nil {+ continue+ }+ total += tokenizer.NumTokensFromString(content)+ }+ return total+}diff --git a/internal/handler/agent_test.go b/internal/handler/agent_test.goindex 5baad8e1d8..911c64e55d 100644--- a/internal/handler/agent_test.go+++ b/internal/handler/agent_test.go@@ -36,6 +36,7 @@ import ("ragflow/internal/dao""ragflow/internal/entity""ragflow/internal/service"+ "ragflow/internal/tokenizer")// setupHandlerAgentsTestDB sets up SQLite in-memory DB with tables needed for agent handler tests.@@ -713,14 +714,18 @@ func TestAgentChatCompletions_OpenAICompat_EmptyMessages(t *testing.T) {// SSE tests. It emits a pre-configured sequence of canvas.RunEvent// values on its RunAgent channel and then closes — enough to verify// the SSE wire format (Content-Type, one `data: {...}\n\n` frame per-// event, trailing `data:[DONE]\n\n`) without standing up the eino+// event, trailing `data: [DONE]\n\n`) without standing up the eino// runner or a live DB.type stubChatRunner struct {- events []canvas.RunEvent- err error+ events []canvas.RunEvent+ err error+ sessionID string+ userInput any}-func (s *stubChatRunner) RunAgent(_ context.Context, _, _, _, _ string, _ any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {+func (s *stubChatRunner) RunAgent(_ context.Context, _, _, sessionID, _ string, userInput any, _ []map[string]interface{}) (<-chan canvas.RunEvent, error) {+ s.sessionID = sessionID+ s.userInput = userInputif s.err != nil {return nil, s.err}@@ -734,7 +739,7 @@ func (s *stubChatRunner) RunAgent(_ context.Context, _, _, _, _ string, _ any, _// TestAgentChatCompletions_StreamSetsContentType covers the SSE// path: the handler streams canvas.RunEvent frames as-// `data: {...}\n\n` with a trailing `data:[DONE]\n\n` terminator.+// `data: {...}\n\n` with a trailing `data: [DONE]\n\n` terminator.// The frame shape is the Python agent-canvas envelope// {event,message_id,task_id,session_id,data:{content}}. task_id is a wire alias// for session_id. See@@ -1035,32 +1040,402 @@ func (c *captureChatRunner) RunAgent(_ context.Context, _, _, _, _ string, userIreturn ch, nil}-// TestAgentChatCompletions_OpenAICompat_NonStreamReturnsChoices covers-// the openai-compatible non-stream branch — the test contract requires-// "choices" at the top level (not inside data).-func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsChoices(t *testing.T) {+// TestAgentChatCompletions_OpenAICompat_NonStreamReturnsCompletion verifies+// the non-stream branch returns the direct OpenAI completion object and that+// Agent events are converted into one final assistant message.+func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsCompletion(t *testing.T) {gin.SetMode(gin.TestMode)w := httptest.NewRecorder()c, _ := gin.CreateTestContext(w)c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",- strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"model":"m","messages":[{"role":"user","content":"hi"}]}`))+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"model":"m","messages":[+ {"role":"system","content":"Be concise."},+ {"role":"user","content":"What is 1+1?"},+ {"role":"assistant","content":"2"},+ {"role":"user","content":"hi"}+ ]}`))c.Request.Header.Set("Content-Type", "application/json")c.Set("user", &entity.User{ID: "u1"})c.Set("user_id", "u1")- ctx := t.Context()- h := NewAgentHandler(ctx, service.NewAgentService(), nil)+ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "message", Data: `{"content":"hello "}`},+ {Type: "message", Data: `{"content":"world"}`},+ {Type: "message_end", Data: `{"reference":{"chunks":[]}}`},+ {Type: "workflow_finished", Data: `{"outputs":"hello world"}`},+ }}+ h := &AgentHandler{chatRunner: runner}h.AgentChatCompletions(c)+ if runner.userInput != "hi" {+ t.Errorf("runner userInput = %v, want hi", runner.userInput)+ }+ if runner.sessionID == "" {+ t.Error("runner sessionID should be generated for a new OpenAI-compatible request")+ }var resp map[string]interface{}- _ = json.Unmarshal(w.Body.Bytes(), &resp)- data, _ := resp["data"].(map[string]interface{})- if data == nil {- t.Fatalf("response should contain 'data', got keys: %v", resp)+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatalf("decode response: %v; body=%s", err, w.Body.String())+ }+ if resp["object"] != "chat.completion" {+ t.Fatalf("object = %v, want chat.completion; response=%v", resp["object"], resp)+ }+ if resp["id"] != runner.sessionID {+ t.Errorf("id = %v, want generated session id %q", resp["id"], runner.sessionID)+ }+ if resp["model"] != "a1" {+ t.Errorf("model = %v, want agent id a1", resp["model"])+ }+ if _, wrapped := resp["code"]; wrapped {+ t.Fatalf("OpenAI response must not use the RAGFlow REST envelope: %v", resp)+ }+ choices, ok := resp["choices"].([]interface{})+ if !ok || len(choices) != 1 {+ t.Fatalf("choices = %#v, want one choice", resp["choices"])+ }+ choice := choices[0].(map[string]interface{})+ message := choice["message"].(map[string]interface{})+ if message["content"] != "hello world" {+ t.Errorf("content = %v, want hello world", message["content"])+ }+ if message["role"] != "assistant" {+ t.Errorf("role = %v, want assistant", message["role"])+ }+ if choice["finish_reason"] != "stop" {+ t.Errorf("finish_reason = %v, want stop", choice["finish_reason"])+ }+ if _, ok := message["reference"]; !ok {+ t.Errorf("message should include reference, got %v", message)+ }+ usage, ok := resp["usage"].(map[string]interface{})+ if !ok {+ t.Fatalf("usage = %#v, want object", resp["usage"])+ }+ wantPromptTokens := tokenizer.NumTokensFromString("Be concise.") ++ tokenizer.NumTokensFromString("What is 1+1?") ++ tokenizer.NumTokensFromString("2") ++ tokenizer.NumTokensFromString("hi")+ if got := int(usage["prompt_tokens"].(float64)); got != wantPromptTokens {+ t.Errorf("prompt_tokens = %d, want all message content counted as %d", got, wantPromptTokens)+ }+ if usage["total_tokens"].(float64) != usage["prompt_tokens"].(float64)+usage["completion_tokens"].(float64) {+ t.Errorf("usage totals do not add up: %v", usage)+ }+}++func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsRunnerError(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "error", Data: `{"message":"retrieval backend failed"}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ if w.Code != http.StatusInternalServerError {+ t.Fatalf("status = %d, want 500: %s", w.Code, w.Body.String())+ }+ var response struct {+ Error struct {+ Message string `json:"message"`+ Type string `json:"type"`+ } `json:"error"`}- if _, ok := data["choices"]; !ok {- t.Errorf("response data should contain 'choices', got keys: %v", data)+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatalf("decode error response: %v", err)+ }+ if response.Error.Type != "server_error" {+ t.Errorf("error.type = %q, want server_error", response.Error.Type)+ }+ if response.Error.Message != "retrieval backend failed" {+ t.Errorf("error.message = %q, want runner error", response.Error.Message)+ }+}++func TestAgentChatCompletions_OpenAICompat_NonStreamReturnsWaitingForUser(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "waiting_for_user", Data: `{"cpn_id":"input-1","tips":"Please choose an option."}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ if w.Code != http.StatusConflict {+ t.Fatalf("status = %d, want 409: %s", w.Code, w.Body.String())+ }+ var response struct {+ Error struct {+ Message string `json:"message"`+ Type string `json:"type"`+ } `json:"error"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatalf("decode error response: %v", err)+ }+ if response.Error.Type != "invalid_request_error" {+ t.Errorf("error.type = %q, want invalid_request_error", response.Error.Type)+ }+ if !strings.Contains(response.Error.Message, "waiting for user input") ||+ !strings.Contains(response.Error.Message, "input-1") {+ t.Errorf("error.message = %q, want waiting state and cpn id", response.Error.Message)+ }+}++func TestAgentChatCompletions_OpenAICompat_MapsErrors(t *testing.T) {+ tests := []struct {+ name string+ err error+ status int+ errorType string+ wantMessage string+ }{+ {+ name: "session busy",+ err: service.ErrAgentSessionBusy,+ status: http.StatusConflict,+ errorType: "invalid_request_error",+ wantMessage: "already running",+ },+ {+ name: "operating error",+ err: service.ErrAgentNotOwner,+ status: http.StatusForbidden,+ errorType: "permission_error",+ wantMessage: "Only the owner",+ },+ {+ name: "data error",+ err: errors.New("invalid workflow input"),+ status: http.StatusBadRequest,+ errorType: "invalid_request_error",+ wantMessage: "invalid workflow input",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions", strings.NewReader(`{+ "agent_id":"a1",+ "openai-compatible":true,+ "messages":[{"role":"user","content":"hi"}]+ }`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{err: tt.err}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ if w.Code != tt.status {+ t.Fatalf("status = %d, want %d: %s", w.Code, tt.status, w.Body.String())+ }+ var response struct {+ Error struct {+ Message string `json:"message"`+ Type string `json:"type"`+ } `json:"error"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatalf("decode error response: %v", err)+ }+ if response.Error.Type != tt.errorType {+ t.Errorf("error.type = %q, want %q", response.Error.Type, tt.errorType)+ }+ if !strings.Contains(response.Error.Message, tt.wantMessage) {+ t.Errorf("error.message = %q, want substring %q", response.Error.Message, tt.wantMessage)+ }+ })+ }+}++func TestAgentChatCompletions_OpenAICompat_StreamUsesOpenAIChunks(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"stream":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "message", Data: `{"content":"hello"}`},+ {Type: "message_end", Data: `{"reference":{"chunks":[]}}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ if got := w.Header().Get("Content-Type"); !strings.Contains(got, "text/event-stream") {+ t.Fatalf("Content-Type = %q, want text/event-stream", got)+ }+ body := w.Body.String()+ if strings.Contains(body, `"code":0`) || strings.Contains(body, `"data":{"choices"`) {+ t.Fatalf("OpenAI stream must not use the RAGFlow REST envelope: %s", body)+ }+ chunks, done := decodeOpenAICompatStream(t, body)+ if !done {+ t.Fatal("stream should end with [DONE]")+ }+ if len(chunks) != 3 {+ t.Fatalf("decoded %d chunks, want message, message_end, and final usage chunk", len(chunks))+ }+ for i, chunk := range chunks {+ if chunk["id"] != runner.sessionID {+ t.Errorf("chunk[%d].id = %v, want %q", i, chunk["id"], runner.sessionID)+ }+ if chunk["model"] != "a1" {+ t.Errorf("chunk[%d].model = %v, want a1", i, chunk["model"])+ }+ if chunk["object"] != "chat.completion.chunk" {+ t.Errorf("chunk[%d].object = %v, want chat.completion.chunk", i, chunk["object"])+ }+ }+ firstChoices, _ := chunks[0]["choices"].([]interface{})+ if len(firstChoices) != 1 {+ t.Fatalf("first choices = %#v, want one choice", chunks[0]["choices"])+ }+ firstDelta := firstChoices[0].(map[string]interface{})["delta"].(map[string]interface{})+ if firstDelta["content"] != "hello" {+ t.Errorf("first delta content = %v, want hello", firstDelta["content"])+ }+ messageEndChoices, _ := chunks[1]["choices"].([]interface{})+ if len(messageEndChoices) != 1 {+ t.Fatalf("message_end choices = %#v, want one choice", chunks[1]["choices"])+ }+ messageEndDelta := messageEndChoices[0].(map[string]interface{})["delta"].(map[string]interface{})+ if _, ok := messageEndDelta["reference"]; !ok {+ t.Errorf("message_end delta should include reference: %#v", messageEndDelta)+ }+ lastChoices, _ := chunks[2]["choices"].([]interface{})+ if len(lastChoices) != 1 {+ t.Fatalf("final choices = %#v, want one choice", chunks[2]["choices"])+ }+ lastChoice := lastChoices[0].(map[string]interface{})+ if lastChoice["finish_reason"] != "stop" {+ t.Errorf("final finish_reason = %v, want stop", lastChoice["finish_reason"])+ }+ usage, ok := chunks[2]["usage"].(map[string]interface{})+ if !ok {+ t.Fatalf("final usage = %#v, want object", chunks[2]["usage"])+ }+ if usage["total_tokens"].(float64) != usage["prompt_tokens"].(float64)+usage["completion_tokens"].(float64) {+ t.Errorf("stream usage totals do not add up: %v", usage)+ }+}++func TestAgentChatCompletions_OpenAICompat_StreamSurfacesRunnerError(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"stream":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "message", Data: `{"content":"partial"}`},+ {Type: "error", Data: `{"message":"LLM failed"}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ chunks, done := decodeOpenAICompatStream(t, w.Body.String())+ if done {+ t.Fatal("failed stream must not end with [DONE]")+ }+ if len(chunks) != 2 {+ t.Fatalf("decoded %d chunks, want partial content and error", len(chunks))+ }+ choices := chunks[1]["choices"].([]interface{})+ choice := choices[0].(map[string]interface{})+ if choice["finish_reason"] != "error" {+ t.Errorf("finish_reason = %v, want error", choice["finish_reason"])+ }+ delta := choice["delta"].(map[string]interface{})+ if delta["content"] != "**ERROR**: LLM failed" {+ t.Errorf("error content = %v, want decorated runner error", delta["content"])+ }+ errorPayload := delta["error"].(map[string]interface{})+ if errorPayload["message"] != "LLM failed" {+ t.Errorf("error payload = %v, want runner message", errorPayload)+ }+}++func TestAgentChatCompletions_OpenAICompat_StreamSurfacesWaitingForUser(t *testing.T) {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/api/v1/agents/chat/completions",+ strings.NewReader(`{"agent_id":"a1","openai-compatible":true,"stream":true,"messages":[{"role":"user","content":"hi"}]}`))+ c.Request.Header.Set("Content-Type", "application/json")+ c.Set("user", &entity.User{ID: "u1"})+ c.Set("user_id", "u1")++ runner := &stubChatRunner{events: []canvas.RunEvent{+ {Type: "waiting_for_user", Data: `{"cpn_id":"input-1","tips":"Please choose an option.","inputs":{"choice":{"type":"line"}}}`},+ }}+ h := &AgentHandler{chatRunner: runner}+ h.AgentChatCompletions(c)++ chunks, done := decodeOpenAICompatStream(t, w.Body.String())+ if done {+ t.Fatal("waiting stream must not end with [DONE]")+ }+ if len(chunks) != 1 {+ t.Fatalf("decoded %d chunks, want waiting state", len(chunks))+ }+ choices := chunks[0]["choices"].([]interface{})+ choice := choices[0].(map[string]interface{})+ if choice["finish_reason"] != "waiting_for_user" {+ t.Errorf("finish_reason = %v, want waiting_for_user", choice["finish_reason"])+ }+ delta := choice["delta"].(map[string]interface{})+ waiting := delta["waiting_for_user"].(map[string]interface{})+ if waiting["cpn_id"] != "input-1" {+ t.Errorf("waiting_for_user = %v, want cpn_id input-1", waiting)+ }+}++func decodeOpenAICompatStream(t *testing.T, body string) ([]map[string]interface{}, bool) {+ t.Helper()+ frames := strings.Split(strings.TrimSuffix(body, "\n\n"), "\n\n")+ chunks := make([]map[string]interface{}, 0, len(frames))+ done := false+ for _, frame := range frames {+ switch {+ case frame == "data: [DONE]":+ done = true+ case strings.HasPrefix(frame, "data: "):+ var chunk map[string]interface{}+ if err := json.Unmarshal([]byte(strings.TrimPrefix(frame, "data: ")), &chunk); err != nil {+ t.Fatalf("decode SSE frame %q: %v", frame, err)+ }+ chunks = append(chunks, chunk)+ default:+ t.Fatalf("unexpected SSE frame %q", frame)+ }}+ return chunks, done}// TestRerunAgent_RequiresAllFields covers the 101 branch: missingdiff --git a/internal/service/agent.go b/internal/service/agent.goindex 638ed602d5..f4de04f7ce 100644--- a/internal/service/agent.go+++ b/internal/service/agent.go@@ -93,6 +93,8 @@ func (s *AgentService) RunAgentWithWebhook(type agentSessionIDContextKey struct{}+type openAICompatMessagesContextKey struct{}+// WithAgentSessionID lets an HTTP boundary allocate the session identity while// keeping session-record persistence inside AgentService.RunAgent.func WithAgentSessionID(ctx context.Context, sessionID string) context.Context {@@ -108,6 +110,33 @@ func AgentSessionIDFromContext(ctx context.Context) string {return sessionID}+// WithOpenAICompatMessages attaches the complete OpenAI messages list to an+// agent run without changing RunAgent's public argument list. The latest user+// message remains the run input; the service uses the earlier messages to seed+// the workflow history.+func WithOpenAICompatMessages(ctx context.Context, messages []map[string]interface{}) context.Context {+ if len(messages) == 0 {+ return ctx+ }++ copied := make([]map[string]interface{}, len(messages))+ for i, message := range messages {+ copied[i] = make(map[string]interface{}, len(message))+ for key, value := range message {+ copied[i][key] = value+ }+ }+ return context.WithValue(ctx, openAICompatMessagesContextKey{}, copied)+}++func openAICompatMessagesFromContext(ctx context.Context) []map[string]interface{} {+ if ctx == nil {+ return nil+ }+ messages, _ := ctx.Value(openAICompatMessagesContextKey{}).([]map[string]interface{})+ return messages+}+func emitAgentMessageEvents(emit func(string, string), answer, thinking string, reference any) {for _, ev := range buildAgentMessageEvents(answer, thinking, reference) {data, _ := json.Marshal(ev)@@ -1673,6 +1702,9 @@ func (s *AgentService) RunAgent(ctx context.Context, userID, canvasID, sessionIDif userInput != nil {root["user_input"] = userInput}+ if messages := openAICompatMessagesFromContext(ctx); len(messages) > 0 {+ root["openai_messages"] = messages+ }if len(files) > 0 {root["files"] = files}@@ -1944,6 +1976,9 @@ func (s *AgentService) buildRunFunc(canvasID string, versionRow *entity.UserCanv}}state.SetHistory(c.History)+ if messages, ok := root["openai_messages"].([]map[string]interface{}); ok && len(messages) > 1 {+ state.SetHistory(openAICompatPriorHistory(messages))+ }state.SetMemory(c.Memory)state.EnsureSysDate()state.Sys["query"] = userInput@@ -2502,6 +2537,31 @@ func renderUserHistoryValue(value any) string {}}+func openAICompatPriorHistory(messages []map[string]interface{}) []map[string]any {+ lastUser := -1+ for i, message := range messages {+ if role, _ := message["role"].(string); role == "user" {+ lastUser = i+ }+ }+ if lastUser <= 0 {+ return nil+ }++ history := make([]map[string]any, 0, lastUser)+ for _, message := range messages[:lastUser] {+ role, _ := message["role"].(string)+ content, err := NormalizeOpenAIMessageContent(message["content"])+ if err != nil || role == "" || content == "" {+ continue+ }+ history = append(history, map[string]any{+ "role": role,+ "content": content,+ })+ }+ return history+}func pythonHistoryRepr(value any) string {switch item := value.(type) {case nil:diff --git a/internal/service/agent_test.go b/internal/service/agent_test.goindex e5f2a53f05..b7d64adfe1 100644--- a/internal/service/agent_test.go+++ b/internal/service/agent_test.go@@ -2343,3 +2343,22 @@ func TestAgentHistoryRenderingMatchesPythonShapes(t *testing.T) {t.Fatalf("rendered assistant history = %q, want %q", assistant, want)}}++func TestOpenAICompatPriorHistoryPreservesConversation(t *testing.T) {+ messages := []map[string]interface{}{+ {"role": "system", "content": "Be concise."},+ {"role": "user", "content": "What is 1+1?"},+ {"role": "assistant", "content": "2"},+ {"role": "user", "content": "What is 2+2?"},+ }++ history := openAICompatPriorHistory(messages)+ want := []map[string]any{+ {"role": "system", "content": "Be concise."},+ {"role": "user", "content": "What is 1+1?"},+ {"role": "assistant", "content": "2"},+ }+ if !reflect.DeepEqual(history, want) {+ t.Fatalf("prior history = %#v, want %#v", history, want)+ }+}diff --git a/internal/service/openai_chat.go b/internal/service/openai_chat.goindex 31dfc2b079..56b096a5d2 100644--- a/internal/service/openai_chat.go+++ b/internal/service/openai_chat.go@@ -567,8 +567,9 @@ func extractGenerationConfig(req *OpenAIChatRequest) map[string]interface{} {return cfg}-// normalizeMessageContent coerces content to string (drops non-text parts).-func normalizeMessageContent(content interface{}) (string, error) {+// NormalizeOpenAIMessageContent coerces OpenAI message content to text and+// drops unsupported non-text parts.+func NormalizeOpenAIMessageContent(content interface{}) (string, error) {if content == nil {return "", nil}@@ -601,7 +602,7 @@ func normalizeOpenAIMessages(messages []map[string]interface{}) ([]map[string]infor k, v := range m {normalized[k] = v}- c, err := normalizeMessageContent(m["content"])+ c, err := NormalizeOpenAIMessageContent(m["content"])if err != nil {return nil, err}diff --git a/internal/service/openai_chat_test.go b/internal/service/openai_chat_test.goindex f3e18e889e..4dc94f62bc 100644--- a/internal/service/openai_chat_test.go+++ b/internal/service/openai_chat_test.go@@ -439,32 +439,32 @@ func TestOpenAI_PerDeltaTrimSpace_NotApplied(t *testing.T) {// Request preparation helpers (moved from internal/handler/openai_chat_completions_test.go)// =============================================================================-// TestService_NormalizeMessageContent_String passes a plain string through.-func TestService_NormalizeMessageContent_String(t *testing.T) {- got, err := normalizeMessageContent("hello")+// TestService_NormalizeOpenAIMessageContent_String passes a plain string through.+func TestService_NormalizeOpenAIMessageContent_String(t *testing.T) {+ got, err := NormalizeOpenAIMessageContent("hello")if err != nil || got != "hello" {t.Fatalf("expected (%q,nil), got (%q,%v)", "hello", got, err)}}-// TestService_NormalizeMessageContent_Nil returns "" with no error.-func TestService_NormalizeMessageContent_Nil(t *testing.T) {- got, err := normalizeMessageContent(nil)+// TestService_NormalizeOpenAIMessageContent_Nil returns "" with no error.+func TestService_NormalizeOpenAIMessageContent_Nil(t *testing.T) {+ got, err := NormalizeOpenAIMessageContent(nil)if err != nil || got != "" {t.Fatalf("expected (\"\",nil), got (%q,%v)", got, err)}}-// TestService_NormalizeMessageContent_ArrayOfTextParts joins text parts+// TestService_NormalizeOpenAIMessageContent_ArrayOfTextParts joins text parts// with "\n" and drops non-text parts (e.g. image_url). Mirrors// _normalize_message_content in openai_api.py:198-216.-func TestService_NormalizeMessageContent_ArrayOfTextParts(t *testing.T) {+func TestService_NormalizeOpenAIMessageContent_ArrayOfTextParts(t *testing.T) {in := []interface{}{map[string]interface{}{"type": "text", "text": "first"},map[string]interface{}{"type": "image_url", "image_url": map[string]string{"url": "http://x"}},map[string]interface{}{"type": "text", "text": "second"},}- got, err := normalizeMessageContent(in)+ got, err := NormalizeOpenAIMessageContent(in)if err != nil {t.Fatalf("unexpected error: %v", err)}@@ -473,9 +473,9 @@ func TestService_NormalizeMessageContent_ArrayOfTextParts(t *testing.T) {}}-// TestService_NormalizeMessageContent_InvalidType returns the Python error string.-func TestService_NormalizeMessageContent_InvalidType(t *testing.T) {- _, err := normalizeMessageContent(42)+// TestService_NormalizeOpenAIMessageContent_InvalidType returns the Python error string.+func TestService_NormalizeOpenAIMessageContent_InvalidType(t *testing.T) {+ _, err := NormalizeOpenAIMessageContent(42)if err == nil || !strings.Contains(err.Error(), "must be a string or an array") {t.Fatalf("expected content-type error, got %v", err)}diff --git a/test/testcases/restful_api/test_agents.py b/test/testcases/restful_api/test_agents.pyindex 92f45a0482..a5cbc004e9 100644--- a/test/testcases/restful_api/test_agents.py+++ b/test/testcases/restful_api/test_agents.py@@ -277,8 +277,7 @@ def test_agent_openai_compatible_mode(rest_client, create_agent_resource):assert nonstream.status_code == 200nonstream_payload = nonstream.json()assert isinstance(nonstream_payload, dict), nonstream_payload- if "choices" not in nonstream_payload and nonstream_payload.get("code") == 0 and "choices" in (nonstream_payload.get("data") or {}):- pytest.skip("Go agent OpenAI-compatible response is incorrectly wrapped in the REST envelope")+ assert nonstream_payload.get("object") == "chat.completion", nonstream_payloadassert "choices" in nonstream_payload, nonstream_payloadstream = rest_client.post(