How langchain-ai/deep-agents-from-scratch works
Project type and purpose
• This is a Python-based tutorial library plus Jupyter notebooks for incrementally building “deep” AI agents using LangGraph.
• It’s not a web or frontend/backend full-stack app but an SDK (src/deep_agents_from_scratch) combined with five interactive notebooks that demonstrate how to assemble agent components (ReAct loop, TODO planner, file system, sub-agents) and hook them up to external APIs (Anthropic, Tavily, Langsmith).
File structure
• Top-level:
• notebooks/ – five sequential Jupyter notebooks + assets + a utils helper.
• src/deep_agents_from_scratch/ – Python package modules:
– file_tools.py (virtual FS operations)
– prompts.py (prompt templates for ReAct, tasks)
– research_tools.py (search, summarization)
– state.py (agent state container)
– task_tool.py (create_agent core, ReAct loop)
– todo_tools.py (TODO list planner)
• example.env, pyproject.toml, uv.lock – environment and dependency management.
README
• Describes progressive agent patterns: Task Planning, File System, Sub-agents, culminating in a Full Agent.
• Lists external dependencies: Python 3.11+, LangGraph via uv, APIs for Anthropic (LLM), Tavily (search), Langsmith (logging/tracing).
a. Main components
• User Interface Layer: Jupyter Notebooks (“0_create_agent” → “4_full_agent”)
• Core Agent Engine: task_tool.py (ReAct loop & create_agent API)
• Tool Modules:
• TODO Planner (todo_tools.py)
• Virtual File System (file_tools.py + state.py)
• Research Tools (research_tools.py)
• Prompt Templates: prompts.py
• State Management: state.py (holds memory, files, todo lists)
• Sub-Agent Manager: sub-agent registry & delegation within task_tool.py + research_tools.py
• External Services:
• LLM API (Anthropic)
• Web Search API (Tavily)
• Tracing/Logging (Langsmith)
b. Relationships & data flow
1. Notebook invokes create_agent(...) from task_tool.py.
2. Agent Engine initializes State, registers Tools, loads Prompt templates.
3. ReAct Loop:
– Agent constructs prompt via prompts.py → sends to LLM API → receives response → Decide: call tool or return final answer.
– Tool invocation: e.g., file_tools calls State to read/write; research_tools calls external search or summarization; todo_tools updates State.todo_list.
– Sub-agent branch: delegate a new create_agent instance with restricted tool set.
4. State persists across turns, held in-memory in state.py.
5. If LANGSMITH_TRACING enabled, every call and state transition is sent to Langsmith.
c. Architectural patterns & principles
• Modular Tool-based Agent: clear separation of core engine vs. individual tools.
• ReAct Loop Pattern: chain of thought + action calls.
• Context Offloading: virtual file system as memory to reduce token use.
• Delegation & Isolation: spawn sub-agents with limited scope.
• Progressive Composition: notebooks build incrementally on prior components.
d. Key technologies & frameworks
• Python 3.11+, LangGraph SDK (via uv package manager)
• Jupyter Notebooks for interactive demos
• Anthropic API for LLM calls
• Tavily API for external research search
• Langsmith for tracing & evaluation
Elements
• Rectangles (or containers) for each module: Task Engine, TODO, File Tools, Research Tools, State, Prompts.
• Notebooks → Agent Engine.create_agent()
• Agent Engine ↔ LLM API (prompt → response)
• Agent Engine → Tool Modules → State or External API → back to Engine
• Core engine (blue), Tools (green), State & Prompts (orange), External (purple), UI (gray).
Detailed call-out items
• Sub-agent invocation: “Engine spawns Sub-agent with restricted tool set.”
• State store as the single source of truth for memory, files, and todo lists.
• Optional tracing channel to Langsmith for telemetry.