AI真好玩系列-2分钟快速了解DeepAgents | Quick Guide to DeepAgents in 2 Minutes

宝宝们又来看我啦~👋 又是一个睡不着觉的夜晚，闲来无事刷了一下GitHub Trending，发现LangChain团队悄悄放出了一个大招——DeepAgents！🤯

说实话，之前用普通的Agent框架跑长任务的时候，总是遇到各种头疼的问题：上下文爆了、任务跑着跑着忘了目标、子任务之间互相打架……现在终于有人把这些痛点给解决了！

而且！它不仅支持 Python，还支持咱们前端人最爱的 TypeScript！废话不多说，2分钟带你快速了解这个框架到底牛在哪里~ 🚀

🌟 项目简介 | Project Introduction

DeepAgents 是 LangChain 团队推出的开源 Agent 框架，专门为处理长时程、多步骤的复杂任务而生。它不是一个简单的 LLM + 工具调用循环，而是一个内置了任务规划、文件系统、子代理生成和长期记忆的"Agent 装备套件"（Agent Harness）。

简单来说：如果说 LangChain 提供了积木，LangGraph 提供了地基，那么 DeepAgents 就是一套成品级的框架，帮你快速构建类似 Claude Code 或 Deep Research 的应用！🏗️

• GitHub项目：github.com/langchain-a…
• 官方文档（Python）：docs.langchain.com/oss/python/…
• 官方文档（JS/TS）：docs.langchain.com/oss/javascr…
• 论文：arxiv.org/pdf/2510.21…

🤔 为什么需要 DeepAgents？ | Why DeepAgents?

宝宝们可能会问：我直接用 LangChain 的 Agent 不就行了？为啥还需要 DeepAgents？

传统的 Agent 运行一个简单的循环：思考 → 调用工具 → 观察 → 重复。这种模式在处理多小时或多天的任务时，容易遇到以下"浅层陷阱"：

问题	传统 Agent	DeepAgents
规划能力	走一步看一步，容易迷路 ✖️	内置 write_todos 自动拆解任务 ✔️
上下文爆炸	所有结果堆在对话历史里 ✖️	文件系统自动卸载大结果 ✔️
子任务协作	上下文互相污染 ✖️	子代理独立上下文，互不干扰 ✔️
跨会话记忆	关了就忘了 ✖️	LangGraph Store 持久化记忆 ✔️

一句话总结：DeepAgents 让 Agent 从"走一步看一步"变成"先规划再执行"！

📌 前提条件 | Prerequisites

1. Node.js 18+：运行环境（本文使用 TypeScript）
2. LLM API Key：Anthropic / OpenAI / Google 等任意一家
3. 基础 TypeScript 知识：了解类型和函数即可
4. npm/pnpm/yarn：包管理器，任选其一

🚀 核心技术栈 | Core Technologies

技术	用途	链接
DeepAgents	Agent 框架主体	GitHub
LangChain	核心构建模块	langchain.com
LangGraph	运行时引擎	langchain.com
Zod	工具参数 Schema 定义	zod.dev
LangSmith	可观测性 & 评估	smith.langchain.com

🧩 核心代码片段 | Core Code Snippets

1. 快速上手 | Quick Start

宝宝们，先来看看最基础的用法，几行代码就能跑起来！

安装依赖：

npm install deepagents langchain @langchain/core
# 如果你需要搜索工具
npm install @langchain/tavily

设置 API Key：

# Anthropic（默认模型 claude-sonnet-4-6）
export ANTHROPIC_API_KEY="your-api-key"

# 或者用 OpenAI
export OPENAI_API_KEY="your-api-key"

# 或者用 Google
export GOOGLE_API_KEY="your-api-key"

创建你的第一个 Deep Agent：

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

// 定义一个自定义工具
const getWeather = tool(
  ({ city }: { city: string }) => `${city}今天阳光明媚！`,
  {
    name: "get_weather",
    description: "获取指定城市的天气",
    schema: z.object({
      city: z.string().describe("城市名称"),
    }),
  }
);

