创建日期：2026-09-17 ｜ 最近更新：2026-09-17 基于 deepagents@1.13.4（LangChain 官方，npm 描述：a library for building controllable AI agents with LangGraph）在本机真实运行：模型走 Anthropic 兼容端点（DeepSeek），文件系统后端落真实磁盘。文中时间线、工具参数、最终回答、产物内容都是实测结果。

Deep Agents 入门：LangChain 把「能干活的 Agent」做成了中间件

一句话：deepagents 是 LangChain 出的「可控 Agent」库——它把你手写过的那些零件（文件读写、子任务、上下文摘要、记忆、技能、工具调用护栏）预先做成了可插拔的中间件，让你几行代码就得到一个「会规划、会读写文件、会派活、长任务不忘事」的 Agent。

它不神秘：底层仍然是 LangGraph，上面套了一层「开箱即用的中间件组合」。

1. 它到底打包了什么

从本机 import * as d from 'deepagents' 的真实导出看，它把能力拆成了几组：

组	代表导出	作用
入口	`createDeepAgent`	一行创建 Agent
文件系统	`createFilesystemMiddleware`、`ls/read_file/write_file/edit_file/delete/glob/grep/execute`	让 Agent 能「操作文件」
后端	`StateBackend`、`FilesystemBackend`、`StoreBackend`、`CompositeBackend`、`LocalShellBackend`、`LangSmithSandbox`	文件存哪：图状态 / 真实磁盘 / Store / 组合 / 沙箱
子 Agent	`createSubAgentMiddleware`、`createSubAgent`、`GENERAL_PURPOSE_SUBAGENT`、`task` 工具	主 Agent 可以「派活」
异步任务	`start_async_task / check_async_task / update_async_task / cancel_async_task / list_async_tasks`	长任务后台跑
上下文	`createSummarizationMiddleware`、`computeSummarizationDefaults`	长对话自动摘要
记忆	`createMemoryMiddleware`、`createAgentMemoryMiddleware`	跨会话记忆
技能	`createSkillsMiddleware`、`listSkills`、`parseSkillMetadata`、`MAX_SKILL_*`	SKILL.md 式技能体系
护栏	`createPatchToolCallsMiddleware`、`createCompletionCallbackMiddleware`	严格保证 tool_call / tool_result 配对等

这就是「Deep Agents」的定位：不是又一个循环实现，而是一整套让 Agent 能长期、可控地干活的基础设施。

2. 最小用法（真实代码）

import { createDeepAgent, FilesystemBackend } from 'deepagents';
import { ChatAnthropic } from '@langchain/anthropic';

const model = new ChatAnthropic({
  model: 'deepseek-v4-flash',
  apiKey: process.env.ANTHROPIC_AUTH_TOKEN,
  anthropicApiUrl: process.env.ANTHROPIC_BASE_URL,   // 兼容端点
  temperature: 0,
  maxTokens: 2048,
});

const agent = createDeepAgent({
  model,
  systemPrompt: '你是一个严谨的助手：先规划，再动手，产物写入 workspace。',
  backend: new FilesystemBackend({ rootDir: '/tmp/deep-lab/ws' }),  // ← 落真实磁盘
});

const res = await agent.invoke({
  messages: [{ role: 'user', content: '读取 readme.md，把要点整理成 notes.md（Markdown），最后告诉我目录里现在有哪些文件。' }],
});

createDeepAgent 的关键选项（本机 d.ts 核对）：model、systemPrompt、tools、subagents、middleware、backend。

3. 实测：它自己决定怎么干

我在 workspace 里放了一个 readme.md，让它整理成 notes.md。真实的工具调用时间线（含参数）：

[AI tool_calls] ls({"path":"/"}) | glob({"pattern":"**/readme.md"})
[AI tool_calls] ls({"path":"/tmp/deep-lab/ws"}) | read_file({"file_path":"/tmp/deep-lab/ws/readme.md","offset":0,"limit":...})
[AI tool_calls] write_file({"file_path":"/tmp/deep-lab/ws/notes.md","content":"# 项目说明 —..."})
[AI tool_calls] ls({"path":"/tmp/deep-lab/ws"})

读法很清楚：

先侦察：ls / + glob **/readme.md 找到目标文件；
再读取：ls 确认工作目录 + read_file 读内容（两个工具并行调用）；
写产物：write_file 把整理结果写进 notes.md；
写后自检：再 ls 一次确认文件在。

最终回答（真实文本节选）：

完成。

## 做了什么
1. 定位文件：readme 位于 /tmp/deep-lab/ws/readme.md（工作目录 /tmp/deep-lab/ws）。
2. 读取内容：原文共 4 行，是一份简短的项目说明。
3. 写入产物：按"所有产物写到 workspace 目录"的约定，把要点整理成 /tmp/deep-lab/ws/notes.md。

## 目录现状
/tmp/deep-lab/ws 下现有 2 个文件：notes.md（344 字节）、readme.md（144 字节）
其中 notes.md 是本次新建的，readme.md 为原有文件，未作任何修改。

