Using AI for long-horizon complex tasks, the model tends to “forget” things as the context grows longer, and output quality drops sharply. The LangChain official team has open-sourced a tutorial: Deep Agents from Scratch, which breaks down the core design patterns of mainstream agents from the ground up with thorough explanations. The tutorial summarizes the solutions used by agents like Manus and Claude Code: task planning, context offloading to the file system, and context isolation via sub-agents.
GitHub: http://github.com/langchain-ai/deep-agents-from-scratch

It consists of 5 progressive notebooks, starting from the most basic ReAct loop, gradually adding TODO task management, a virtual file system, sub-agent delegation, and finally integrating into a complete deep research agent. Each step is runnable and shows tangible results — it’s not pure theory. The final agent can perform real web searches and multi-step analysis tasks. If you want to understand how current mainstream agents are actually designed, or if you are planning to build one yourself, this tutorial is well worth following through.

langchain-ai/deep-agents-from-scratch

Source: https://github.com/langchain-ai/deep-agents-from-scratch

🧱 Deep Agents from Scratch

Deep Research (https://academy.langchain.com/courses/deep-research-with-langgraph) broke out as one of the first major agent use-cases along with coding. Now, we’ve seeing an emergence of general purpose agents that can be used for a wide range of tasks. For example, Manus (https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) has gained significant attention and popularity for long-horizon tasks; the average Manus task uses ~50 tool calls!. As a second example, Claude Code is being used generally for tasks beyond coding.

Careful review of the context engineering patterns (https://docs.google.com/presentation/d/16aaXLu40GugY-kOpqDU4e-S0hD1FmHcNyF0rRRnb1OU/edit?slide=id.p#slide=id.p) across these popular “deep” agents shows some common approaches:

• Task planning (e.g., TODO), often with recitation
• Context offloading to file systems
• Context isolation through sub-agent delegation

This course will show how to implement these patterns from scratch using LangGraph!

🚀 Quickstart

Prerequisites

• Ensure you’re using Python 3.11 or later.
• This version is required for optimal compatibility with LangGraph.

python3 --version

• uv (https://docs.astral.sh/uv/) package manager

curl -LsSf https://astral.sh/uv/install.sh | sh
# Update PATH to use the new uv version
export PATH="/Users/$USER/.local/bin:$PATH"

Installation

1. Clone the repository:

git clone https://github.com/langchain-ai/deep-agents-from-scratch.git
cd deep-agents-from-scratch

2. Install the package and dependencies (this automatically creates and manages the virtual environment):

uv sync

3. Create a .env file in the project root with your API keys:

# Create .env file
touch .env

Add your API keys to the .env file:

# Required for research agents with external search
TAVILY_API_KEY=your_tavily_api_key_here

# Required for model usage
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Optional: For evaluation and tracing
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=deep-agents-from-scratch

4. Run notebooks or code using uv:

# Run Jupyter notebooks directly
uv run jupyter notebook

# Or activate the virtual environment if preferred
source .venv/bin/activate
# On Windows: .venv\Scripts\activate
jupyter notebook

📚 Tutorial Overview

This repository contains five progressive notebooks that teach you to build advanced AI agents:

0_create_agent.ipynb

• Learn how to use the create_agent component. This component
  • implements a ReAct (Reason - Act) loop that forms the foundation for many agents.
  • is easy to use and quick to set up.
  • serves as the basis for the following lessons.

1_todo.ipynb

• Task Planning Foundations Learn to implement structured task planning using TODO lists. This notebook introduces:
• Task tracking with status management (pending/in_progress/completed)
• Progress monitoring and context management
• The write_todos() tool for organizing complex multi-step workflows
• Best practices for maintaining focus and preventing task drift

2_files.ipynb

• Virtual File Systems Implement a virtual file system stored in agent state for context offloading:
• File operations: ls(), read_file(), write_file(), edit_file()
• Context management through information persistence
• Enabling agent “memory” across conversation turns
• Reducing token usage by storing detailed information in files

3_subagents.ipynb

• Context Isolation Master sub-agent delegation for handling complex workflows:
• Creating specialized sub-agents with focused tool sets
• Context isolation to prevent confusion and task interference
• The task() delegation tool and agent registry patterns
• Parallel execution capabilities for independent research streams

4_full_agent.ipynb

• Complete Research Agent Combine all techniques into a production-ready research agent:
• Integration of TODOs, files, and sub-agents
• Real web search with intelligent context offloading
• Content summarization and strategic thinking tools
• Complete workflow for complex research tasks with LangGraph Studio integration

Each notebook builds on the previous concepts, culminating in a sophisticated agent architecture capable of handling real-world research and analysis tasks.