// 创建 Deep Agent
const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [getWeather],
  systemPrompt: "你是一个有用的助手",
});

// 运行 Agent
const result = await agent.invoke({
  messages: [{ role: "user", content: "北京今天天气怎么样？" }],
});

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

就这么简单！定义工具 → 创建 Agent → 运行，完事儿~ ✨

2. 四大核心能力详解 | Four Core Capabilities

DeepAgents 内置了四大核心能力，这才是它跟普通 Agent 框架拉开差距的地方：

① 任务规划 — write_todos / read_todos

Agent 会自动把复杂任务拆解成待办清单。比如你说"帮我写一个博客系统"，它会拆成：1.设计数据库 2.写后端API 3.写前端页面 4.部署上线。再也不怕跑着跑着忘了目标了~

② 文件系统 — ls / read_file / write_file / edit_file

大量上下文自动保存到文件，防止上下文窗口溢出。工具返回结果太长？自动存文件！再也不用担心 token 爆炸了 💥

③ 子代理生成 — task

主 Agent 可以"外包"子任务给专门的子 Agent，每个子 Agent 有独立的上下文窗口，互不干扰。就像项目经理把活分给不同组员一样~

④ 长期记忆 — LangGraph Store

跨会话持久化记忆，记住之前的对话和偏好。今天聊的内容，明天还能记住！🐘

3. 自定义工具扩展 | Custom Tool Extension

添加你自己的工具超级简单，用 Zod 定义参数 Schema 就行：

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

// 网络搜索工具
const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
  }: {
    query: string;
    maxResults?: number;
  }) => {
    // 这里可以接入 Tavily、SerpAPI 等搜索服务
    return `搜索结果：${query}的相关信息...（共${maxResults}条）`;
  },
  {
    name: "internet_search",
    description: "运行网络搜索，获取最新信息",
    schema: z.object({
      query: z.string().describe("搜索关键词"),
      maxResults: z.number().optional().default(5).describe("最大返回结果数"),
    }),
  }
);

// 邮件发送工具
const sendEmail = tool(
  ({ to, subject, body }: { to: string; subject: string; body: string }) =>
    `邮件已发送至 ${to}`,
  {
    name: "send_email",
    description: "发送邮件给指定收件人",
    schema: z.object({
      to: z.string().describe("收件人邮箱"),
      subject: z.string().describe("邮件主题"),
      body: z.string().describe("邮件正文"),
    }),
  }
);

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [internetSearch, sendEmail],
  systemPrompt: `你是一个研究助手。
对于数据分析任务，先运行探索性分析再建模。
如果工具调用超过100次，请停止并汇报进度。`,
});

小贴士：systemPrompt 里可以加一些业务规则，比如"数据分析先探索再建模"、"工具调用超过100次就停"，这样 Agent 就不会瞎跑了~ 💡

4. 子代理系统 | Subagent System

这个功能真的超级实用！主 Agent 可以把复杂子任务"外包"给专门的子 Agent，每个子 Agent 有自己的上下文和工具，互不干扰：

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

// 定义事实核查工具
const verifyClaim = tool(
  ({ claim }: { claim: string }) => `已验证："${claim}" - 状态：确认`,
  {
    name: "verify_claim",
    description: "验证事实性声明",
    schema: z.object({ claim: z.string() }),
  }
);

// 方式1：声明式子代理（运行时动态创建）
const factChecker: SubAgent = {
  name: "fact-checker",
  description: "验证事实性声明和陈述",
  systemPrompt: "你是一个事实核查专家，请彻底验证声明。",
  tools: [verifyClaim],
};

// 方式2：预编译子代理（复用已有的 Agent 实例）
const researchAgent = createDeepAgent({
  systemPrompt: "你是一个研究专家。",
  tools: [verifyClaim],
  subagents: [factChecker],
});

const compiledResearcher: CompiledSubAgent = {
  name: "research-specialist",
  description: "具有事实核查能力的研究专家",
  runnable: researchAgent,
};

