LangChain Deep Agents — Agent Architecture

LangChain Deep Agents — The Batteries-Included Agent Harness, Explained

LangChain Open Source Python & TypeScript GitHub Repo (Python) ↗ GitHub Repo (JS/TS) ↗ Official Docs ↗

Overview

LangChain just open-sourced Deep Agents — an opinionated, batteries-included agent harness built on top of LangGraph. Inspired by Claude Code, Deep Agents gives you planning, filesystem access, sub-agent orchestration, context management, and persistent memory out of the box. It works with any model that supports tool calling, from frontier APIs like OpenAI and Anthropic to self-hosted models via Ollama or vLLM. Available in both Python and TypeScript, this article explains what Deep Agents is, why it exists, how the architecture works, and walks through a practical example in both languages.

1 What Are Deep Agents?

Deep Agents is an open-source agent harness — a term LangChain uses to describe an opinionated agent framework that comes batteries-included with built-in tools and capabilities. Unlike minimal agent loops where you wire everything yourself, Deep Agents gives you a production-ready agent that runs out of the box.

The key distinction from other LangChain tools:

LangGraph — the low-level graph runtime for building stateful workflows
LangChain's create_agent — a minimal agent harness on top of LangGraph
Deep Agents — a fully opinionated harness on top of create_agent, bundling filesystem, sub-agents, context management, and skills

Think of it this way: LangGraph is the engine, create_agent is a basic car, and Deep Agents is a fully loaded vehicle with GPS, cruise control, and autopilot built in.

2 Why Deep Agents Exists

AI agents are taking on increasingly complex, long-running work — multi-step research, autonomous coding, data pipelines that run for hours. Traditional single-turn agent loops struggle with this because they hit fundamental bottlenecks:

Context window overflow — long tasks accumulate tool outputs and conversation history that blow past token limits
No persistent state — the agent forgets everything between sessions, forcing repeated work
No delegation — a single agent trying to do everything creates a cognitive bottleneck
No planning — without the ability to decompose tasks, agents get lost in complex objectives

Deep Agents was built specifically to solve these problems. It provides the infrastructure layer that long-running, autonomous agents need — so developers can focus on their domain logic instead of reinventing agent plumbing.

Inspired by Claude Code — LangChain's stated goal was to identify what makes Claude Code's general-purpose approach work, and push that further as an open, extensible framework.

3 Core Architecture

Deep Agents ships as two separate repositories — one for Python, one for TypeScript — each structured as a monorepo with independently versioned packages:

libs/deepagents/ — the core SDK (create_deep_agent in Python, createDeepAgent in TS)
libs/code/ — "Deep Agents Code", a terminal-based coding agent (like Claude Code, but model-agnostic)
libs/cli/ — deployment CLI for production environments
libs/acp/ — Agent Context Protocol integration
libs/evals/ — evaluation suite and Harbor integration
libs/partners/ — provider integrations (e.g., Daytona for sandboxed environments)

The architecture follows a layered composition model. Any LangGraph CompiledStateGraph can be passed in as a sub-agent, so custom orchestration plugs in alongside the harness defaults.

4 Key Features In-Depth

🔀 Sub-agents with Isolated Context

Deep Agents can spawn sub-agents that operate with their own isolated context windows. This means a research task can delegate to a "web searcher" sub-agent and a "critic" sub-agent running in parallel, each with their own conversation history. The parent agent stays focused on orchestration while children handle the details.

📋 Planning Tools

Built-in planning primitives (write_todos) let agents decompose complex objectives into trackable sub-tasks, monitor progress, and adapt their plan as new information arrives. This is critical for multi-step workflows where the path isn't known in advance.

💾 Persistent Memory

Deep Agents includes a virtual filesystem that persists system prompts, learned skills, and long-term memory across sessions. Pluggable state and store backends mean you can swap in whatever persistence layer your infrastructure uses.

🧠 Native Context Management

Context management middleware automatically handles the biggest pain point of long-running agents:

Conversation compression — summarizes old history to stay within token limits
Tool output offloading — moves large tool results to disk to free context space
Sub-agent isolation — each child agent gets its own context, preventing cross-contamination
Prompt caching — reduces latency and cost for repeated patterns

🛡️ Human-in-the-Loop

Every tool call can be intercepted — approve, edit, or reject before execution. This gives you safety rails for high-stakes operations while still allowing fully autonomous mode when appropriate.

🔧 Extensible Tools and MCP Support

Bring your own functions as tools, or connect any MCP (Model Context Protocol) server. Deep Agents is designed to be extended, not replaced — override any piece without forking the framework.

5 Model Compatibility

Deep Agents is fully model-agnostic. Any LLM that supports tool calling works:

Frontier APIs — OpenAI (GPT-4o, GPT-5.5), Anthropic (Claude), Google (Gemini)
Open-weight hosted — models on Baseten, Fireworks, Together AI
Self-hosted — Ollama, vLLM, llama.cpp for fully local deployments

In Python, you specify the model as a string like "openai:gpt-5.5". In TypeScript, you pass a LangChain chat model instance like new ChatOpenAI({ model: "gpt-5" }).

6 Getting Started — A Practical Example

Here's how to build a simple research agent with Deep Agents that can search the web, delegate to a critic, and write reports. Every step is shown in both Python and TypeScript.

Step 1: Install

Python TypeScript

# Install with uv (recommended) or pip
uv add deepagents tavily-python

// Install with npm, pnpm, or yarn
npm install deepagents @langchain/anthropic @langchain/tavily zod

