跪拜 Guibai
← Back to the summary

LangChain Ships DeepAgents: Built-In Planning, File System, and Sub-Agents for Long-Running AI Tasks

Hey everyone, here I am again~ 👋 Another sleepless night, and while idly browsing GitHub Trending, I discovered that the LangChain team has quietly dropped a bombshell — DeepAgents! 🤯

Honestly, when running long tasks with ordinary Agent frameworks before, I always ran into all sorts of headaches: context windows blowing up, tasks forgetting their goals mid-run, sub-tasks conflicting with each other... Now someone has finally solved these pain points!

And! It not only supports Python but also TypeScript, which we frontend folks love the most! Without further ado, let me take you through what makes this framework so awesome in 2 minutes~ 🚀

🌟 Project Introduction

DeepAgents is an open-source Agent framework launched by the LangChain team, specifically designed for handling long-running, multi-step complex tasks. It's not a simple LLM + tool-calling loop, but an "Agent Harness" with built-in task planning, a file system, sub-agent spawning, and long-term memory.

Simply put: if LangChain provides the building blocks and LangGraph provides the foundation, then DeepAgents is a production-grade framework that helps you quickly build applications similar to Claude Code or Deep Research! 🏗️

🤔 Why DeepAgents?

You might ask: Can't I just use LangChain's Agent directly? Why do I need DeepAgents?

Traditional Agents run a simple loop: Think → Call Tool → Observe → Repeat. This pattern easily falls into the following "shallow traps" when handling tasks that last hours or days:

Problem Traditional Agent DeepAgents
Planning Ability One step at a time, easy to get lost ✖️ Built-in write_todos auto-decomposes tasks ✔️
Context Explosion All results pile up in conversation history ✖️ File system auto-offloads large results ✔️
Sub-task Collaboration Contexts pollute each other ✖️ Sub-agents have independent contexts, no interference ✔️
Cross-session Memory Forgets when closed ✖️ LangGraph Store persistent memory ✔️

One-sentence summary: DeepAgents moves Agents from "one step at a time" to "plan first, then execute"!

📌 Prerequisites

  1. Node.js 18+: Runtime environment (this article uses TypeScript)
  2. LLM API Key: Any one of Anthropic / OpenAI / Google, etc.
  3. Basic TypeScript Knowledge: Understanding types and functions is enough
  4. npm/pnpm/yarn: Package manager, choose any

🚀 Core Technologies

Technology Purpose Link
DeepAgents Agent Framework Main Body GitHub
LangChain Core Building Blocks langchain.com
LangGraph Runtime Engine langchain.com
Zod Tool Parameter Schema Definition zod.dev
LangSmith Observability & Evaluation smith.langchain.com

🧩 Core Code Snippets

1. Quick Start

Folks, let's first look at the most basic usage. You can get it running in just a few lines of code!

Install Dependencies:

npm install deepagents langchain @langchain/core
# If you need a search tool
npm install @langchain/tavily

Set API Key:

# Anthropic (default model claude-sonnet-4-6)
export ANTHROPIC_API_KEY="your-api-key"

# Or use OpenAI
export OPENAI_API_KEY="your-api-key"

# Or use Google
export GOOGLE_API_KEY="your-api-key"

Create Your First Deep Agent:

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import { z } from "zod";

// Define a custom tool
const getWeather = tool(
  ({ city }: { city: string }) => `${city} is sunny today!`,
  {
    name: "get_weather",
    description: "Get the weather for a specified city",
    schema: z.object({
      city: z.string().describe("City name"),
    }),
  }
);

// Create a Deep Agent
const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant",
});

// Run the Agent
const result = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather like in Beijing today?" }],
});

console.log(result.messages[result.messages.length - 1].content);

It's that simple! Define tools → Create Agent → Run, done~ ✨

2. Four Core Capabilities Explained

DeepAgents has four built-in core capabilities. This is what sets it apart from ordinary Agent frameworks:

① Task Planning — write_todos / read_todos

The Agent automatically breaks down complex tasks into a to-do list. For example, if you say "Help me write a blog system," it will break it down into: 1. Design database 2. Write backend API 3. Write frontend pages 4. Deploy online. No more worrying about forgetting the goal mid-run~

② File System — ls / read_file / write_file / edit_file

Large amounts of context are automatically saved to files, preventing context window overflow. Tool results too long? Auto-save to file! No more worrying about token explosions 💥

③ Sub-agent Spawning — task

The main Agent can "outsource" sub-tasks to specialized sub-agents. Each sub-agent has an independent context window, with no interference. Just like a project manager assigning work to different team members~

④ Long-term Memory — LangGraph Store

Cross-session persistent memory, remembering previous conversations and preferences. What you talked about today, it remembers tomorrow! 🐘

3. Custom Tool Extension

Adding your own tools is super simple. Just define the parameter Schema with Zod:

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import { z } from "zod";

