Deep Agents：智能体如何利用文件系统进行上下文工程

Deep Agents Header

概述

Deep Agents 是 LangChain 推出的一个开源智能体框架，基于 LangGraph 构建。它的一个关键特性是能够访问一套文件系统工具，使智能体能够读取、写入、编辑、列出和搜索文件系统中的文件。

这种设计背后的核心理念是上下文工程（Context Engineering）——用恰当的信息填充上下文窗口以支持下一步操作的微妙艺术和科学。

上下文工程的三个层面

Context Engineering Diagram

理解上下文工程需要区分三个关键概念：

概念	描述
拥有的上下文（Available Context）	智能体可访问的全部信息
需要的上下文（Needed Context）	回答特定问题所需的信息
检索的上下文（Retrieved Context）	智能体实际调入上下文窗口的信息

理想情况下，检索的上下文应该恰好等于需要的上下文。但现实中，这三者之间的不匹配会导致各种问题。

四大失效场景与文件系统解决方案

场景一：令牌过剩问题

问题：当检索到的上下文远大于实际需要时，会导致：

成本大幅增加
性能显著下降
上下文窗口被无关信息占用

解决方案：文件系统作为临时存储（Scratchpad）

Manus Context Engineering

与其将所有工具调用结果和笔记都保存在对话历史中，智能体可以将这些内容写入文件系统，然后在需要时有选择性地查找相关信息。

例如，一个需要 10,000+ tokens 的工具结果，如果一直保留在对话历史中，会持续消耗上下文空间。但如果将其写入文件系统，智能体可以在需要时精确读取所需的行数。

场景二：上下文需求超出窗口限制

问题：智能体可能需要大量信息，但这些信息无法通过单次查询全部获得，导致上下文窗口溢出。

解决方案：动态内容管理

文件系统支持多种动态内容管理策略：

长期规划存储：制定计划并存储到文件系统，后续可以检索和更新
子智能体协作：通过子智能体分工处理不同任务，避免"传话游戏"式的信息丢失
动态指令加载：将不同场景的指令存储在不同文件中，按需加载

场景三：难以定位利基信息

问题：语义搜索在处理 API 文档、代码文件等结构化内容时效果不佳。"检索的内容 ≠ 必需的内容"。

解决方案：智能搜索工具

文件系统提供了比语义搜索更精确的搜索工具：

工具	功能	适用场景
`ls`	列出目录内容	浏览文件结构
`glob`	模式匹配文件	查找特定类型文件
`grep`	正则搜索内容	精确定位代码或文本

这些工具的优势在于：

模型专门训练：当代模型经过专门训练来理解文件系统遍历
逻辑结构利用：技术文档和代码通常已有良好的逻辑结构
精确定位：glob 和 grep 不仅能定位特定文件，还能定位到特定行和特定字符

场景四：长期学习能力缺失

问题：智能体可能缺乏回答问题所需的必要上下文，无法从用户反馈中学习。

解决方案：自适应学习

智能体可以通过直接更新自身的指令文件来学习：

用户反馈可触发智能体自动记录新信息
重要的学习成果可写入文件，为未来交互存储必要的上下文
系统可以随时间"增长自己的技能集"

Deep Agents 框架详解

核心组件

Deep Agents 实现了来自 Claude Code、Manus 等先进智能体的三大核心原则：

执行前规划：使用 write_todos 工具进行任务分解
计算机访问：通过文件系统工具进行上下文管理
子智能体委派：通过 task 工具生成专门的子智能体

内置工具集

python

# 任务规划工具
write_todos  # 分解复杂任务为离散步骤
read_todos   # 读取和跟踪进度

# 文件系统工具
read_file    # 读取文件（可指定行数）
write_file   # 写入文件
edit_file    # 编辑文件

# 搜索工具
ls           # 列出目录
glob         # 模式匹配
grep         # 内容搜索

# 执行和委派
execute      # 执行 shell 命令
task         # 委派给子智能体

快速开始

安装

bash

pip install deepagents tavily-python

基本使用

python

from deepagents import create_deep_agent

def internet_search(query: str, max_results: int = 5):
    """运行网络搜索"""
    return tavily_client.search(query, max_results=max_results)

agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="进行研究并撰写精炼的报告。",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "什么是 LangGraph？"}]
})

