🧱 Deep Agents from Scratch

Deep Research 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 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 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 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
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

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.