Open Studio
system breakdown

Inside Open Deep Research: Hierarchical Supervisor Fan-Out, Subgraph Compression & Multi-Provider Search Architecture

A production teardown of LangChain's Open Deep Research agent—deconstructing bounded parallel researcher subgraphs, subgraph-level context compression, override_reducer state channels, progressive token-limit recovery, and RFC 8693 MCP OAuth token exchange.

FullStack AI Hub Editorial22 min readPublished 29 Sep 20262 primary sources
Inside Open Deep Research: Hierarchical Supervisor Fan-Out, Subgraph Compression & Multi-Provider Search Architecture

Evidence boundary

This system breakdown analyzes the Open Deep Research agent (src/open_deep_research), Supabase auth middleware (src/security/auth.py), and Deep Research Bench evaluation harness (tests/evaluators.py) at commit 1b7d2e80db9faa586165c60e09096dbbfd483a64 (release v0.0.16).


1. Hierarchical 3-Graph Topology & override_reducer State Channels

Open Deep Research decomposes long-horizon web synthesis into three nested LangGraph StateGraph machines: the outer deep_researcher pipeline, the middle supervisor_subgraph, and the inner researcher_subgraph:

code(22 lines)
1+-----------------------------------------------------------------------------+
2| Outer Graph: deep_researcher (AgentState) |
3| [clarify_with_user] -> [write_research_brief] -> [research_supervisor] |
4| | |
5| v |
6| [final_report_generation] |
7+-----------------------------------------------------------------------------+
8 |
9 +-------------------------------------------------+
10 v
11+-----------------------------------------------------------------------------+
12| Middle Subgraph: supervisor_subgraph (SupervisorState) |
13| [supervisor] <---> [supervisor_tools] (think_tool, ConductResearch fan-out) |
14+-----------------------------------------------------------------------------+
15 |
16 | asyncio.gather(*research_tasks[:max_concurrent_research_units])
17 v
18+-----------------------------------------------------------------------------+
19| Inner Worker Subgraph: researcher_subgraph (ResearcherState) |
20| [researcher] <---> [researcher_tools] (Tavily / MCP) -> [compress_research] |
21+-----------------------------------------------------------------------------+
Missing evidence claim: odr-override-state-reducer

Standard LangGraph operator.add reducers only append to list channels, making it impossible to reset a sub-graph's scratchpad or clear accumulated notes after final report synthesis without mutating state in place. In src/open_deep_research/state.py, override_reducer solves this with a tagged dictionary protocol:

python(7 lines)
1def override_reducer(current_value, new_value):
2 """Reducer function that allows overriding values in state."""
3 if isinstance(new_value, dict) and new_value.get("type") == "override":
4 return new_value.get("value", new_value)
5 else:
6 return operator.add(current_value, new_value)

When write_research_brief initializes the supervisor or final_report_generation flushes completed notes, it emits {"type": "override", "value": [...]} to deterministically reset the channel while preserving incremental operator.add semantics during normal loop turns.


2. Bounded Supervisor Fan-Out & Deliberate Reflection

Missing evidence claim: odr-hierarchical-supervisor-fanout

After clarify_with_user verifies scope clarity (or halts early with a clarifying question via Command(goto=END)) and write_research_brief synthesizes a ResearchQuestion, control enters supervisor_subgraph.

The Lead Researcher model is bound to three structured tools:

  1. think_tool: Forces a deliberate reflection pause to evaluate gathered evidence and identify missing sub-topics before issuing new searches.
  2. ConductResearch: Delegates a detailed, single-topic investigation to an isolated worker subgraph.
  3. ResearchComplete: Signals termination of the research loop.

To prevent rate-limit exhaustion when the supervisor emits a wide fan-out of ConductResearch calls in a single turn, supervisor_tools enforces hard concurrency slicing:

