deepagents

Deepagents 技能

用于构建自主编码 Agent 的 Langchain deep agents 框架。适用于 Agent 框架、后端、子 Agent、人机协作、长期记忆、中间件和基于命令行的 Agent 开发，内容根据官方文档生成。

何时使用此技能

遇到以下情况时应触发此技能：

• 使用 deepagents
• 询问 deepagents 的功能或 API
• 实现 deepagents 解决方案
• 调试 deepagents 代码
• 学习 deepagents 最佳实践

快速参考

常见模式

模式 1： LangChain 文档主页LangChain + LangGraph搜索...⌘K支持GitHub试用 LangSmith试用 LangSmith搜索...导航核心能力后端LangChainLangGraphDeep Agents集成学习参考贡献Python概览开始使用快速入门自定义核心能力Agent 框架后端子 Agent人工参与长期记忆中间件命令行界面使用 CLI本页内容快速入门内置后端StateBackend（临时）FilesystemBackend（本地磁盘）StoreBackend（LangGraph 存储）CompositeBackend（路由器）指定后端路由到不同后端使用虚拟文件系统添加策略钩子协议参考核心能力后端复制页面为 deep agent 选择并配置文件系统后端。你可以指定到不同后端的路由、实现虚拟文件系统，并强制执行策略。复制页面

Deep agent 通过 ls、read_file、write_file、edit_file、glob 和 grep 等工具，向 Agent 提供文件系统接口。这些工具通过可插拔后端运行。本页介绍如何选择后端、将不同路径路由到不同后端、实现自己的虚拟文件系统（例如 S3 或 Postgres）、添加策略钩子，以及如何遵循后端协议。

​快速入门

以下是一些预构建的文件系统后端，可供你快速用于 deep agent：

内置后端说明默认agent = create_deep_agent() 状态中的临时存储。Agent 的默认文件系统后端存储在 langgraph 状态中。请注意，此文件系统只会在单个线程中持久化。本地文件系统持久化agent = create_deep_agent(backend=FilesystemBackend(root_dir="/Users/nh/Desktop/")) 这会让 deep agent 访问本地计算机的文件系统。你可以指定 Agent 可访问的根目录。请注意，提供的任何 root_dir 都必须是绝对路径。持久化存储（LangGraph 存储）agent = create_deep_agent(backend=lambda rt: StoreBackend(rt)) 这会让 Agent 访问可跨线程持久化的长期存储。适合存储可供 Agent 在多次执行期间使用的长期记忆或指令。组合后端默认临时存储，/memories/ 持久化。Composite 后端灵活性最高。你可以指定文件系统中的不同路由，让它们指向不同后端。有关可直接粘贴使用的示例，请参阅下方的 Composite 路由。

​内置后端

​StateBackend（临时）

复制

# By default we provide a StateBackend
agent = create_deep_agent()

# Under the hood, it looks like
from deepagents.backends import StateBackend
agent = create_deep_agent(
    backend=(lambda rt: StateBackend(rt))
    # Note that the tools access State through the runtime.state
)

工作原理：将文件存储在当前线程的 LangGraph Agent 状态中。通过检查点在同一线程的多个 Agent 回合之间持久化。

适用场景：作为 Agent 编写中间结果的草稿区。自动清除较大的工具输出，之后 Agent 可以分段读取。

​FilesystemBackend（本地磁盘）

复制

from deepagents.backends import FilesystemBackend
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
)

工作原理：在可配置的 root_dir 下读取/写入真实文件。你可以选择设置 virtual_mode=True，在 root_dir 下进行沙箱隔离并规范化路径。使用安全的路径解析，在可能的情况下防止不安全的符号链接遍历，并可使用 ripgrep 快速执行 grep。

适用场景：

• 本地计算机上的项目
• CI 沙箱
• 已挂载的持久化卷

​StoreBackend（LangGraph 存储）

复制

from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    backend=(lambda rt: StoreBackend(rt)),
    # Note that the tools access Store through the runtime.store
    store=InMemoryStore()
)