// Web search tool
const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
  }: {
    query: string;
    maxResults?: number;
  }) => {
    // You can integrate Tavily, SerpAPI, etc. here
    return `Search results: Information related to ${query}... (Total ${maxResults} items)`;
  },
  {
    name: "internet_search",
    description: "Run a web search to get the latest information",
    schema: z.object({
      query: z.string().describe("Search keyword"),
      maxResults: z.number().optional().default(5).describe("Maximum number of results to return"),
    }),
  }
);

// Email sending tool
const sendEmail = tool(
  ({ to, subject, body }: { to: string; subject: string; body: string }) =>
    `Email sent to ${to}`,
  {
    name: "send_email",
    description: "Send an email to a specified recipient",
    schema: z.object({
      to: z.string().describe("Recipient email"),
      subject: z.string().describe("Email subject"),
      body: z.string().describe("Email body"),
    }),
  }
);

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [internetSearch, sendEmail],
  systemPrompt: `You are a research assistant.
For data analysis tasks, run exploratory analysis first before modeling.
If tool calls exceed 100 times, please stop and report progress.`,
});

Tip: You can add some business rules in systemPrompt, like "Run exploratory analysis before modeling for data analysis" or "Stop if tool calls exceed 100 times", so the Agent doesn't run wild~ 💡

4. Subagent System

This feature is really super practical! The main Agent can "outsource" complex sub-tasks to specialized sub-agents. Each sub-agent has its own context and tools, with no interference:

import {
  createDeepAgent,
  type SubAgent,
  type CompiledSubAgent,
} from "deepagents";
import { tool } from "langchain";
import { z } from "zod";

// Define a fact-checking tool
const verifyClaim = tool(
  ({ claim }: { claim: string }) => `Verified: "${claim}" - Status: Confirmed`,
  {
    name: "verify_claim",
    description: "Verify factual claims",
    schema: z.object({ claim: z.string() }),
  }
);

// Method 1: Declarative Sub-agent (dynamically created at runtime)
const factChecker: SubAgent = {
  name: "fact-checker",
  description: "Verify factual claims and statements",
  systemPrompt: "You are a fact-checking expert, please verify claims thoroughly.",
  tools: [verifyClaim],
};

// Method 2: Pre-compiled Sub-agent (reuse an existing Agent instance)
const researchAgent = createDeepAgent({
  systemPrompt: "You are a research expert.",
  tools: [verifyClaim],
  subagents: [factChecker],
});

const compiledResearcher: CompiledSubAgent = {
  name: "research-specialist",
  description: "A research expert with fact-checking capabilities",
  runnable: researchAgent,
};

// Main orchestration Agent
const mainAgent = createDeepAgent({
  systemPrompt: "You are responsible for coordinating research and fact-checking tasks.",
  subagents: [factChecker, compiledResearcher],
});

// The Agent automatically gets a "task" tool for delegating tasks
const result = await mainAgent.invoke({
  messages: [
    { role: "user", content: "Research quantum computing and verify key claims" },
  ],
});

Differences between the two sub-agent types:

Just like a project manager assigning work to different team members, each member has their own toolbox and working memory, with no interference! 🧑‍💼

5. Backend System

DeepAgents version 0.2 introduces pluggable backends, allowing you to freely choose the storage method for the file system:

import {
  createDeepAgent,
  FilesystemBackend,
} from "deepagents";

// ① Default: StateBackend (temporary storage, valid for a single session)
const agent1 = createDeepAgent({
  // No backend specified, defaults to StateBackend
  // Suitable as a temporary scratchpad
});

// ② Local filesystem backend
const agent2 = createDeepAgent({
  backend: new FilesystemBackend({
    rootDir: "/workspace",
    virtualMode: true, // Sandbox mode, restricted within rootDir
  }),
  // Suitable for local development, CI environments
});

Backend Selection Guide:

Backend Characteristics Use Cases
StateBackend Temporary storage, single session Temporary scratchpad, intermediate result staging
FilesystemBackend Real filesystem read/write Local development, CI sandbox environments
StoreBackend LangGraph Store cross-thread persistence Cross-session memory, multi-user scenarios
CompositeBackend Hybrid backend, different storage for different paths Production environments, complex requirements

6. Skills System

DeepAgents also has a super cool feature — the Skills System! You can define skills using SKILL.md files, and the Agent loads them on demand:

import { createDeepAgent, FilesystemBackend } from "deepagents";
import fs from "node:fs";

// Create skills directory and files
const skillsDir = "/project/skills";
fs.mkdirSync(`${skillsDir}/web-research`, { recursive: true });
fs.writeFileSync(
  `${skillsDir}/web-research/SKILL.md`,
  `---
name: web-research
description: A structured methodology for web research
---

# Web Research Skill

## When to Use
- User requests research on a topic
- Need to comprehensively gather information

## Workflow
1. Clarify research scope and requirements
2. Use search tools to collect information
3. Analyze and extract key information
4. Synthesize findings into a summary
5. Cite all sources
`
);