// 主编排 Agent
const mainAgent = createDeepAgent({
  systemPrompt: "你负责协调研究和事实核查任务。",
  subagents: [factChecker, compiledResearcher],
});

// Agent 会自动获得 "task" 工具用于委派任务
const result = await mainAgent.invoke({
  messages: [
    { role: "user", content: "调研量子计算并验证关键声明" },
  ],
});

两种子代理的区别：

• SubAgent：声明式定义，运行时动态创建，轻量灵活
• CompiledSubAgent：预编译的 Agent 实例，可以复用已有配置，适合复杂场景

就像项目经理把活分给不同组员，每个组员有自己的工具箱和工作记忆，互不干扰！🧑‍💼

5. 后端系统 | Backend System

DeepAgents 0.2 版本引入了可插拔后端，你可以自由选择文件系统的存储方式：

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

// ① 默认：StateBackend（临时存储，单次会话有效）
const agent1 = createDeepAgent({
  // 不指定 backend，默认使用 StateBackend
  // 适合作为临时草稿本
});

// ② 本地文件系统后端
const agent2 = createDeepAgent({
  backend: new FilesystemBackend({
    rootDir: "/workspace",
    virtualMode: true, // 沙箱模式，限制在 rootDir 内
  }),
  // 适合本地开发、CI 环境
});

后端选择指南：

后端	特点	适用场景
StateBackend	临时存储，单次会话	临时草稿本、中间结果暂存
FilesystemBackend	真实文件系统读写	本地开发、CI 沙箱环境
StoreBackend	LangGraph Store 跨线程持久化	跨会话记忆、多用户场景
CompositeBackend	混合后端，不同路径用不同存储	生产环境、复杂需求

6. 技能系统 | Skills System

DeepAgents 还有一个超酷的功能——技能系统！你可以用 SKILL.md 文件定义技能，Agent 会按需加载：

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

// 创建技能目录和文件
const skillsDir = "/project/skills";
fs.mkdirSync(`${skillsDir}/web-research`, { recursive: true });
fs.writeFileSync(
  `${skillsDir}/web-research/SKILL.md`,
  `---
name: web-research
description: 结构化的网络研究方法论
---

# Web Research Skill

## When to Use
- 用户要求研究某个主题
- 需要全面收集信息

## Workflow
1. 明确研究范围和需求
2. 使用搜索工具收集信息
3. 分析并提取关键信息
4. 综合发现形成摘要
5. 引用所有来源
`
);

// 创建带技能的 Agent
const backend = new FilesystemBackend({
  rootDir: "/project",
  virtualMode: true,
});

const agent = createDeepAgent({
  systemPrompt: "你是一个研究助手。",
  backend: backend,
  skills: ["/skills/"], // 技能源目录
});

技能系统的好处是渐进式披露——Agent 不会一次性加载所有技能，而是根据任务需要按需读取，节省上下文空间！🎯

7. 长期记忆 | Long-term Memory

让 Agent 跨会话记住你的偏好和上下文：

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  memory: ["~/.deepagents/AGENTS.md"], // 记忆文件路径
  skills: ["/skills/"],
});

记忆文件 AGENTS.md 的格式：

# Agent Memory

## User Preferences
- 喜欢用 TypeScript 而不是 Python
- 偏好函数式编程风格
- 文章风格：口语化、轻松

## Project Context
- 当前项目：掘金博客自动发布系统
- 技术栈：LangChain + DeepAgents + TypeScript

今天告诉 Agent 的偏好，明天它还记得！🐘

8. 流式输出 | Streaming

对于长任务，流式输出让用户不用干等：

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

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

// 流式输出
const stream = await agent.stream({
  messages: [new HumanMessage("帮我调研2026年AI Agent市场格局")],
});

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

长任务再也不用盯着空白屏幕发呆了~ ⚡

🛠️ 使用指南 | Run Guide

本地安装 | Local Installation

# 1. 安装 DeepAgents
npm install deepagents langchain @langchain/core

