What Does `max_researcher_iterations` Control in the Open Deep Research Supervisor Loop?

max_researcher_iterations is a configuration parameter that hard-caps how many research and thinking tool calls the supervisor node may execute before it is forced to terminate the loop and return the current findings.

In the langchain-ai/open_deep_research project, the supervisor loop iteratively delegates sub-tasks to a researcher and performs strategic planning. The max_researcher_iterations setting acts as a safety budget that prevents runaway tool usage during a single research run.

How the Supervisor Loop Counts Iterations

Inside the supervisor logic found in src/open_deep_research/deep_researcher.py, the graph maintains an internal counter called research_iterations. This counter increments each time the supervisor invokes a research-related tool.

Tools That Increment the Counter

According to the system prompt in src/open_deep_research/prompts.py, the supervisor is told to stop after {max_researcher_iterations} calls to the following tools:

• ConductResearch – delegates a sub-task to the researcher node.
• think_tool – lets the supervisor perform a strategic "thinking" step.

Every invocation of either tool advances the research_iterations tally by one.

Where the Limit Is Enforced

The guard clause that enforces the ceiling is implemented directly in src/open_deep_research/deep_researcher.py. After the supervisor finishes a step, the code evaluates:

configurable = Configuration.from_runnable_config(config)
research_iterations = state["research_iterations"]
exceeded_allowed_iterations = (
    research_iterations > configurable.max_researcher_iterations
)

If exceeded_allowed_iterations evaluates to True, the supervisor exits the loop rather than issuing another tool call.

Configuring max_researcher_iterations

You can set the limit at runtime through the Configuration model or a RunnableConfig dictionary.

Setting the Limit via RunnableConfig

from langgraph.types import RunnableConfig

# Cap the research phase at 4 iterations

config: RunnableConfig = {
    "configurable": {
        "max_researcher_iterations": 4,
        # ...other configurable fields...

    }
}

Overriding the Limit in Tests

The test suite demonstrates practical usage in tests/run_evaluate.py:

# tests/run_evaluate.py

max_researcher_iterations = 6
config["configurable"]["max_researcher_iterations"] = max_researcher_iterations

Typical test values are 3 or 6, but the field is fully user-configurable.

What Happens When the Limit Is Reached

Once research_iterations exceeds max_researcher_iterations, the supervisor treats the budget as exhausted. Instead of dispatching another ConductResearch or think_tool call, it returns a termination command:

# src/open_deep_research/deep_researcher.py (excerpt)

if exceeded_allowed_iterations:
    # Terminate the loop and return current findings

    return Command(goto="research_complete")

This causes the graph to transition to a completion node, finalize the gathered results, and exit the supervisor loop so the final report can be generated.

Summary

• max_researcher_iterations sets a hard upper bound on supervisor tool calls in a single research run.
• The counter tracks combined invocations of ConductResearch and think_tool.
• Enforcement lives in src/open_deep_research/deep_researcher.py via the exceeded_allowed_iterations check.
• You can configure the value through the Configuration model or a RunnableConfig dictionary.
• When the limit is crossed, the supervisor exits to a research-complete state instead of looping indefinitely.

Frequently Asked Questions

Which tool calls count toward max_researcher_iterations?

Both ConductResearch and think_tool increment the internal research_iterations counter. The system prompt in src/open_deep_research/prompts.py explicitly instructs the model to treat these two tools as part of the same budget.

Where is max_researcher_iterations defined?

It is declared as a field on the Configuration model in src/open_deep_research/configuration.py. At runtime, the supervisor loads it with Configuration.from_runnable_config(config).

What is the default value of max_researcher_iterations?

The raw test files set the value to 3 or 6 depending on the scenario, but the parameter is fully user-configurable and accepts any integer you pass through the config dictionary.

How does the supervisor know when to stop?

After each step, the supervisor compares state["research_iterations"] against configurable.max_researcher_iterations in src/open_deep_research/deep_researcher.py. If the counter is greater than the configured limit, the function returns a Command(goto="research_complete"), forcing the graph to finish.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}