工作原理：将文件存储在运行时提供的 LangGraph BaseStore 中，从而实现跨线程的持久化存储。

适用场景：

• 已配置 LangGraph 存储的现有环境（例如 Redis、Postgres，或基于 BaseStore 的云实现）。
• 通过 LangSmith Deployment 部署 Agent（系统会自动为 Agent 配置存储）。

​CompositeBackend（路由器）

复制

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),
    routes={
        "/memories/": StoreBackend(rt),
    }
)

agent = create_deep_agent(
    backend=composite_backend,
    store=InMemoryStore()  # Store passed to create_deep_agent, not backend
)

工作原理：根据路径前缀，将文件操作路由到不同后端。在列表和搜索结果中保留原始路径前缀。

适用场景：

• 希望 Agent 同时使用临时存储和跨线程存储时，CompositeBackend 允许你同时提供 StateBackend 和 StoreBackend。
• 希望将多个信息来源作为单个文件系统提供给 Agent 时。例如，你在一个 Store 中将长期记忆存储于 /memories/ 下，同时还有一个自定义后端，在 /docs/ 下提供文档。

​指定后端

将后端传递给 create_deep_agent(backend=...)。文件系统中间件会将其用于所有工具。你可以传递以下任一项：

• 实现 BackendProtocol 的实例（例如 FilesystemBackend(root_dir=".")），或
• 工厂 BackendFactory = Callable[[ToolRuntime], BackendProtocol]（适用于需要运行时的后端，例如 StateBackend 或 StoreBackend）。

如果省略，默认值为 lambda rt: StateBackend(rt)。

​路由到不同后端