产物确实落盘（宿主视角，不是模型自述）：

$ ls -la ws
-rw-r--r--  344  notes.md      ← 本次新建
-rw-r--r--  144  readme.md

$ head -8 ws/notes.md
# 项目说明 —— 要点整理

> 来源：`readme.md`

## 要点

1. **项目性质**：这是一个演示项目。
2. **项目目标**：验证 deep agents 的规划能力与文件能力。

注意它「写后自检」这个动作——这正是 Deep Agents 想传达的工程习惯：以工具结果为准，而不是模型说自己写完了。（呼应本站 InkOS 的「以落盘为准」。）

4. 几个值得记住的设计

① 后端是「可换的」

backend 决定了「文件系统」到底落在哪：

后端	文件在哪	适合
`StateBackend`	LangGraph 状态里（虚拟文件系统）	无副作用试跑、测试
`FilesystemBackend`	真实磁盘（构造参数：`rootDir` / `virtualMode` / `maxFileSizeMb`）	本地开发、批处理工具
`StoreBackend`	外部 Store	多会话共享
`CompositeBackend`	组合多个后端	分区/路由
`LocalShellBackend`、`LangSmithSandbox`	本机 shell / 沙箱	需要执行命令的隔离场景

换后端不用改 Agent 逻辑——这是它比「自己写文件工具」值钱的地方。

② 子 Agent 与异步任务

task 工具 + createSubAgentMiddleware 让主 Agent 能把子任务派给子 Agent；start_async_task 系列则把长任务放到后台，主流程不必干等。能力更强，但调用次数与成本也更高——要有节制地用。

③ 摘要与记忆是分开的

createSummarizationMiddleware（压缩当前会话的上下文）和 createMemoryMiddleware（跨会话持久记忆）是两件事，别混。长任务 Agent 的「不忘事」通常两者都要。

5. 和本站其它内容的关系

你已经看过的	和 Deep Agents 的关系
手写 agent 循环	Deep Agents = 你手写的那套「循环 + 工具 + 落盘」的平台化版本
LangGraph 状态图	Deep Agents 底层就是它；中间件最终变成图上的节点与状态更新
LangChain vs pi-agent	pi 走「薄 + 透明」，Deep Agents 走「厚 + 开箱即用」，是两种取向的典型代表
p i（InkOS 的底座）	想做自己的生产 harness（确认闸门/原子落盘）时，薄框架更顺手

6. 实测踩到的坑 / 注意事项

ls 无参会列出根目录：实测第一条工具调用就是 ls({"path":"/"})，输出是文件系统根（/.file /Applications …）。想让它「待在项目里」，要么用 virtualMode、要么在 systemPrompt 里约束路径约定，否则容易越界去翻系统目录；
步数增长很快：这次任务只有一句话，也产生了 4 轮工具调用、14 条消息。生产里务必设 recursionLimit，并盯着 token 成本；
模型必须支持工具调用；推理模型对强制 tool_choice 敏感（本站实测过 LangChain 在这个点上直接 400：Thinking mode does not support this tool_choice）；
别照搬 Python 版教程：本机 1.13.4 的内置工具清单里没有 Python 版常见的 write_todos 规划工具（我核对的是导出的 FILESYSTEM_TOOL_NAMES / ASYNC_TASK_TOOL_NAMES）。要规划能力，可以自己在 middleware 里加工具，或写进 systemPrompt；
文件系统后端的安全边界：FilesystemBackend 有路径解析与安全校验（源码注释提到 security checks），但别把 rootDir 指到敏感目录；要执行命令的场景优先用沙箱后端。

7. 什么时候用它

你要的是一个「能处理多步任务、会读文件写文件、长任务不忘事」的 Agent → 它开箱即用；
你要的是「完全掌控循环与权限边界」的生产系统 → 参考 pi-agent 或直接手写；
你只是想「调一下模型 + 调个工具」→ 用 createReactAgent 就够了，不必上 Deep Agents。

关联

参考

npm：deepagents（1.13.4，本机实测版本）
LangChain 文档：docs.langchain.com（Deep Agents 章节）
Web 端另有 deepagents/browser 入口（本机包内 dist/browser.js 存在）

自测

Deep Agents 和 LangGraph 是什么关系？
backend 有哪几类？FilesystemBackend 的三个构造参数是什么？
实测里 Agent 的四个动作分别是什么？最后一步为什么要再 ls 一次？
摘要（summarization）和记忆（memory）有什么区别？
为什么说「别照搬 Python 版教程」？

1. 它到底打包了什么​

2. 最小用法（真实代码）​

3. 实测：它自己决定怎么干​

4. 几个值得记住的设计​

① 后端是「可换的」​

② 子 Agent 与异步任务​

③ 摘要与记忆是分开的​

5. 和本站其它内容的关系​

6. 实测踩到的坑 / 注意事项​

7. 什么时候用它​

关联​

参考​

自测​