Step 2: Define a Custom Tool

Python TypeScript

from tavily import TavilyClient

tavily = TavilyClient()

def internet_search(query: str) -> str:
    """Search the internet for current information."""
    results = tavily.search(query=query, max_results=5)
    return "\n".join(
        f"{r['title']}: {r['content']}"
        for r in results["results"]
    )

import { z } from "zod";
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";

const internetSearch = tool(
  async ({ query, maxResults = 5 }: {
    query: string; maxResults?: number;
  }) => {
    const tavily = new TavilySearch({ maxResults });
    return await tavily._call({ query });
  },
  {
    name: "internet_search",
    description: "Search the internet for current information",
    schema: z.object({
      query: z.string().describe("The search query"),
      maxResults: z.number().optional().default(5),
    }),
  }
);

Step 3: Configure Sub-agents

Python TypeScript

# Define a critic sub-agent that reviews the research output
critic_config = {
    "name": "critic",
    "model": "openai:gpt-4o",
    "system_prompt": (
        "You are a research critic. Review the report for "
        "accuracy, completeness, and clarity. Suggest specific "
        "improvements."
    ),
}

import { type SubAgent } from "deepagents";

// Define a critic sub-agent that reviews the research output
const criticConfig: SubAgent = {
  name: "critic",
  description: "Reviews reports for accuracy and completeness",
  systemPrompt:
    "You are a research critic. Review the report for " +
    "accuracy, completeness, and clarity. Suggest specific " +
    "improvements.",
};

Step 4: Create and Run the Agent

Python TypeScript

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4",
    tools=[internet_search],
    subagents=[critic_config],
    system_prompt=(
        "You are a research assistant. When given a topic:\n"
        "1. Plan your research approach\n"
        "2. Search for current information\n"
        "3. Write a comprehensive report\n"
        "4. Delegate to the critic for review\n"
        "5. Incorporate feedback and finalize"
    ),
)

result = agent.invoke({
    "messages": "Research the current state of AI agent frameworks "
                "and write a comparative analysis."
})

import { ChatAnthropic } from "@langchain/anthropic";
import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: new ChatAnthropic({
    model: "claude-sonnet-4-20250514",
    temperature: 0,
  }),
  tools: [internetSearch],
  subagents: [criticConfig],
  systemPrompt:
    "You are a research assistant. When given a topic:\n" +
    "1. Plan your research approach\n" +
    "2. Search for current information\n" +
    "3. Write a comprehensive report\n" +
    "4. Delegate to the critic for review\n" +
    "5. Incorporate feedback and finalize",
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "Research the current state of AI agent frameworks and write a comparative analysis." },
  ],
});

This example demonstrates the core Deep Agents workflow: the main agent plans, uses tools, writes files, delegates review to a sub-agent, and produces a polished output — all with built-in context management handling the details. The Python and TypeScript APIs mirror each other closely.

7 Deep Agents Code — The Terminal Coding Agent

Beyond the SDK, LangChain ships Deep Agents Code — a pre-built coding agent that runs in your terminal, similar to Claude Code or Cursor, but powered by any LLM.

# Install with one command
curl -LsSf https://langch.in/dcode | bash

Deep Agents Code gives you an interactive coding assistant with full filesystem access, shell commands, and context management — all configurable to use your preferred model provider. It's essentially a reference implementation showing what Deep Agents can build.

8 When to Use Deep Agents vs. Alternatives

Use Deep Agents when you need an autonomous agent for complex, non-deterministic, long-running tasks — research, coding, multi-step workflows, data analysis
Use LangChain's create_agent when you want a lighter harness without bundled middleware — simpler tasks, quick prototypes
Use LangGraph directly when the agent loop isn't the right shape and you need a fully custom graph — deterministic workflows, complex branching logic, approval chains
Use Claude Code / Cursor when you want a polished end-user product now — Deep Agents is for builders who want to customize and extend

The layers compose: any LangGraph graph can be a sub-agent inside Deep Agents, so you don't have to choose one or the other — you can combine them.

9 Security Model

Deep Agents follows a "trust the LLM" model. The agent can do anything its tools allow — boundaries are enforced at the tool and sandbox level, not by expecting the model to self-police.

In practice, this means:

Use sandboxed filesystem backends for untrusted workloads
Enable human-in-the-loop approval for dangerous operations
Restrict shell access to safe command sets when deploying autonomously
Pair with LangSmith for tracing and monitoring agent decisions

🎯 Key Takeaways

Agent harness, not framework — Deep Agents is opinionated and batteries-included, designed to run out of the box while remaining fully extensible
Built for long-running work — planning, context management, and persistent memory solve the problems that break traditional single-turn agents
Sub-agent orchestration — delegate tasks to isolated child agents running in parallel, each with their own context window
Model-agnostic — works with OpenAI, Anthropic, Google, open-weight models, and self-hosted LLMs via Ollama/vLLM
Python and TypeScript — first-class support in both languages with nearly identical APIs (create_deep_agent / createDeepAgent)
LangGraph foundation — built on LangGraph's streaming, persistence, and checkpointing, with native LangSmith integration
Inspired by Claude Code — LangChain identified what makes Claude Code effective and built an open, extensible version of that approach
Deep Agents Code — a terminal coding agent ships alongside the SDK, installable with a single curl command
Production-ready — tracing, evaluation, and deployment all work natively through LangSmith
Open source — MIT licensed, extensible by design, with a growing ecosystem of examples and community contributions