将命名空间中的不同部分路由到不同后端。常见做法是持久化 /memories/*，并让其他内容保持临时存储。

复制

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, FilesystemBackend

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),
    routes={
        "/memories/": FilesystemBackend(root_dir="/deepagents/myagent", virtual_mode=True),
    },
)

agent = create_deep_agent(backend=composite_backend)

行为：

• /workspace/plan.md → StateBackend（临时）
• /memories/agent.md → /deepagents/myagent 下的 FilesystemBackend
• ls、glob、grep 会汇总结果并显示原始路径前缀。

注意：

• 较长的前缀优先级更高（例如，路由 "/memories/projects/" 可以覆盖 "/memories/"）。
• 使用 StoreBackend 路由时，请确保 Agent 运行时提供了存储（runtime.store）。

​使用虚拟文件系统

构建自定义后端，将远程或数据库文件系统（例如 S3 或 Postgres）映射到工具命名空间中。

设计指南：

• 路径是绝对路径（/x/y.txt）。确定如何将其映射到存储键/行。
• 高效实现 ls_info 和 glob_info（如果可用，使用服务端列表；否则使用本地筛选）。
• 对于缺失文件或无效正则表达式模式，返回用户可读的错误字符串。
• 对于外部持久化，在结果中设置 files_update=None；只有进程内状态后端才应返回 files_update 字典。

S3 风格示例：

复制

from deepagents.backends.protocol import BackendProtocol, WriteResult, EditResult
from deepagents.backends.utils import FileInfo, GrepMatch

class S3Backend(BackendProtocol):
    def __init__(self, bucket: str, prefix: str = ""):
        self.bucket = bucket
        self.prefix = prefix.rstrip("/")

    def _key(self, path: str) -> str:
        return f"{self.prefix}{path}"

    def ls_info(self, path: str) -> list[FileInfo]:
        # List objects under _key(path); build FileInfo entries (path, size, modified_at)
        ...

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> str:
        # Fetch object; return numbered content or an error string
        ...

    def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str:
        # Optionally filter server‑side; else list and scan content
        ...

    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
        # Apply glob relative to path across keys
        ...

    def write(self, file_path: str, content: str) -> WriteResult:
        # Enforce create‑only semantics; return WriteResult(path=file_path, files_update=None)
        ...

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        # Read → replace (respect uniqueness vs replace_all) → write → return occurrences
        ...

Postgres 风格示例：

表 files(path text primary key, content text, created_at timestamptz, modified_at timestamptz)

将工具操作映射到 SQL：

• ls_info 使用 WHERE path LIKE $1 || '%'
• glob_info 在 SQL 中筛选，或先获取数据再在 Python 中应用 glob
• grep_raw 可以按扩展名或最后修改时间获取候选行，然后扫描行内容

​添加策略钩子

通过子类化或包装后端来强制执行企业规则。

阻止在指定前缀下写入/编辑（子类化）：

复制

from deepagents.backends.filesystem import FilesystemBackend
from deepagents.backends.protocol import WriteResult, EditResult

class GuardedBackend(FilesystemBackend):
    def __init__(self, *, deny_prefixes: list[str], **kwargs):
        super().__init__(**kwargs)
        self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in deny_prefixes]

    def write(self, file_path: str, content: str) -> WriteResult:
        if any(file_path.startswith(p) for p in self.deny_prefixes):
            return WriteResult(error=f"Writes are not allowed under {file_path}")
        return super().write(file_path, content)

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        if any(file_path.startswith(p) for p in self.deny_prefixes):
            return EditResult(error=f"Edits are not allowed under {file_path}")
        return super().edit(file_path, old_string, new_string, replace_all)

通用包装器（适用于任何后端）：

复制

from deepagents.backends.protocol import BackendProtocol, WriteResult, EditResult
from deepagents.backends.utils import FileInfo, GrepMatch

class PolicyWrapper(BackendProtocol):
    def __init__(self, inner: BackendProtocol, deny_prefixes: list[str] | None = None):
        self.inner = inner
        self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in (deny_prefixes or [])]

    def _deny(self, path: str) -> bool:
        return any(path.startswith(p) for p in self.deny_prefixes)

    def ls_info(self, path: str) -> list[FileInfo]:
        return self.inner.ls_info(path)

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> str:
        return self.inner.read(file_path, offset=offset, limit=limit)

    def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str:
        return self.inner.grep_raw(pattern, path, glob)

    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
        return self.inner.glob_info(pattern, path)

    def write(self, file_path: str, content: str) -> WriteResult:
        if self._deny(file_path):
            return WriteResult(error=f"Writes are not allowed under {file_path}")
        return self.inner.write(file_path, content)

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        if self._deny(file_path):
            return EditResult(error=f"Edits are not allowed under {file_path}")
        return self.inner.edit(file_path, old_string, new_string, replace_all)

​协议参考

后端必须实现 BackendProtocol。

必需端点：

ls_info(path: str) -> list[FileInfo]

返回至少包含 path 的条目。若可用，请包含 is_dir、size、modified_at。按 path 排序，以确保输出具有确定性。

read(file_path: str, offset: int = 0, limit: int = 2000) -> str

返回带行号的内容。文件缺失时，返回 "Error: File '/x' not found"。

grep_raw(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> list[GrepMatch] | str

返回结构化匹配结果。正则表达式无效时，返回类似 "Invalid regex pattern: ..." 的字符串（不要抛出异常）。

glob_info(pattern: str, path: str = "/") -> list[FileInfo]

将匹配的文件作为 FileInfo 条目返回（无匹配项时返回空列表）。

write(file_path: str, content: str) -> WriteResult

仅创建。发生冲突时，返回 WriteResult(error=...)。成功时，设置 path；对于状态后端，设置 files_update={...}；外部后端应使用 files_update=None。

edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult

除非 replace_all=True，否则必须确保 old_string 唯一。未找到时，返回错误。成功时包含 occurrences。

支持的类型：

• WriteResult(error, path, files_update)
• EditResult(error, path, files_update, occurrences)
• FileInfo 字段：path（必填），is_dir、size、modified_at（可选）。
• GrepMatch 字段：path、line、text。

在 GitHub 上编辑此页面或提交问题。

通过 MCP 将这些文档连接到 Claude、VSCode 等，即可获得实时答案。

此页面是否有帮助？是 否

Agent 框架能力上一个子 Agent下一个⌘I

LangChain 文档主页githubxlinkedinyoutube资源论坛更新日志LangChain 学院信任中心公司关于我们招聘博客githubxlinkedinyoutube由……提供支持

ls

模式 2： Docs by LangChain 首页LangChain + LangGraph搜索...⌘K支持GitHub试用 LangSmith试用 LangSmith搜索...导航核心能力Agent 框架能力LangChainLangGraphDeep Agents集成学习参考贡献Python概览开始使用快速入门自定义核心能力Agent 框架后端子 Agent人工参与长期记忆中间件命令行界面使用 CLI本页文件系统访问大型工具结果淘汰可插拔存储后端任务委派（子 Agent）对话历史摘要未完成工具调用修复待办事项跟踪人工参与提示缓存（Anthropic）核心能力Agent 框架能力复制页面复制页面我们将 deepagents 视为一种“Agent 框架”。它与其他 Agent 框架使用相同的核心工具调用循环，但内置了工具和能力。本页列出了构成 Agent 框架的组件。

​文件系统访问

该框架提供六种用于文件系统操作的工具，让文件成为 Agent 环境中的一等公民：

工具描述ls列出目录中的文件及其元数据（大小、修改时间）read_file读取文件内容并显示行号，支持对大型文件使用 offset/limitwrite_file创建新文件edit_file在文件中执行精确字符串替换（支持全局替换模式）glob查找与模式匹配的文件（例如，**/*.py）grep搜索文件内容，支持多种输出模式（仅显示文件、显示带上下文的内容，或显示计数）

