Skip to content

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

Fix don't send an empty tools array (#19015)

Martin Civáň867e4187ebba
diff --git a/api/db/services/llm_service.py b/api/db/services/llm_service.py
index 653f512940..0e84b7c72b 100644
--- a/api/db/services/llm_service.py
+++ b/api/db/services/llm_service.py
@@ -473,7 +473,7 @@ class LLMBundle(LLM4Tenant):
return queue
async def async_chat(self, system: str, history: list, gen_conf: dict = {}, **kwargs):
- if self.is_tools and hasattr(self.mdl, "async_chat_with_tools"):
+ if self.is_tools and getattr(self.mdl, "is_tools", False) and hasattr(self.mdl, "async_chat_with_tools"):
base_fn = self.mdl.async_chat_with_tools
elif hasattr(self.mdl, "async_chat"):
base_fn = self.mdl.async_chat
diff --git a/rag/llm/chat_model.py b/rag/llm/chat_model.py
index 3603cd1a12..b5ccde4cf8 100644
--- a/rag/llm/chat_model.py
+++ b/rag/llm/chat_model.py
@@ -507,6 +507,16 @@ class Base(ABC):
self.toolcall_session = toolcall_session
self.tools = tools
+ def _tool_request_kwargs(self, tools: list | None = None) -> dict:
+ """Tool fields for a completion request, omitted when nothing is bound.
+
+ Providers that validate the request body reject `tools: []` outright.
+ """
+ tools = self.tools if tools is None else tools
+ if not tools:
+ return {}
+ return {"tools": tools, "tool_choice": "auto"}
+
async def async_chat_with_tools(self, system: str, history: list, gen_conf: dict | None = None):
gen_conf = dict(gen_conf or {})
gen_conf = self._clean_conf(gen_conf)
@@ -516,6 +526,8 @@ class Base(ABC):
gen_conf=gen_conf,
request_kwargs={},
)
+ gen_conf.pop("tools", None)
+ gen_conf.pop("tool_choice", None)
if system and history and history[0].get("role") != "system":
history.insert(0, {"role": "system", "content": system})
@@ -539,7 +551,7 @@ class Base(ABC):
try:
for _ in range(self.max_rounds + 1):
logging.info(f"{self.tools=}")
- response = await self.async_client.chat.completions.create(model=self.model_name, messages=history, tools=self.tools, tool_choice="auto", **gen_conf, **extra_request_kwargs)
+ response = await self.async_client.chat.completions.create(model=self.model_name, messages=history, **self._tool_request_kwargs(), **gen_conf, **extra_request_kwargs)
_add_round_usage(response)
if not response.choices or not response.choices[0].message:
raise Exception(f"500 response structure error. Response: {response}")
@@ -621,6 +633,8 @@ class Base(ABC):
gen_conf=gen_conf,
request_kwargs={},
)
+ gen_conf.pop("tools", None)
+ gen_conf.pop("tool_choice", None)
tools = self.tools
if system and history and history[0].get("role") != "system":
history.insert(0, {"role": "system", "content": system})
@@ -651,7 +665,7 @@ class Base(ABC):
logging.info(f"[Tool loop] Deciding what to do next (step {_round + 1}); available tools: {', '.join(t['function']['name'] for t in tools)}")
response = await self.async_client.chat.completions.create(
- model=self.model_name, messages=history, stream=True, tools=tools, tool_choice="auto", **gen_conf, **extra_request_kwargs
+ model=self.model_name, messages=history, stream=True, **self._tool_request_kwargs(tools), **gen_conf, **extra_request_kwargs
)
final_tool_calls = {}
@@ -761,8 +775,7 @@ class Base(ABC):
model=self.model_name,
messages=history,
stream=True,
- tools=tools,
- tool_choice="auto",
+ **self._tool_request_kwargs(tools),
**gen_conf,
**extra_request_kwargs,
)
diff --git a/test/unit_test/api/db/services/test_llm_bundle_tool_routing.py b/test/unit_test/api/db/services/test_llm_bundle_tool_routing.py
new file mode 100644
index 0000000000..6514e56e16
--- /dev/null
+++ b/test/unit_test/api/db/services/test_llm_bundle_tool_routing.py
@@ -0,0 +1,104 @@
+#
+# 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 LLMBundle's tool-call dispatch.
+
+Two flags share the name `is_tools`: `LLMBundle.is_tools` says the model is
+declared tool-capable in the tenant's provider config, `mdl.is_tools` says
+tools were actually bound by bind_tools(). Both are required before routing
+into `*_with_tools` — checking only the first sends `tools: []` on every
+plain chat against a tool-capable model, which strict providers reject.
+
+async_chat lost the `mdl.is_tools` half of the guard in #16859; its two
+streaming siblings kept it.
+"""
+
+import asyncio
+
+import pytest
+
+from api.db.services.llm_service import LLMBundle
+
+pytestmark = pytest.mark.p1
+
+
+class _RecordingModel:
+ def __init__(self, tools_bound: bool):
+ self.is_tools = tools_bound
+ self.tools = [{"type": "function", "function": {"name": "rag"}}] if tools_bound else []
+ self.last_usage = {"prompt_tokens": 1, "completion_tokens": 2, "total_tokens": 3}
+ self.calls = []
+
+ async def async_chat(self, system, history, gen_conf, **kwargs):
+ self.calls.append("async_chat")
+ return "plain answer", 3
+
+ async def async_chat_with_tools(self, system, history, gen_conf, **kwargs):
+ self.calls.append("async_chat_with_tools")
+ return "tool answer", 3
+
+
+def _bundle(mdl, declared_tool_capable=True):
+ """An LLMBundle without __init__ — no tenant, no DB, no provider lookup."""
+ bundle = LLMBundle.__new__(LLMBundle)
+ bundle.mdl = mdl
+ bundle.is_tools = declared_tool_capable
+ bundle.langfuse = None
+ bundle.trace_context = {}
+ bundle.verbose_tool_use = True
+ bundle.model_config = {"llm_name": "some-tool-capable-model"}
+ return bundle
+
+
+def _chat(bundle):
+ return asyncio.run(bundle.async_chat("system", [{"role": "user", "content": "hi"}], {}))
+
+
+def test_declared_tool_capable_but_nothing_bound_uses_plain_chat():
+ """The regression: this routed into async_chat_with_tools and sent tools: []."""
+ mdl = _RecordingModel(tools_bound=False)
+
+ assert _chat(_bundle(mdl)) == "plain answer"
+ assert mdl.calls == ["async_chat"]
+
+
+def test_tools_actually_bound_uses_the_tool_loop():
+ mdl = _RecordingModel(tools_bound=True)
+
+ assert _chat(_bundle(mdl)) == "tool answer"
+ assert mdl.calls == ["async_chat_with_tools"]
+
+
+def test_not_declared_tool_capable_uses_plain_chat():
+ mdl = _RecordingModel(tools_bound=True)
+
+ assert _chat(_bundle(mdl, declared_tool_capable=False)) == "plain answer"
+ assert mdl.calls == ["async_chat"]
+
+
+def test_model_without_tool_support_still_works():
+ class _PlainOnly:
+ last_usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+
+ async def async_chat(self, system, history, gen_conf, **kwargs):
+ return "plain answer", 0
+
+ assert _chat(_bundle(_PlainOnly())) == "plain answer"
+
+
+def test_model_implementing_neither_raises():
+ with pytest.raises(RuntimeError, match="async_chat"):
+ _chat(_bundle(object()))
diff --git a/test/unit_test/rag/llm/test_empty_tools_request.py b/test/unit_test/rag/llm/test_empty_tools_request.py
new file mode 100644
index 0000000000..5135b4b792
--- /dev/null
+++ b/test/unit_test/rag/llm/test_empty_tools_request.py
@@ -0,0 +1,120 @@
+#
+# 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.
+#
+"""
+`tools: []` must never reach the provider.
+
+Servers that validate their request body reject an empty array outright:
+
+ 400 - Value error, `tools` must not be an empty array.
+ Either provide at least one tool or omit the field entirely.
+
+The LiteLLM path already guards this in `_construct_completion_args`; the
+base OpenAI path did not.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from rag.llm.chat_model import Base
+
+pytestmark = pytest.mark.p1
+
+SCHEMAS = [{"type": "function", "function": {"name": "rag", "parameters": {}}}]
+
+
+def _model(tools):
+ """A Base instance without running __init__ (which would build an API client)."""
+ mdl = Base.__new__(Base)
+ mdl.tools = tools
+ return mdl
+
+
+def test_no_tools_bound_omits_the_fields_entirely():
+ assert _model([])._tool_request_kwargs() == {}
+
+
+def test_bound_tools_are_sent_with_auto_choice():
+ assert _model(SCHEMAS)._tool_request_kwargs() == {"tools": SCHEMAS, "tool_choice": "auto"}
+
+
+def test_explicit_tools_argument_wins_over_self_tools():
+ """The streaming loop snapshots `tools = self.tools` and passes it back in."""
+ assert _model(SCHEMAS)._tool_request_kwargs([]) == {}
+ assert _model([])._tool_request_kwargs(SCHEMAS) == {"tools": SCHEMAS, "tool_choice": "auto"}
+
+
+def test_tool_choice_is_never_sent_without_tools():
+ """`tool_choice: auto` alone is just as invalid as an empty `tools` array."""
+ assert "tool_choice" not in _model([])._tool_request_kwargs()
+ assert "tool_choice" not in _model(None)._tool_request_kwargs()
+
+
+class _RecordingClient:
+ """Captures the kwargs of the single completion request the tool loop makes."""
+
+ def __init__(self):
+ self.kwargs = None
+ message = SimpleNamespace(content="answer", tool_calls=None, reasoning_content=None)
+ self._response = SimpleNamespace(
+ choices=[SimpleNamespace(message=message, finish_reason="stop")],
+ usage=SimpleNamespace(prompt_tokens=1, completion_tokens=1, total_tokens=2),
+ )
+
+ async def create(**kwargs):
+ self.kwargs = kwargs
+ return self._response
+
+ self.chat = SimpleNamespace(completions=SimpleNamespace(create=create))
+
+
+def _loop_model(tools):
+ """A Base wired to a recording client, without running __init__."""
+ mdl = Base.__new__(Base)
+ mdl.tools = tools
+ mdl.is_tools = bool(tools)
+ mdl.model_name = "some-model"
+ mdl.max_rounds = 1
+ mdl.max_retries = 0
+ mdl.toolcall_session = None
+ mdl.verbose_tool_use = False
+ mdl.async_client = _RecordingClient()
+ return mdl
+
+
+async def test_caller_supplied_tool_fields_never_reach_the_provider():
+ """`llm_setting` may carry `tools`/`tool_choice`: ALLOWED_GEN_CONF_KEYS lets
+ both through `_clean_conf`. The tool loop owns those fields, so a caller's
+ copy must be dropped rather than merged into the request."""
+ mdl = _loop_model([])
+
+ await mdl.async_chat_with_tools("sys", [{"role": "user", "content": "hi"}], {"temperature": 0.1, "tools": [], "tool_choice": "auto"})
+
+ sent = mdl.async_client.kwargs
+ assert "tools" not in sent
+ assert "tool_choice" not in sent
+ assert sent["temperature"] == 0.1
+
+
+async def test_bound_tools_win_over_caller_supplied_ones():
+ """Merging both would raise TypeError on the duplicate keyword."""
+ mdl = _loop_model(SCHEMAS)
+
+ await mdl.async_chat_with_tools("sys", [{"role": "user", "content": "hi"}], {"tools": [], "tool_choice": "none"})
+
+ sent = mdl.async_client.kwargs
+ assert sent["tools"] == SCHEMAS
+ assert sent["tool_choice"] == "auto"