Skip to content

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

feat(agent): support OpenAI-compatible responses (#18316)

Guofang.Tang4304a3b7c6d3
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 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.go
new file mode 100644
index 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.go
index 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 = userInput
if 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, userI
return 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: missing
diff --git a/internal/service/agent.go b/internal/service/agent.go
index 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, sessionID
if 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.go
index 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.go
index 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]in
for 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.go
index 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.py
index 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 == 200
nonstream_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_payload
assert "choices" in nonstream_payload, nonstream_payload
stream = rest_client.post(