LangChain Deep Agents — The Batteries-Included Agent Harness, Explained
Deep Agents is LangChain's new open-source agent harness built on top of LangGraph that bundles everything you need for production-grade AI agents — filesystem access, sub-agent delegation, context management, memory, and planning — into a single, opinionated framework. Think of LangGraph as the engine, Deep Agents as the fully loaded vehicle. This article breaks down the architecture, capabilities, and practical usage of this batteries-included agent system.
What Are Deep Agents?
Deep Agents is an open-source agent harness built on LangGraph, LangChain's framework for stateful, multi-step AI workflows. While LangGraph gives you the engine — the low-level graph execution runtime — Deep Agents provides the fully assembled vehicle, pre-wired with tools, memory, planning, and delegation out of the box.
The analogy breaks down into three layers:
- LangGraph = Engine: The raw execution framework. Graph nodes, edges, state management, checkpointing. Powerful but requires assembly.
- Deep Agents = Car: A pre-built agent architecture on top of LangGraph with sensible defaults, built-in tools, and opinionated structure.
- Deep Agents + Your Config = Loaded Vehicle: When you bring your own API keys, tool configurations, and domain-specific instructions, you get a production-ready agent system.
"LangGraph is the engine. Deep Agents is the car that comes with the engine already installed, the seats bolted in, and the GPS wired up. You just need to turn the key."
Why Deep Agents Exists
Building agents from scratch — even with LangGraph — involves solving the same problems repeatedly. Deep Agents was created to address four recurring pain points that every agent developer encounters:
- Context overflow: Long-running agents blow past context windows. Without automatic management, agents either crash or silently lose critical information mid-task.
- No persistent state: Vanilla LLM calls are stateless. Between turns, agents forget what they've done, what files they've read, and what decisions they've made. Deep Agents solves this with built-in memory and checkpointing.
- No delegation: Complex tasks require multiple agents working in parallel or sequentially. Building a sub-agent orchestration layer from scratch is tedious and error-prone.
- No planning: Without explicit planning capabilities, agents wander aimlessly — taking actions without a coherent strategy, often repeating work or going in circles.
The project draws heavy inspiration from Claude Code and similar terminal-based coding agents, aiming to provide an open-source alternative that works with any model provider and can be extended or customized for domain-specific use cases.
"Every team building agents on LangGraph was solving context management, state persistence, delegation, and planning from scratch. Deep Agents packages those solutions so you can focus on your actual use case."
Core Architecture
Deep Agents is structured as a monorepo with two primary libraries, both targeting the same design philosophy but implemented natively for their respective ecosystems:
- libs/deepagents: The core agent harness library. Provides the agent loop, tool integration, memory, context management, and planning primitives.
- libs/code: A specialized coding agent built on top of the core library (Deep Agents Code). Adds terminal access, file operations, and code-specific workflows.
Both Python and TypeScript implementations exist as first-class citizens. The Python version targets data science, ML pipelines, and backend automation. The TypeScript version targets web development, full-stack applications, and Node.js toolchains.
The architecture follows a layered design: LangGraph provides the execution graph, Deep Agents adds the agent loop and built-in capabilities, and your application-specific configuration sits on top. Each layer can be swapped or extended independently.
"It's a monorepo with two packages: the core agent harness and the coding agent. Python and TypeScript aren't ports of each other — they're native implementations sharing the same design."
Built-in Capabilities
Deep Agents ships with five major capability categories that work together to create a cohesive agent experience:
- Filesystem access: Read, write, search, and navigate files. Agents can explore codebases, edit configurations, and produce artifacts. Sandboxed by default with configurable permissions.
- Sub-agent delegation: Spawn child agents for subtasks. The parent agent can delegate research, code generation, or analysis to specialized sub-agents that run in parallel and report back results.
- Context management: Automatic context window tracking and compression. When context grows too large, the system summarizes older messages while preserving critical information. No more silent context truncation.
- Memory: Persistent memory across sessions. Agents remember past interactions, learned preferences, and discovered facts. Backed by LangGraph's checkpointing system with optional external storage.
- Planning: Explicit plan-then-execute workflow. Before taking actions, agents create structured plans with steps, dependencies, and success criteria. Plans are visible, editable, and can be resumed if interrupted.
"Each capability was built because teams kept reimplementing it. Filesystem, delegation, context management, memory, planning — these are table stakes for production agents."
Model Compatibility
Deep Agents is model-agnostic by design. Any language model that supports tool calling (function calling) can serve as the agent's brain. This includes both cloud APIs and locally-hosted models:
- OpenAI: GPT-4o, GPT-4.1, o3, and future models via the OpenAI API.
- Anthropic: Claude Sonnet 4, Claude Opus 4 via the Anthropic API.
- Ollama: Any locally-running model with tool-calling support (Llama, Qwen, Mistral).
- vLLM: Self-hosted models at scale with OpenAI-compatible endpoints.
- Any OpenAI-compatible API: Together AI, Fireworks, Groq, and other providers that expose the standard chat completions interface.
The model layer is abstracted through LangChain's chat model interface, so switching providers is a one-line configuration change. This means you can prototype with a cloud API and deploy with a self-hosted model — or vice versa — without changing any agent logic.
Deep Agents Code
Deep Agents Code is a terminal-based coding agent built on the core Deep Agents library — think of it as LangChain's open-source answer to Claude Code. It lives in libs/code within the monorepo and adds coding-specific capabilities on top of the general-purpose agent harness.
Key features that differentiate it from the base library:
- Terminal execution: Run shell commands, install packages, execute scripts, and interact with the development environment directly.
- Code-aware editing: Understands file types, syntax highlighting, and language-specific conventions. Can apply targeted patches rather than rewriting entire files.
- Git integration: Stage, commit, diff, and manage branches as part of the coding workflow.
- Project understanding: Scans project structure, reads configuration files, and builds a mental model of the codebase before making changes.
- Iterative development: Run tests, observe failures, fix issues, and re-run in a tight loop until the task is complete.
Because it's open source, you can customize the system prompt, add domain-specific tools, restrict dangerous operations, or integrate it into your own CI/CD pipeline — things that proprietary coding agents don't allow.
"Deep Agents Code is Claude Code but open source, model-agnostic, and extensible. You own the agent, you control the tools, you pick the model."
Practical Example
Getting started with Deep Agents in Python is straightforward. Install the package, configure your model, and run:
from deepagents import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
agent = Agent(llm=llm)
# Run with a task
result = agent.run("Analyze the project structure and suggest improvements")
The TypeScript version follows a similar pattern:
import { Agent } from "@langchain/deepagents";
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({ model: "gpt-4o" });
const agent = new Agent({ llm });
// Run with a task
const result = await agent.run("Analyze the project structure and suggest improvements");
Both examples spin up a full agent with filesystem access, context management, and planning enabled by default. Sub-agent delegation and memory can be configured via options. The agent automatically creates a plan, executes each step, and returns structured results.
Comparison & When to Use
Deep Agents occupies a specific niche in the agent ecosystem. Understanding when to use it — and when not to — depends on what you're comparing it against:
Deep Agents vs. Claude Code:
- Claude Code is proprietary, locked to Anthropic models, and works as a standalone tool. Deep Agents Code is open source, model-agnostic, and designed to be embedded in your own applications.
- Claude Code has a more polished UX and deeper integration with Claude's capabilities. Deep Agents trades polish for flexibility and control.
- Choose Claude Code for quick, interactive coding sessions. Choose Deep Agents Code when you need to customize the agent, use a different model, or integrate into CI/CD.
Deep Agents vs. Raw LangGraph:
- Raw LangGraph gives you maximum control and zero opinions. Deep Agents gives you a working agent in minutes with sensible defaults.
- If your use case doesn't fit Deep Agents' opinionated structure, drop down to raw LangGraph. If you want filesystem, memory, planning, and delegation without building them yourself, use Deep Agents.
- They're complementary, not competing. Deep Agents is built on LangGraph — you can always access the underlying graph when you need to.
"Use raw LangGraph when you need full control. Use Deep Agents when you need a working agent yesterday. Use Deep Agents Code when you want an open-source Claude Code you can actually customize."