中间件架构

Deep Agents 使用可组合的中间件来扩展功能：

中间件	功能
`TodoListMiddleware`	任务规划和进度跟踪
`FilesystemMiddleware`	文件系统操作，自动将大于 20K tokens 的结果保存到文件
`SubAgentMiddleware`	子智能体生成和管理
`SummarizationMiddleware`	智能上下文摘要
`HumanInTheLoopMiddleware`	人工审批工作流

沙箱执行：安全的代码运行环境

Sandbox Header

LangChain 还提供了一套沙箱集成，允许在远程沙箱中安全执行任意 DeepAgent 代码。目前支持的提供商包括：

Runloop
Daytona
Modal

为什么需要沙箱？

DeepAgents Sandbox Workflow

沙箱解决了五个核心问题：

问题	描述
安全性	保护本地机器免受潜在有害代码的影响
干净环境	实现隔离设置，不污染本地系统
并行执行	在隔离环境中同时运行多个智能体
长时任务	防止阻塞本地资源
可重现性	确保团队间执行的一致性

使用方法

1. 设置环境变量

bash

# Daytona
export DAYTONA_API_KEY="your-key"

# Runloop
export RUNLOOP_API_KEY="your-key"

# Modal
modal setup

2. 运行 CLI

bash

uvx deepagents-cli --sandbox runloop --sandbox-setup ./setup.sh

3. 设置脚本示例

bash

#!/bin/bash
set -e  # 出错时退出

echo "配置沙箱环境..."

# 1. 使用 GitHub token 克隆仓库
echo "克隆仓库..."
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace
echo "✓ 仓库已克隆"

# 2. 设置持久化环境变量
echo "设置环境变量..."
cat >> ~/.bashrc <<'EOF'

# 从本地传入环境变量到沙箱
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export FAL_API_KEY="${FAL_API_KEY}"

# 自动导航到工作区
cd $HOME/workspace
EOF

# 3. 激活环境
source ~/.bashrc
echo "✓ 环境已配置"

安全注意事项

即使在隔离的沙箱中，智能体仍然容易受到提示注入攻击。建议采取以下缓解措施：

使用可信的设置脚本
实施人工监督
使用短期凭证

上下文工程的四大策略

LangChain 总结了上下文工程的四大核心策略：

策略	描述	示例工具
Write（写入）	将上下文保存到上下文窗口之外	`write_file`
Select（选择）	将上下文拉入上下文窗口	`read_file`, `grep`
Compress（压缩）	仅保留所需的 tokens	`SummarizationMiddleware`
Isolate（隔离）	分割上下文以帮助智能体执行任务	`task`（子智能体）

文件系统为智能体提供了单一接口来灵活存储、检索和更新无限量的上下文，是实现这四大策略的关键基础设施。

参考来源

LangChain Blog: How agents can use filesystems for context engineering - Nick Huang, 2025年11月21日
LangChain Blog: Execute Code with Sandboxes for DeepAgents - Vivek Trivedy, 2025年11月13日
LangChain Blog: Deep Agents
LangChain Documentation: Deep Agents Overview

Deep Agents：智能体如何利用文件系统进行上下文工程 ​

概述 ​

上下文工程的三个层面 ​

四大失效场景与文件系统解决方案 ​

场景一：令牌过剩问题 ​

场景二：上下文需求超出窗口限制 ​

场景三：难以定位利基信息 ​

场景四：长期学习能力缺失 ​

Deep Agents 框架详解 ​

核心组件 ​

内置工具集 ​

快速开始 ​

中间件架构 ​

沙箱执行：安全的代码运行环境 ​

为什么需要沙箱？ ​

使用方法 ​

安全注意事项 ​

上下文工程的四大策略 ​

相关资源 ​

参考来源 ​

Deep Agents：智能体如何利用文件系统进行上下文工程

概述

上下文工程的三个层面

四大失效场景与文件系统解决方案

场景一：令牌过剩问题

场景二：上下文需求超出窗口限制

场景三：难以定位利基信息

场景四：长期学习能力缺失

Deep Agents 框架详解

核心组件

内置工具集

快速开始

中间件架构

沙箱执行：安全的代码运行环境

为什么需要沙箱？

使用方法

安全注意事项

上下文工程的四大策略

相关资源

参考来源