# 2. 安装对应的模型提供商（选一个就行）
npm install @langchain/anthropic    # Anthropic（默认推荐）
npm install @langchain/openai       # OpenAI
npm install @langchain/google-genai # Google

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

# 4. 开跑！
npx tsx your-agent.ts

Deep Agents CLI | 命令行工具

对了，DeepAgents 还自带了一个终端编码 Agent，就像 Claude Code 一样，在终端里直接用：

npm install -g deepagents
deepagents

支持代码编写、文件操作、任务规划，终端党狂喜！⌨️

🔧 定制项 | Customization Options

项目	修改方法	效果预览
模型选择	model: "openai:gpt-5.4"	🧠 GPT-5.4 → 🟣 Claude Sonnet
自定义工具	tools: [myTool]	🔧 基础工具 → 🎯 行业专用工具
系统提示词	systemPrompt: "..."	📝 通用助手 → 🏥 医疗/法律专家
子代理	subagents: [researcher]	🧑‍💼 单兵作战 → 👥 团队协作
后端存储	backend: new FilesystemBackend(...)	💾 临时存储 → 🗄️ 持久化存储
技能系统	skills: ["/skills/"]	📖 一次性加载 → 🎯 按需加载
长期记忆	memory: ["~/.deepagents/AGENTS.md"]	🐟 金鱼记忆 → 🐘 跨会话记忆

🏗️ 架构对比 | Architecture Comparison

宝宝们经常问：DeepAgents 和 LangChain、LangGraph 到底啥关系？

维度	LangGraph	LangChain	DeepAgents
定位	Agent 运行时	Agent 框架	Agent 工具包
特点	确定性步骤 + 智能组件	核心循环 + 中间件	内置规划/文件/子代理
适合	生产系统、精细控制	快速开发、标准模式	复杂长任务、自主执行
类比	地基	积木	成品框架

三者是递进关系：LangGraph → LangChain → DeepAgents，上层基于下层构建。选哪个取决于你的需求复杂度~ 🧱

🐛 常见问题 | Troubleshooting

1. 上下文窗口不够用？

   • DeepAgents 会自动将大结果保存到文件系统，不用你操心
   • 用子代理拆分任务，每个子代理有独立上下文
   • 在 systemPrompt 里限制工具调用次数就行

2. Agent 陷入死循环？

   • 在 systemPrompt 里加停止规则，比如"超过100次工具调用就停"
   • 用 LangSmith 监控 Agent 的执行步骤，看看到底卡在哪了
   • DeepAgents 有规划能力，比普通框架不容易绕圈圈

3. 子代理之间怎么通信？

   • 通过文件系统共享中间结果
   • 主代理负责协调和汇总，就像项目经理一样
   • 每个子代理的输出会返回给主代理

4. 该选 Python 还是 TypeScript？

   • 两个版本功能基本一致，API 风格略有不同
   • Python：create_deep_agent（下划线命名）
   • TypeScript：createDeepAgent（驼峰命名）
   • 前端项目选 TS，数据科学项目选 Python，都行！

📚 扩展学习资源 | Extended Resources

• DeepAgents 官方文档（Python）
• DeepAgents 官方文档（JS/TS）
• DeepAgents Quickstart
• LangChain 官方文档
• LangGraph 工作流引擎
• DeepAgents 论文
• GitHub 仓库

Conclusion | 结语

• That's all for today~ - | 今天就写到这里啦~

• Guys, (￣ω￣(￣ω￣〃 (￣ω￣〃)ゝ See you tomorrow~~ | 小伙伴们，(￣ω￣(￣ω￣〃 (￣ω￣〃)ゝ我们明天再见啦~~

• Everyone, be happy every day! 大家要天天开心哦

• Welcome everyone to point out any mistakes in the article~ | 欢迎大家指出文章需要改正之处~

• Learning has no end; win-win cooperation | 学无止境，合作共赢

• Welcome all the passers-by, boys and girls, to offer better suggestions! ~~~ | 欢迎路过的小哥哥小姐姐们提出更好的意见哇~~