python(12 lines)
1allowed_conduct_research_calls = conduct_research_calls[:configurable.max_concurrent_research_units]
2overflow_conduct_research_calls = conduct_research_calls[configurable.max_concurrent_research_units:]
3
4research_tasks = [
5 researcher_subgraph.ainvoke({
6 "researcher_messages": [HumanMessage(content=tool_call["args"]["research_topic"])],
7 "research_topic": tool_call["args"]["research_topic"]
8 }, config)
9 for tool_call in allowed_conduct_research_calls
10]
11tool_results = await asyncio.gather(*research_tasks)

Any tool calls beyond max_concurrent_research_units (default 5) immediately receive an explicit backpressure ToolMessage instructing the supervisor to re-queue those topics on the next iteration.


3. URL Deduplication, Subgraph Compression & Progressive Truncation

Missing evidence claim: odr-subgraph-compression-isolation

If five sub-researchers each execute 6 multi-query web searches, raw webpage scrapes easily exceed 500,000 tokens. Open Deep Research applies a three-tier context defense pipeline:

  1. In-Tool URL Deduplication & Timeout-Bounded Summarization (utils.py): tavily_search executes multiple queries via AsyncTavilyClient, deduplicates results by URL across the batch, truncates raw HTML/markdown to max_content_length (50,000 characters), and runs parallel summarize_webpage calls wrapped in asyncio.wait_for(..., timeout=60.0).
  2. Subgraph-Level compress_research Isolation (deep_researcher.py): When a sub-researcher finishes its ReAct loop, compress_research invokes compression_model to distill the entire researcher_messages trajectory into a structured synthesis (ResearcherOutputState.compressed_research). Only this compressed synthesis is returned as the ToolMessage observation to supervisor_messages, while raw scrapes are sidelined into raw_notes for downstream evaluation.
  3. Progressive Context-Overflow Recovery:
Missing evidence claim: odr-progressive-token-truncation

Provider exceptions are inspected by is_token_limit_exceeded() across OpenAI (context_length_exceeded), Anthropic (prompt is too long), and Gemini (ResourceExhausted). If compress_research overflows, it strips older turns via remove_up_to_last_ai_message(). If final_report_generation overflows, it looks up MODEL_TOKEN_LIMITS and applies iterative 10% character truncation across up to 3 retries:

python(7 lines)
1if current_retry == 1:
2 model_token_limit = get_model_token_limit(configurable.final_report_model)
3 findings_token_limit = model_token_limit * 4
4else:
5 findings_token_limit = int(findings_token_limit * 0.9)
6findings = findings[:findings_token_limit]

4. RFC 8693 MCP OAuth Token Exchange & Multi-Rubric Evaluation

Missing evidence claim: odr-mcp-oauth-token-exchange

In multi-tenant deployments (src/security/auth.py), LangGraph @auth.authenticate verifies the caller's Supabase JWT in a worker thread (asyncio.to_thread(supabase.auth.get_user, token)) and stamps metadata["owner"] = ctx.user.identity on every thread, assistant, and store namespace.

When a researcher connects to an authenticated Model Context Protocol (MCP) server over streamable_http, get_mcp_access_token() performs an RFC 8693 OAuth 2.0 Token Exchange (urn:ietf:params:oauth:grant-type:token-exchange), trading the user's x-supabase-access-token for a resource-scoped MCP token cached in LangGraph's BaseStore under (user_id, "tokens"). Each MCP tool is wrapped by wrap_mcp_authenticate_tool(), which recursively traverses Python 3.11+ ExceptionGroup chains for McpError code -32003 (interaction required) and surfaces actionable authorization URLs via ToolException.

Finally, tests/evaluators.py benchmarks generated reports across six LLM-as-a-judge dimensions (OverallQualityScore, RelevanceScore, StructureScore, CorrectnessScore, CompletenessScore, and claim-by-claim GroundednessScore verified against raw_notes), utilizing Anthropic cache_control={"type": "ephemeral", "ttl": "1h"} breakpoints to amortize judge prompt tokens across multi-criteria evaluations.

Continue Reading

All Blog Posts