Skip to content

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

fix(chat): stop rag_agent forwarding message bookkeeping keys to the provider (#18663)

Bharadwaj Pendyala89fc1abac9d5
diff --git a/api/db/services/dialog_service.py b/api/db/services/dialog_service.py
index d8d235356f..45529fdd70 100644
--- a/api/db/services/dialog_service.py
+++ b/api/db/services/dialog_service.py
@@ -523,6 +523,11 @@ def convert_last_user_msg_to_multimodal(msg: list[dict], image_data_uris: list[s
return
+# Keys the chat-completions message schema defines. Stored messages also carry
+# RAGFlow bookkeeping such as id, created_at and doc_ids, plus the conversationId
+# the web client stamps on every turn, and strict providers reject those.
+LLM_MESSAGE_FIELDS = frozenset({"role", "content", "name", "tool_calls", "tool_call_id", "function_call", "refusal", "audio"})
+
BAD_CITATION_PATTERNS = [
re.compile(r"\(\s*ID\s*[: ]*\s*(\d+)\s*\)"), # (ID: 12)
re.compile(r"\[\s*ID\s*[: ]*\s*(\d+)\s*\]"), # [ID: 12]
@@ -1949,7 +1954,7 @@ async def rag_agent(dialog, messages, stream=True, **kwargs):
model_type = chat_mdl.model_config["model_type"]
factory = chat_mdl.model_config.get("llm_factory", "") if chat_mdl.model_config else ""
text_attachments_content, image_attachments, image_files = get_files_content(messages[-1], model_type)
- agent_messages = deepcopy(messages)
+ agent_messages = [{k: deepcopy(v) for k, v in m.items() if k in LLM_MESSAGE_FIELDS} for m in messages]
if text_attachments_content and agent_messages:
agent_messages[-1]["content"] += text_attachments_content
if model_type == "chat" and image_attachments:
diff --git a/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py
new file mode 100644
index 0000000000..1dcf592e41
--- /dev/null
+++ b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py
@@ -0,0 +1,178 @@
+#
+# 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.
+#
+"""
+Regression tests for rag_agent() forwarding message bookkeeping keys to the LLM.
+
+Stored and client-supplied messages carry keys the chat schema does not define
+(`id`, `created_at`, and `conversationId` from the web client). rag_agent() used
+to deepcopy the message list wholesale, so providers that validate message
+properties strictly, such as Groq, rejected the request.
+"""
+
+import asyncio
+import sys
+import types
+import warnings
+from types import SimpleNamespace
+
+import pytest
+
+warnings.filterwarnings(
+ "ignore",
+ message="pkg_resources is deprecated as an API.*",
+ category=UserWarning,
+)
+
+
+def _install_cv2_stub_if_unavailable():
+ try:
+ import cv2 # noqa: F401
+
+ return
+ except Exception:
+ pass
+ stub = types.ModuleType("cv2")
+ stub.INTER_LINEAR = 1
+ stub.INTER_CUBIC = 2
+ stub.BORDER_CONSTANT = 0
+ stub.BORDER_REPLICATE = 1
+ stub.COLOR_BGR2RGB = 0
+ stub.COLOR_BGR2GRAY = 1
+ stub.COLOR_GRAY2BGR = 2
+ stub.IMREAD_IGNORE_ORIENTATION = 128
+ stub.IMREAD_COLOR = 1
+ stub.RETR_LIST = 1
+ stub.CHAIN_APPROX_SIMPLE = 2
+
+ def _module_getattr(name):
+ if name.isupper():
+ return 0
+ raise RuntimeError(f"cv2.{name} is unavailable in this test environment")
+
+ stub.__getattr__ = _module_getattr
+ sys.modules["cv2"] = stub
+
+
+_install_cv2_stub_if_unavailable()
+
+from api.db.services import dialog_service # noqa: E402
+
+
+_DIALOG = SimpleNamespace(
+ id="dialog-1",
+ tenant_id="tenant-1",
+ kb_ids=["kb-1"],
+ llm_id="gpt-4o@OpenAI",
+ llm_setting={"temperature": 0.1},
+ prompt_config={"reasoning": 1},
+ meta_data_filter=None,
+)
+
+_KB = SimpleNamespace(id="kb-1", tenant_id="tenant-1")
+
+
+class _RecordingChatModel:
+ """Records the message list rag_agent() hands to the provider."""
+
+ def __init__(self):
+ self.model_config = {"model_type": "chat", "llm_factory": "OpenAI"}
+ self.mdl = None
+ self.sent_messages = None
+
+ def bind_tools(self, toolcall_session, tools):
+ pass
+
+ async def async_chat(self, system_prompt, messages, gen_conf, **_kwargs):
+ self.sent_messages = messages
+ return "RAGFlow is a RAG engine."
+
+
+class _StubRAGTools:
+ def __init__(self, *_args, **_kwargs):
+ self.kbinfos = {"chunks": [], "doc_aggs": []}
+ self.tools = []
+
+ def sys_prompt(self):
+ return "You are a helpful assistant."
+
+
+def _drive_rag_agent(monkeypatch, messages):
+ chat_mdl = _RecordingChatModel()
+ monkeypatch.setattr(dialog_service, "get_models", lambda _dialog, **_kw: ([_KB], None, None, chat_mdl, None))
+ monkeypatch.setattr(dialog_service, "RAGTools", _StubRAGTools)
+ monkeypatch.setattr(dialog_service, "tts", lambda _mdl, _text: None)
+
+ async def _run():
+ return [ev async for ev in dialog_service.rag_agent(_DIALOG, messages, False, reasoning="2")]
+
+ events = asyncio.run(_run())
+ assert events, "rag_agent must yield an answer event"
+ return chat_mdl
+
+
+def test_rag_agent_drops_bookkeeping_keys_before_the_provider_call(monkeypatch):
+ """Groq rejects any message property the chat schema does not define."""
+ messages = [
+ {"role": "assistant", "content": "Hi! How can I help?", "id": "m-1", "created_at": 1755900000.0},
+ {"role": "user", "content": "What is RAGFlow?", "id": "m-2", "conversationId": "conv-1", "doc_ids": ["doc-1"]},
+ ]
+
+ chat_mdl = _drive_rag_agent(monkeypatch, messages)
+
+ assert chat_mdl.sent_messages == [
+ {"role": "assistant", "content": "Hi! How can I help?"},
+ {"role": "user", "content": "What is RAGFlow?"},
+ ]
+
+
+def test_rag_agent_keeps_tool_call_protocol_fields(monkeypatch):
+ """`tool_calls` and `tool_call_id` belong to the chat schema and pair the two messages together."""
+ tool_calls = [{"id": "call_1", "type": "function", "function": {"name": "weather", "arguments": "{}"}}]
+ messages = [
+ {"role": "user", "content": "Get the weather.", "id": "m-1"},
+ {"role": "assistant", "content": None, "tool_calls": tool_calls, "id": "m-2"},
+ {"role": "tool", "tool_call_id": "call_1", "content": '{"temp_c": 20}', "id": "m-3"},
+ {"role": "user", "content": "Should I take a coat?", "id": "m-4"},
+ ]
+
+ chat_mdl = _drive_rag_agent(monkeypatch, messages)
+
+ assert chat_mdl.sent_messages[1] == {"role": "assistant", "content": None, "tool_calls": tool_calls}
+ assert chat_mdl.sent_messages[2] == {"role": "tool", "tool_call_id": "call_1", "content": '{"temp_c": 20}'}
+
+
+def test_rag_agent_leaves_the_caller_messages_untouched(monkeypatch):
+ """chat_api persists the same dicts after the answer, so the keys must survive the call."""
+ messages = [{"role": "user", "content": "What is RAGFlow?", "id": "m-1", "conversationId": "conv-1"}]
+
+ _drive_rag_agent(monkeypatch, messages)
+
+ assert messages[0]["id"] == "m-1"
+ assert messages[0]["conversationId"] == "conv-1"
+
+
+def test_rag_agent_preserves_multimodal_content_parts(monkeypatch):
+ """`/chat/completions` accepts content-part arrays, so content must be passed through as-is."""
+ content = [{"type": "text", "text": "Describe this image"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA"}}]
+ messages = [{"role": "user", "content": content, "id": "m-1"}]
+
+ chat_mdl = _drive_rag_agent(monkeypatch, messages)
+
+ assert chat_mdl.sent_messages[0]["content"] == content