// Create an Agent with skills
const backend = new FilesystemBackend({
  rootDir: "/project",
  virtualMode: true,
});

const agent = createDeepAgent({
  systemPrompt: "You are a research assistant.",
  backend: backend,
  skills: ["/skills/"], // Skills source directory
});

The benefit of the skills system is progressive disclosure — the Agent doesn't load all skills at once, but reads them on demand based on task needs, saving context space! 🎯

7. Long-term Memory

Let the Agent remember your preferences and context across sessions:

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  memory: ["~/.deepagents/AGENTS.md"], // Memory file path
  skills: ["/skills/"],
});

Format of the memory file AGENTS.md:

# Agent Memory

## User Preferences
- Prefers TypeScript over Python
- Prefers functional programming style
- Writing style: Conversational, relaxed

## Project Context
- Current project: Juejin blog auto-publishing system
- Tech stack: LangChain + DeepAgents + TypeScript

Preferences you tell the Agent today, it remembers tomorrow! 🐘

8. Streaming

For long tasks, streaming output prevents users from waiting idly:

import { createDeepAgent } from "deepagents";
import { HumanMessage } from "@langchain/core/messages";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [internetSearch],
});

// Streaming output
const stream = await agent.stream({
  messages: [new HumanMessage("Help me research the 2026 AI Agent market landscape")],
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

No more staring at a blank screen for long tasks~ ⚡

🛠️ Run Guide

Local Installation

# 1. Install DeepAgents
npm install deepagents langchain @langchain/core

# 2. Install the corresponding model provider (choose one)
npm install @langchain/anthropic    # Anthropic (default recommendation)
npm install @langchain/openai       # OpenAI
npm install @langchain/google-genai # Google

# 3. Set API Key
export ANTHROPIC_API_KEY="your-key-here"

# 4. Run!
npx tsx your-agent.ts

Deep Agents CLI

Oh right, DeepAgents also comes with a terminal coding Agent, just like Claude Code, usable directly in the terminal:

npm install -g deepagents
deepagents

Supports code writing, file operations, task planning. Terminal enthusiasts rejoice! ⌨️

🔧 Customization Options

Item Modification Method Effect Preview
Model Selection model: "openai:gpt-5.4" 🧠 GPT-5.4 → 🟣 Claude Sonnet
Custom Tools tools: [myTool] 🔧 Basic Tools → 🎯 Industry-specific Tools
System Prompt systemPrompt: "..." 📝 General Assistant → 🏥 Medical/Legal Expert
Sub-agents subagents: [researcher] 🧑‍💼 Solo Operation → 👥 Team Collaboration
Backend Storage backend: new FilesystemBackend(...) 💾 Temporary Storage → 🗄️ Persistent Storage
Skills System skills: ["/skills/"] 📖 One-time Load → 🎯 On-demand Load
Long-term Memory memory: ["~/.deepagents/AGENTS.md"] 🐟 Goldfish Memory → 🐘 Cross-session Memory

🏗️ Architecture Comparison

Folks often ask: What exactly is the relationship between DeepAgents, LangChain, and LangGraph?

Dimension LangGraph LangChain DeepAgents
Positioning Agent Runtime Agent Framework Agent Toolkit
Characteristics Deterministic steps + Intelligent components Core loop + Middleware Built-in planning/files/sub-agents
Suitable For Production systems, fine-grained control Rapid development, standard patterns Complex long tasks, autonomous execution
Analogy Foundation Building Blocks Finished Framework

The three are progressive: LangGraph → LangChain → DeepAgents, with upper layers built on lower ones. Which one to choose depends on your requirement complexity~ 🧱

🐛 Troubleshooting

  1. Context window insufficient?

    • DeepAgents automatically saves large results to the file system, no need to worry
    • Use sub-agents to split tasks, each sub-agent has independent context
    • Limit the number of tool calls in systemPrompt

  2. Agent stuck in an infinite loop?

    • Add stop rules in systemPrompt, like "Stop if tool calls exceed 100 times"
    • Use LangSmith to monitor the Agent's execution steps to see exactly where it's stuck
    • DeepAgents has planning capabilities, less prone to going in circles than ordinary frameworks

  3. How do sub-agents communicate?

    • Share intermediate results through the file system
    • The main agent is responsible for coordination and summarization, just like a project manager
    • Each sub-agent's output is returned to the main agent

  4. Should I choose Python or TypeScript?

    • The two versions have basically the same functionality, with slightly different API styles
    • Python: create_deep_agent (snake_case naming)
    • TypeScript: createDeepAgent (camelCase naming)
    • Choose TS for frontend projects, Python for data science projects, both work!

📚 Extended Resources

Conclusion

Snipaste_2025-10-10_00-29-10.png