​大型工具结果淘汰

FilesystemMiddleware 会在大型工具结果超过 token 阈值时，自动将其淘汰到文件系统，从而避免上下文窗口饱和。

工作方式：

监控工具调用结果的大小（默认阈值：20,000 个 token，可通过 tool_token_limit_before_evict 配置）超过阈值时，使用配置的后端写入结果将工具结果替换为截断后的预览和文件引用Agent 可根据需要从文件系统读取完整结果

​可插拔存储后端

该框架通过协议抽象文件系统操作，以便针对不同用例采用不同的存储策略。

可用后端：

StateBackend - 临时内存存储文件保存在 Agent 状态中（随对话一起创建检查点）在一个会话线程内持久保存，但不会跨会话线程保存适用于临时工作文件FilesystemBackend - 访问真实文件系统从实际磁盘读取/写入支持虚拟模式（限制在根目录下运行）与系统工具集成（使用 ripgrep 执行 grep）安全功能：路径验证、大小限制、防止符号链接StoreBackend - 跨对话持久存储使用 LangGraph 的 BaseStore 实现持久化按 assistant_id 命名空间文件可跨对话持久保存适用于长期记忆或知识库CompositeBackend - 将不同路径路由到不同后端示例：/ → StateBackend，/memories/ → StoreBackend使用最长前缀匹配进行路由支持混合存储策略有关配置详情和示例，请参阅 backends。

​任务委派（子 Agent）

该框架允许主 Agent 创建临时“子 Agent”，用于执行彼此隔离的多步骤任务。

优点：

上下文隔离 - 子 Agent 的工作不会占用主 Agent 的上下文并行执行 - 多个子 Agent 可以并行运行专业化 - 子 Agent 可以使用不同的工具/配置token 效率 - 大型子任务的上下文会压缩为单个结果

工作方式：

主 Agent 拥有一个 task 工具调用该工具时，会创建一个拥有独立上下文的新 Agent 实例子 Agent 会自主执行，直至任务完成向主 Agent 返回一份最终报告子 Agent 是无状态的（无法向主 Agent 发送多条消息）默认子 Agent：“general-purpose”子 Agent 会自动提供默认配有文件系统工具可通过其他工具/中间件自定义自定义子 Agent：定义配有特定工具的专用子 Agent示例：code-reviewer、web-researcher、test-runner通过 subagents 参数配置

​对话历史摘要

当 token 用量过高时，该框架会自动压缩较早的对话历史。

配置：

