Building a LangChain deep agent that does real research

A langchain deep agent is not a smarter ReAct loop. It is a different architecture. Where a standard ReAct chain calls tools sequentially inside one growing context window, a deep agent assigns each sub-task to a capped executor, lets it run to completion, and feeds only the result back to the orchestrator. The practical gap shows up on tasks like multi-source research: a problem that breaks most flat chains before the synthesis step runs reliably in this model. This walkthrough covers the structural differences, the deepagents library that LangChain shipped in July 2025 on top of LangGraph, and the setup for a working autonomous research pipeline.

What separates a deep agent from a standard ReAct loop

Standard ReAct follows a tight reason/act/observe cycle. Every tool call appends tokens to a single shared context. For tasks that touch three or four sources, this holds up. For anything longer, the math works against you.

A flat chain with parallel tool calls exhausts a 128k-token context in under 20 turns, because every intermediate observation accumulates. By turn 15 of a multi-source research task, the context is dense with raw HTML excerpts, redundant search snippets, and partial reasoning steps the model cannot prune.

A langchain deep agent solves this with three structural differences. First, an explicit planning step: before any tool runs, the orchestrator decomposes the query into discrete sub-tasks (search, fetch, extract, compare) and writes them to a structured plan. Second, sub-agent delegation: each sub-task is handed to an isolated executor with its own bounded context, when that executor finishes, only its summary returns to the orchestrator. Third, a lean orchestrator context: the planner holds the global goal, the plan state, and accumulated results, but never sees raw intermediate content.

The trade-off is added latency per sub-task and result-merging overhead. A long-running agent running 10 sub-tasks takes longer end-to-end than a flat chain attempting the same search. The benefit? It actually finishes.

LangChain deep agent architecture: planning, context, and orchestration

LangChain open-sourced the deepagents library on July 30, 2025. It is built on LangGraph's durable execution runtime, which handles state persistence, retries, and streaming natively. The library ships with a default tool registry (web search, URL fetch, text extraction), streaming support out of the box, and override hooks at every stage of the loop.

The execution model has three phases: plan, execute, and synthesize.

The planning tool: how the orchestrator breaks down a query

The planning tool is the orchestrator's first action. It receives the raw query and a context budget parameter, then outputs an ordered list of sub-tasks with explicit input/output contracts: what each executor receives and what schema it must return.

You can override the planner by passing a custom PlanningTool instance to the DeepAgent constructor. The default planner uses the same LLM as the orchestrator, though pointing it at a cheaper model (gpt-4o-mini or Claude Haiku) is common practice to reduce cost on the planning step specifically.

Sub-agent delegation and result merging

Each executor receives its sub-task specification, a constrained tool registry limited to what that sub-task actually needs, and a hard token cap. When the cap is hit, the executor finalizes and returns whatever it has rather than continuing. This cap is the key guard against runaway context growth.

The result merging step is a plain callable. The default implementation concatenates structured outputs in plan order. You can swap in a custom merger for heterogeneous schemas. The entire langchain deep agent loop is stateful via LangGraph checkpoints, so a failed sub-task can be retried without restarting the pipeline from scratch.

Installing deepagents and running your first query

Requirements: Python 3.11 or higher, LangGraph >= 0.2. The version constraint on LangGraph was locked in Q4 2025 when the state checkpointing API stabilized.

pip install deepagents

Set your credentials:

export OPENAI_API_KEY=sk-...
export TAVILY_API_KEY=tvly-...

Minimum working example for a multi-step AI workflow:

from deepagents import DeepAgent
from langchain_openai import ChatOpenAI

agent = DeepAgent(
    llm=ChatOpenAI(model="gpt-4o"),
    sub_agent_llm=ChatOpenAI(model="gpt-4o-mini"),
)

for chunk in agent.stream("Compare the API pricing of Anthropic, OpenAI, and Google as of 2026"):
    print(chunk, end="", flush=True)

The stream() call emits the plan as a JSON block first, then streams sub-task results as executors complete, then delivers the final synthesis. Use agent.invoke() if you do not need streaming.

Two environment variables control context budgets: DEEPAGENTS_ORCHESTRATOR_BUDGET (default: 8,000 tokens) and DEEPAGENTS_SUBAGENT_BUDGET (default: 16,000 tokens per executor). Both can also be passed directly to the constructor as integers. A practical split: use gpt-4o on the orchestrator where reasoning quality matters, and gpt-4o-mini on executors where volume matters more than nuance.

Adding real research tools: search, scrape, synthesize

The default tool registry handles common cases, but the choice of search backend has a direct impact on result quality and cost.

Tavily is built for RAG and AI research agent workflows. Its free tier covers 1,000 searches per month, then charges $0.004 per search beyond that. Results include extracted page summaries by default, which reduces the need for a separate scraping step in most configurations.

Exa uses a neural retrieval model trained on web content, priced at $0.005 per search call. It returns fewer results per query but typically with higher relevance, which reduces token waste during result merging. The two backends are not mutually exclusive: it is common to run Tavily for broad coverage and Exa for high-precision follow-up queries on the same task.

For full-page content when summaries are insufficient, add a lightweight HTML extractor to the executor tool registry. The browser-use community tool pack handles JavaScript-rendered pages. The extractor returns cleaned text to the executor, which summarizes before reporting back to the orchestrator. An optional vector store (Chroma, Pinecone, or Qdrant) can sit between sub-tasks as a deduplication layer, so the AI web crawler does not process the same URL twice when multiple executors retrieve overlapping sources.

Cost estimate for a typical run: a 10-source research task with gpt-4o-mini as the sub-agent model consumes roughly 40,000 tokens total. At late-2025 pricing, that puts the cost of a complete research run well under $0.05 for most configurations. 💰

The deepagents ecosystem in 2026: what has stabilized and what is still moving

Between the July 2025 release and mid-2026, the library has matured in some areas and remained volatile in others.

The planning layer has largely stabilized. LangGraph Studio added visual debugger support for deepagents graphs in late 2025, making it practical to trace plan state, executor inputs, and result merges in a UI rather than parsing log output. The community has shipped two tool packs worth using in production: a browser-use integration for JavaScript-rendered pages, and a structured-output planner that enforces JSON schema on the plan step, which reduces malformed plan failures significantly. LangChain also published a deep-agents course on the LangChain Academy platform in early 2026, which remains the fastest path to understanding the library's extension points.

Two gaps remain open heading into mid-2026. Sub-agent memory isolation is incomplete: if you need one executor to read an artifact produced by a previous executor, you have to route it through the orchestrator explicitly. There is no shared scratchpad between sub-agents. Per-task cost accounting (knowing exactly how many tokens each sub-task consumed) is also not surfaced in the public API, approximating it requires wrapping LLM calls with custom token counters.

As a deep research bot handling stateless multi-source queries, deepagents is production-ready. For stateful workflows where sub-agents need to build on each other's intermediate context across multiple turns, you will hit the memory isolation limit quickly. That is the case to test before committing.

Key takeaways

A langchain deep agent distributes work across bounded executors instead of accumulating every intermediate result in one context window. The deepagents library, built on LangGraph and released in July 2025, provides this architecture with a default tool registry, streaming, and checkpoint-based retries. By mid-2026, the planning layer and visual debugger support have stabilized. Sub-agent memory isolation and per-task cost accounting remain the two gaps to account for before building stateful pipelines.

---

Deep agents break research into bounded sub-tasks instead of one growing context window, which is why multi-source research actually finishes. The CLI blueprint in the welcome kit shows you how to wire retrieval tools as agent commands so Claude can chain them without token bloat.

→ Get the welcome kit