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

> Understand max_researcher_iterations in Open Deep Research. Learn how this parameter limits supervisor loop tool calls and forces termination for efficient research management.

- Repository: [LangChain/open_deep_research](https://github.com/langchain-ai/open_deep_research)
- Tags: deep-dive
- Published: 2026-07-23

---

**`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`](https://github.com/langchain-ai/open_deep_research/blob/main/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`](https://github.com/langchain-ai/open_deep_research/blob/main/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`](https://github.com/langchain-ai/open_deep_research/blob/main/src/open_deep_research/deep_researcher.py). After the supervisor finishes a step, the code evaluates:

```python
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

```python
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`](https://github.com/langchain-ai/open_deep_research/blob/main/tests/run_evaluate.py):

```python

# 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:

```python

# 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`](https://github.com/langchain-ai/open_deep_research/blob/main/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`](https://github.com/langchain-ai/open_deep_research/blob/main/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`](https://github.com/langchain-ai/open_deep_research/blob/main/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`](https://github.com/langchain-ai/open_deep_research/blob/main/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.