Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(langgraph-agent): align MAX_SUBTOPICS with 'pass 2-5' contract and make truncation observable (#5012) (#5013)

Sb4d800466f07
diff --git a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
index f54a8fce4c..8f0518a480 100644
--- a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
@@ -19,11 +19,11 @@ from langchain_core.tools import tool
from langgraph.errors import GraphRecursionError
from loguru import logger
-from ...utilities.thread_context import get_search_context, search_context
from ...citation_handler import CitationHandler
+from ...security import sanitize_error_for_client
+from ...utilities.thread_context import get_search_context, search_context
from ..tools.fetch import FETCH_MODES, build_fetch_tool
from .base_strategy import BaseSearchStrategy
-from ...security import sanitize_error_for_client
# ---------------------------------------------------------------------------
# Constants
@@ -34,7 +34,10 @@ DEFAULT_MAX_ITERATIONS = (
)
MIN_ITERATIONS = 10 # below this the agent can barely do anything useful
SUBAGENT_TIMEOUT_SECONDS = 1800 # 30 minutes per subagent
-MAX_SUBTOPICS = 8
+MAX_SUBTOPICS = 5 # must match the "pass 2-5" contract in the lead prompt
+# and the research_subtopic tool docstring. Values above this are dropped
+# at the call site, with the dropped subtopics named in the tool's reply
+# so the lead agent can re-issue or avoid citing them.
MAX_SUBAGENT_WORKERS = 4
# CONTENT_FETCH_TIMEOUT and CONTENT_MAX_LENGTH live alongside the fetch
# tool builders in advanced_search_system/tools/fetch/.
@@ -316,19 +319,35 @@ def _make_research_subtopic_tool(
if not subtopics:
return "No subtopics provided."
- if len(subtopics) > MAX_SUBTOPICS:
+
+ requested_count = len(subtopics)
+ truncated_from: int | None = None
+ dropped_subtopics: list[str] = []
+ if requested_count > MAX_SUBTOPICS:
+ logger.warning(
+ "research_subtopic received {} subtopics; truncating to MAX_SUBTOPICS={}",
+ requested_count,
+ MAX_SUBTOPICS,
+ )
+ dropped_subtopics = subtopics[MAX_SUBTOPICS:]
subtopics = subtopics[:MAX_SUBTOPICS]
+ truncated_from = requested_count
# Emit progress for UI
if progress_callback:
+ meta = {
+ "phase": "sub_research",
+ "type": "milestone",
+ "subtopics": subtopics,
+ }
+ # Only surface the truncation key when subtopics were actually
+ # dropped, so UI consumers don't have to special-case a None value.
+ if truncated_from is not None:
+ meta["truncated_from"] = truncated_from
progress_callback(
f"Researching {len(subtopics)} subtopics in parallel",
None,
- {
- "phase": "sub_research",
- "type": "milestone",
- "subtopics": subtopics,
- },
+ meta,
)
current_date = datetime.now(UTC).strftime("%Y-%m-%d")
@@ -465,7 +484,18 @@ def _make_research_subtopic_tool(
parts.append(
f"## {topic}\n{ordered_results.get(topic, 'No results')}"
)
- return "\n\n---\n\n".join(parts)
+ result_text = "\n\n---\n\n".join(parts)
+
+ # Surface the truncation to the lead agent itself (not just logs/UI):
+ # otherwise the model believes the dropped subtopics were investigated
+ # and may cite them. Addresses issue #2 (PR #5012).
+ if dropped_subtopics:
+ result_text += (
+ f"\n\nNote: {len(dropped_subtopics)} subtopic(s) beyond the limit "
+ f"of {MAX_SUBTOPICS} were not investigated: "
+ f"{', '.join(dropped_subtopics)}"
+ )
+ return result_text
return research_subtopic
@@ -719,9 +749,6 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
# forbidden tools never reach create_agent(), and the LLM never
# learns they exist.
try:
- from local_deep_research.web_search_engines.search_engines_config import (
- get_available_engines,
- )
from local_deep_research.security.egress.policy import (
EgressScope,
evaluate_engine,
@@ -730,6 +757,9 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
from local_deep_research.web_search_engines.retriever_registry import (
retriever_registry,
)
+ from local_deep_research.web_search_engines.search_engines_config import (
+ get_available_engines,
+ )
available = get_available_engines(
settings_snapshot=self.settings_snapshot,
@@ -932,7 +962,8 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
"Strategy:\n"
"1. Start with web_search for initial exploration.\n"
"2. For complex multi-faceted questions, use research_subtopic to "
- "investigate specific aspects in parallel (pass 2-5 focused questions).\n"
+ f"investigate specific aspects in parallel (pass 2-{MAX_SUBTOPICS} "
+ f"focused, non-overlapping questions — at most {MAX_SUBTOPICS}).\n"
f"{fetch_line}"
"4. Use search_[engine] tools for domain-specific searches "
"(search_arxiv for science, search_pubmed for medical, etc.).\n"
diff --git a/tests/strategies/test_langgraph_agent_strategy.py b/tests/strategies/test_langgraph_agent_strategy.py
index 94198ecdd8..69b1c03d83 100644
--- a/tests/strategies/test_langgraph_agent_strategy.py
+++ b/tests/strategies/test_langgraph_agent_strategy.py
@@ -1588,3 +1588,189 @@ class TestEgressScopePolicyAddendum:
assert "RESTRICTED MODE" not in prompt
assert "PRIVATE-ONLY MODE" not in prompt
assert "PUBLIC-ONLY MODE" not in prompt
+
+
+# ---------------------------------------------------------------------------
+# research_subtopic truncation (LANGGRAPH_AGENT_REVIEW.md issue #2)
+# ---------------------------------------------------------------------------
+
+
+class _ImmediateFuture:
+ """Minimal future that runs the callable synchronously on result()."""
+
+ def __init__(self, fn, arg):
+ self._fn = fn
+ self._arg = arg
+
+ def result(self, timeout=None):
+ return self._fn(self._arg)
+
+
+class _ImmediateExecutor:
+ """ThreadPoolExecutor stand-in that runs tasks synchronously."""
+
+ def __init__(self, max_workers=None):
+ self._max_workers = max_workers
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc):
+ return False
+
+ def submit(self, fn, arg):
+ return _ImmediateFuture(fn, arg)
+
+
+def _fake_as_completed(futures, timeout=None):
+ for f in futures:
+ yield f
+
+
+class TestResearchSubtopicToolTruncation:
+ """Regression tests for issue #2: MAX_SUBTOPICS vs the 'pass 2-5' contract.
+
+ Covers the silent-truncation path that previously dropped subtopics with no
+ warning/feedback to the lead (LANGGRAPH_AGENT_REVIEW.md, Part 1 issue #2).
+ """
+
+ MODULE = (
+ "local_deep_research.advanced_search_system.strategies."
+ "langgraph_agent_strategy"
+ )
+
+ def _make_tool(self, progress_callback=None):
+ from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (
+ MAX_SUBTOPICS,
+ SearchResultsCollector,
+ _make_research_subtopic_tool,
+ )
+
+ collector = SearchResultsCollector([])
+ tool = _make_research_subtopic_tool(
+ search_engine_name="duckduckgo",
+ model=MagicMock(),
+ settings_snapshot={"search.tool": {"value": "duckduckgo"}},
+ collector=collector,
+ max_sub_iterations=8,
+ progress_callback=progress_callback,
+ )
+ return tool, MAX_SUBTOPICS
+
+ def _patched_run(self, subtopics, progress_callback=None):
+ import local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy as mod
+
+ tool, max_sub = self._make_tool(progress_callback)
+
+ agent_mock = MagicMock()
+ agent_mock.invoke.return_value = {
+ "messages": [MagicMock(content="finding for topic")]
+ }
+ with patch.object(
+ mod, "_make_web_search_tool", return_value=MagicMock()
+ ):
+ with patch.object(mod, "build_fetch_tool", return_value=None):
+ with patch(
+ "langchain.agents.create_agent", return_value=agent_mock
+ ):
+ with patch.object(
+ mod, "ThreadPoolExecutor", _ImmediateExecutor
+ ):
+ with patch.object(
+ mod, "as_completed", _fake_as_completed
+ ):
+ result = tool.invoke({"subtopics": subtopics})
+ return result, max_sub
+
+ def test_constant_matches_prompt_contract(self):
+ from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (
+ MAX_SUBTOPICS,
+ LangGraphAgentStrategy,
+ )
+
+ # The constant must agree with the 'pass 2-5' docstring + lead prompt.
+ assert MAX_SUBTOPICS == 5
+
+ # And the lead prompt must render the *same* constant, so the two
+ # can't silently drift apart again (reviewer note on PR #5013: a magic
+ # number in the prompt text could otherwise diverge from MAX_SUBTOPICS).
+ captured = {}
+
+ def _fake_create_agent(model=None, tools=None, system_prompt=None):
+ captured["system_prompt"] = system_prompt
+ return MagicMock()
+
+ strategy = LangGraphAgentStrategy(
+ model=MagicMock(),
+ search=MagicMock(),
+ settings_snapshot={},
+ max_sub_iterations=8,
+ )
+ with patch(
+ "langchain.agents.create_agent", side_effect=_fake_create_agent
+ ):
+ with patch.object(
+ strategy,
+ "_build_tools",
+ return_value=[MagicMock(name="web_search")],
+ ):
+ strategy.analyze_topic("does the prompt honor the limit?")
+
+ prompt = captured["system_prompt"]
+ assert f"at most {MAX_SUBTOPICS}" in prompt
+ assert f"pass 2-{MAX_SUBTOPICS}" in prompt
+
+ def test_no_truncation_below_limit(self):
+ captured = {}
+ subtopics = [f"topic {i}" for i in range(3)]
+
+ result, _ = self._patched_run(
+ subtopics,
+ progress_callback=lambda *a: captured.update({"meta": a[2]}),
+ )
+
+ assert "## topic 0" in result
+ assert "## topic 2" in result
+ # No truncation -> the truncation metadata key is omitted entirely,
+ # so UI consumers don't have to special-case a None value.
+ assert "truncated_from" not in captured["meta"]
+
+ def test_truncation_above_limit_drops_extra_and_warns(self):
+ captured = {}
+ subtopics = [f"topic {i}" for i in range(8)]
+
+ with patch(
+ "local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy.logger"
+ ) as log:
+ result, max_sub = self._patched_run(
+ subtopics,
+ progress_callback=lambda *a: captured.update({"meta": a[2]}),
+ )
+
+ # Only the first MAX_SUBTOPICS topics are actually investigated.
+ assert "## topic 0" in result
+ assert "## topic 4" in result
+ assert "## topic 5" not in result # dropped (6th..8th)
+ assert max_sub == 5
+
+ # Progress metadata surfaces the truncation to the UI.
+ assert captured["meta"].get("truncated_from") == 8
+
+ # A warning is emitted at the truncation point (fix for #2).
+ assert log.warning.called
+
+ def test_truncation_above_limit_notes_dropped_in_output(self):
+ subtopics = [f"topic {i}" for i in range(8)]
+
+ result, _ = self._patched_run(subtopics)
+
+ # The lead model must be told which subtopics were dropped, so it can
+ # avoid citing uninvestigated topics or re-issue a follow-up call.
+ # This is the core of issue #2: truncation was previously invisible to
+ # the model (logs/UI only).
+ assert "Note:" in result
+ assert "beyond the limit" in result
+ assert "not investigated" in result
+ # The dropped subtopics (indices 5..7) are named explicitly.
+ assert "topic 5" in result
+ assert "topic 7" in result