从零搭建数据分析深度智能体（Deep Agent）

这篇适合谁、读完能做到什么

这篇适合已经会用 LangChain 写简单智能体，想搞清楚 Deep Agents 那一套能力（文件系统、上下文压缩、技能、子代理）到底是怎么一块块拼起来的开发者。读完你能用 create_agent 搭一个能读 CSV、在沙箱里写代码跑分析的智能体，并且知道每一步加的是什么，以后可以只换掉自己需要的部分。

为什么不直接用 create_deep_agent

create_agent 和 create_deep_agent 都能精细控制工具和记忆。两者的主要区别是：Deep Agents 已经内置了一批常用能力，比如规划、文件系统工具和子代理。^[1]

如果 Deep Agents 默认的组装方式不合你的需要，就从 create_agent 开始，一次只加一个组件。这样你能看清每个组件带来什么，只换入真正需要的那几个。^[1] 这篇教程最后搭出来的栈和 create_deep_agent 默认组装的结构一致，只是每一块都是手动装上的。^[1]

目标：一个能分析 CSV 的智能体

这个智能体要做四件事：接收一个 CSV 文件做分析；在隔离的沙箱里写并执行 Python 代码；把绘图工作交给专门的可视化子代理；从技能文件里读取数据分析的套路。^[1]

整个过程分五步，每一步只加一个能力，前后是同一个智能体：最小智能体（只有模型和循环）、沙箱加文件系统、上下文压缩、技能、可视化子代理。^[1]

准备

• 安装依赖：Python 版本运行 pip install deepagents langsmith，JavaScript 版本用 npm install deepagents langsmith。^[1]

pip install deepagents langsmith

• LangSmith 账号和 API key：示例用的 LangSmithSandbox 通过 SandboxClient 开沙箱，它从环境变量 LANGSMITH_API_KEY 里取凭证，所以没有 API key 就跑不起来。^[1] 导出命令是：

export LANGSMITH_API_KEY=...

• 开启追踪：设置 LANGSMITH_TRACING=true 之后，每加一个组件，你都能在 LangSmith 里看到工具调用、中间件步骤和子代理委派。^[1]

export LANGSMITH_TRACING=true

• 模型提供商的 key：按你用的模型导出对应的变量，例如 OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY，用 Ollama 时要么本机已经启动 Ollama 服务，要么设置 OLLAMA_API_KEY 走云端推理。^[1]

第一步：最小智能体

用 create_agent 指定模型就能跑起来，这时的智能体没有文件系统，也不能执行代码。如果你让它分析一个 CSV，它只能靠提示词里的信息去猜。^[1] 这一步的目的是给后面的每个组件一个基线。

第二步：沙箱和文件系统

分析数据需要在文件上运行代码，这需要两样东西：一个隔离的沙箱，以及把沙箱暴露给模型的工具。LangSmithSandbox 提供的是隔离环境，智能体可以在里面装包、写脚本、运行它们，而不会碰到你的电脑。^[1]

FilesystemMiddleware 把沙箱里的文件操作变成工具，包括 read_file、write_file、edit_file、glob 和 grep，Python 版本还有 delete。因为 LangSmithSandbox 实现了沙箱协议，FilesystemMiddleware 还会加上一个 execute 工具，用来运行 shell 命令。^[1] 如果以后要换成别的后端，这个中间件可以保持不变。^[1]

沙箱的文件系统和你的电脑是分开的，所以智能体要用的文件必须在调用之前先上传。上传路径要用绝对的 POSIX 路径，比如 /sales.csv。写成 sales.csv 这样的相对路径会被以 invalid_path 拒绝，文件也不会写入沙箱。^[1]

把前面的代码合成一个脚本，Python 版本这样运行：

python analyze_sales.py

第一次运行时，LangSmith 会先开一个沙箱，这可能要几秒钟。脚本会上传 sales.csv，流式运行智能体，并在消息到达时打印出来。具体措辞每次运行都可能不同。^[1]

第三步：上下文压缩

每次工具调用的结果都会留在消息历史里。真实的分析会话里，多张图、失败的脚本和很大的 read_file 输出很快就会占满上下文窗口。^[1]

SummarizationMiddleware 会在历史太长时压缩较早的轮次，智能体可以继续工作，不需要你手动裁剪消息。这一步在第一个问题上体现不明显，在后续追问时才有用，比如"现在按产品分组，画出每月趋势"。^[1]

第四步：技能

技能（skills）用渐进式披露（progressive disclosure）的方式给智能体按需提供领域知识。智能体启动时只看到每个技能的轻量元数据，任务需要时才加载完整的技能文件。^[1] 这样，数据分析的规则不会一直占着系统提示词的 token。

一个技能放在目录里，比如 skills/pandas-patterns/，目录下有一个 SKILL.md 文件。下面是一个示例，写的是 pandas 和 matplotlib 的常用套路：

---
name: pandas-patterns
description: Common pandas and matplotlib patterns for data analysis and visualization
---

## Data loading
Use `pd.read_csv()` for CSV files. Always check `df.info()` and `df.describe()` first.

## Visualization
Use `matplotlib` for bar charts, `seaborn` for statistical plots.
Save figures with `plt.savefig("output.png", dpi=150, bbox_inches="tight")`.

## Reporting
Write a markdown summary to `report.md` alongside any generated charts.

技能的路径是在沙箱文件系统里解析的，不是在你的电脑上。所以配置 SkillsMiddleware 之前，要先把本地的 skills/ 目录上传到沙箱。^[1] 之后用 "Analyze sales.csv using our pandas patterns" 这样的提示词去试，智能体会在需要画图或写报告时加载这个技能；问一个用不到技能的问题，它就不会加载。^[1]

第五步：可视化子代理

有些任务会产生大量中间输出，比如脚本草稿、失败的运行和文件读取。如果都放在同一个线程里，会挤占主智能体的上下文。子代理（subagent）运行在自己的上下文窗口里，主智能体只看到最终结果，不用看到途中的每一次工具调用。^[1]

绘图很适合交给子代理，因为画图往往要反复修改脚本、装包、读报错，图才能画好。加上 TodoListMiddleware 和 SubAgentMiddleware 之后，主智能体可以通过 task 工具把绘图交给 visualizer 子代理，并且可以并行委派，不必等每张图都画完再继续。^[1]

在 LangSmith 里，你会看到一次对 visualizer 的 task 调用，它是一个独立的子运行，有自己的工具循环，最后只返回一段简短结果给主智能体。^[1]

限制和常见问题

• 上传路径写成相对路径，会被以 invalid_path 拒绝，文件不会写入沙箱。^[1]
• 第一次运行要先开沙箱，需要等几秒。^[1]
• 同样的提示词，每次模型运行的输出措辞可能不同，不要按字面去比对。^[1]
• 跑通之后，可以把 create_agent 组装的版本和 create_deep_agent 的默认组装对照着看，确认哪些组件你真的需要。^[1]

下一步

想看预先组装好的版本，可以接着读 Deep Agents 的自定义章节；想看用 create_deep_agent 完成的完整数据分析示例，也可以在官方文档里找到。^[1]

本文改编自 LangChain 官方教程《Build a data analysis agent from scratch》^[1]，原文以 MIT 许可证发布。