当 token 用量达到模型配置文件中 max_input_tokens 的 85% 时触发保留 10% 的 token 作为近期上下文如果模型配置文件不可用，则在达到 170,000 个 token 时触发／保留 6 条消息由模型对较早的消息进行摘要

优点：

支持超长对话，而不会触及上下文限制在压缩很早之前的历史记录时，保留近期上下文对 Agent 透明（表现为一条特殊的系统消息）

​未完成工具调用修复

当工具调用在收到结果前被中断或取消时，该框架会修复消息历史记录。

问题：

Agent 请求工具调用：“请运行 X”工具调用被中断（用户取消、发生错误等）Agent 在 AIMessage 中看到 tool_call，但没有对应的 ToolMessage这会导致消息序列无效

解决方案：

检测没有结果的 AIMessage 对象中的 tool_calls创建表示调用已取消的合成 ToolMessage 响应在 Agent 执行前修复消息历史记录

优点：

避免不完整的消息链让 Agent 困惑优雅地处理中断和错误保持对话连贯性

​待办事项跟踪

该框架提供 write_todos 工具，供 Agent 用于维护结构化任务列表。

功能：

使用状态（'pending'、'in_progress'、'completed'）跟踪多个任务保存在 Agent 状态中帮助 Agent 组织复杂的多步骤工作适用于长时间运行的任务和规划

​人工参与

该框架可以在指定的工具调用处暂停 Agent 执行，以便人工审批或修改。

此功能通过 interrupt_on 参数启用。

配置：

将包含工具名称和中断配置的映射传递给 create_deep_agent，以设置 interrupt_on示例：interrupt_on={"edit_file": True} 会在每次编辑前暂停可提供审批消息或修改工具输入

优点：

为破坏性操作设置安全关卡在昂贵的 API 调用前进行用户验证交互式调试与指导

​提示缓存（Anthropic）

该框架启用 Anthropic 的提示缓存功能，以减少重复的 token 处理。

工作方式：

缓存各轮对话中重复出现的部分提示显著降低长系统提示词的延迟和成本非 Anthropic 模型会自动跳过

优点：

系统提示词（尤其是包含文件系统文档时）可能超过 5k 个 token若未启用缓存，这些内容会在每一轮中重复处理缓存可带来约 10 倍的速度提升和成本降低

在 GitHub 上编辑此页面或提交 issue。通过 MCP 将这些文档连接到 Claude、VSCode 等，以获取实时答案。

此页面是否有帮助？是/否自定义 Deep Agents上一页后端下一页⌘IDocs by LangChain 首页githubxlinkedinyoutube资源论坛变更日志LangChain Academy信任中心公司关于我们职业博客githubxlinkedinyoutube技术支持方

deepagents

示例代码模式

示例 1（python）：

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

model = init_chat_model(model="openai:gpt-5")
agent = create_deep_agent(model=model)

示例 2（sql）：

from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
)

参考文件

此技能在 references/ 中包含全面的文档：

• capabilities.md - 功能文档
• core.md - 核心文档
• getting_started.md - 入门文档
• tools.md - 工具文档

需要详细信息时，使用 view 阅读特定的参考文件。

使用此技能

入门指南

从 getting_started 或 tutorials 参考文件开始，了解基础概念。

查找特定功能

使用相应类别的参考文件（api、guides 等）获取详细信息。

查找代码示例

上方的快速参考部分包含从官方文档中提取的常见模式。

资源

references/

整理了从官方来源提取的文档。这些文件包含：

• 详细说明
• 带有语言注释的代码示例
• 指向原始文档的链接
• 便于快速导航的目录

scripts/

在此处添加用于常见自动化任务的辅助脚本。

assets/

在此处添加模板、样板代码或示例项目。

注意事项

• 此技能由官方文档自动生成
• 参考文件保留了源文档的结构和示例
• 代码示例包含语言检测，以便更好地进行语法高亮
• 快速参考模式从文档中的常见用法示例提取

更新

若要使用更新后的文档刷新此技能：

1. 使用相同的配置重新运行 scraper
2. 技能将使用最新信息重新构建