从零开始构建数据分析智能体

本指南将使用 create_agent 和 Deep Agent 中间件，从第一性原理出发构建一个数据分析智能体。 create_agent 和 create_deep_agent 都为你提供了对工具、记忆等方面的细粒度控制。两者的主要区别在于，Deep Agent 已经内置了一系列常用且有用的功能，例如规划、文件系统工具和子智能体。如果 Deep Agent 的默认框架不符合你的需求，本指南将向你展示如何从 create_agent 开始，一步步组装这个框架，这样你就能清楚地看到每个组件的作用，并只换入你的用例所需的部分。按照本指南构建一个能够：

接收 CSV 文件进行分析
在隔离的沙箱中编写并执行 Python 代码
将可视化工作委托给专门的子智能体
从技能文件加载数据分析模式

的智能体。最终的技术栈与 create_deep_agent 默认组装的相同。

你将学到什么

每个步骤都会为同一个数据分析智能体添加一项能力：

步骤	没有它时的问题	你添加的内容
最小智能体	—	基础循环：模型 + 工具，无框架
沙箱 + 文件系统	智能体无法读取 CSV 或运行 Python	隔离的后端 + 文件和执行工具
摘要功能	长会话会遇到上下文限制	自动历史压缩
技能	领域规则会膨胀系统提示	通过渐进式披露按需加载专业知识
子智能体	图表迭代会挤占主线程	隔离的工作线程 + 并行委托

设置

安装依赖包

安装本教程所需的包：

pip install deepagents langsmith

设置 LangSmith API 密钥

本教程使用 LangSmithSandbox，它通过 SandboxClient 来配置沙箱。该客户端使用你环境中的 LANGSMITH_API_KEY 进行身份验证，因此运行本教程需要 API 密钥。设置 LangSmith 还能让你查看智能体运行时发生情况的跟踪记录。

注册免费账户。你可以使用 Google、GitHub 或电子邮箱。
在 设置 → API 密钥 中创建一个 API 密钥。
导出 LangSmith API 密钥：

export LANGSMITH_API_KEY=...

启用跟踪功能，以便在你添加每个部分时，能够检查工具调用、中间件步骤和子智能体委托：

export LANGSMITH_TRACING=true

添加模型提供商 API 密钥

导出你在代码示例中使用的模型提供商的 API 密钥。例如：

export ANTHROPIC_API_KEY=...

构建智能体

创建最小智能体

一个数据分析智能体需要的不仅仅是一个聊天循环，但作为开始，我们从基础开始：仅包含一个模型和一个循环。使用 create_agent 并指定你想使用的模型：

from langchain.agents import create_agent

agent = create_agent("anthropic:claude-sonnet-4-6", tools=[])

这个可以运行，但智能体没有文件系统，也没有执行代码的能力。如果你要求它分析一个 CSV 文件，它只能根据提示进行猜测。接下来的步骤将添加真正的文件访问和代码执行能力。

添加沙箱后端

为了高效地分析数据，智能体需要在文件上运行代码。这需要两样东西：

一个隔离的沙箱，智能体可以在其中放置文件并在文件上运行代码，而无需让智能体访问你的主机。
一个后端，它使用 FilesystemMiddleware 提供文件系统工具（read_file、write_file、edit_file、delete、glob、grep）来操作沙箱。由于 LangSmithSandbox 后端实现了沙箱协议，FilesystemMiddleware 还会添加 execute 工具，该工具允许智能体运行 shell 命令。

LangSmithSandbox 是文件存放和命令运行的地方。FilesystemMiddleware 则将该环境作为工具暴露给模型。如果你稍后更换后端，相同的中间件也可以与其他后端一起工作。 LangSmithSandbox 为智能体提供了一个带有文件系统的隔离环境和一个用于运行 shell 命令的 execute 工具。有了它，智能体可以安装包、编写脚本并运行它们，而不会影响主机。若要从自定义镜像而非默认运行时启动，请在 create_sandbox() 中传递 snapshot_name 或 snapshot_id；参阅沙箱快照。将上一步的智能体替换为包含 FilesystemMiddleware 的版本：

from langchain.agents import create_agent
from deepagents.backends.langsmith import LangSmithSandbox
from deepagents.middleware import FilesystemMiddleware
from langsmith.sandbox import SandboxClient

client = SandboxClient()
sandbox = None
# 创建一个指向 langchain 文档的沙箱环境
sandbox = client.create_sandbox(name="langchain-docs", snapshot_name="docs-test-ci")
backend = LangSmithSandbox(sandbox=sandbox)

# 为文档构建一个基本的 agent
agent = create_agent(
    "anthropic:claude-sonnet-4-6",
    tools=[],
    middleware=[FilesystemMiddleware(backend=backend)],
)

沙箱文件系统与你的笔记本电脑是分开的。你必须在调用智能体之前将需要的文件上传到沙箱中：

import csv
import io

rows = [
    ["日期", "产品", "数量", "收入"],
    ["2025-08-01", "Widget A", 10, 250],
    ["2025-08-02", "Widget B", 5, 125],
    ["2025-08-03", "Widget A", 7, 175],
    ["2025-08-04", "Widget C", 3, 90],
]
buf = io.StringIO()
csv.writer(buf).writerows(rows)
backend.upload_files([("/sales.csv", buf.getvalue().encode())])

upload_stream = agent.stream_events(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "读取 /sales.csv 文件，并用一句话按产品汇总总收入。"
                    "请勿执行 shell 命令。"
                ),
            }
        ]
    },
    version="v3",
    config={"recursion_limit": 8},
)
for item in upload_stream.messages:
    print(item.text)
upload_stream.output

使用 LangSmithSandbox 时，上传路径必须是绝对的 POSIX 路径（例如 /sales.csv）。像 sales.csv 这样的相对路径会被拒绝，并提示 invalid_path，且文件不会写入沙箱。

将前面步骤的代码合并到一个脚本中并运行：

python analyze_sales.py

首次运行时，LangSmith 会配置一个沙箱（这可能需要几秒钟）。脚本会上传 sales.csv，流式传输智能体运行过程，并在助手消息到达时打印它们。你应该能看到对示例销售数据的分析：产品级收入、哪些小部件最畅销以及简要的趋势说明。具体措辞因模型运行而异。在 LangSmith 中打开该运行记录，在智能体回复之前，观察它使用文件系统工具（read_file，以及如果它在沙箱中运行 Python 时使用的 execute）。

添加上下文管理

在第 2 步之后，每个工具结果都会保留在消息历史中。一个真实的分析会话（多个绘图、失败的脚本、大量的 read_file 输出）会很快填满上下文窗口。当历史记录变得过大时，SummarizationMiddleware 会压缩较早的轮次，这样智能体就能继续工作，而无需你手动修剪消息。这在第一个 sales.csv 问题上影响不大，但在后续问题（如“现在按产品细分并绘制月度趋势图”）中更为重要。通过在中间件列表中添加 SummarizationMiddleware 来更新你的第 2 步智能体：

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="google_genai:gemini-3.6-flash"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="openai:gpt-5.5"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="anthropic:claude-sonnet-4-6"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="openrouter:z-ai/glm-5.2"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="fireworks:accounts/fireworks/models/glm-5p2"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="baseten:zai-org/GLM-5.2"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

from deepagents.middleware import FilesystemMiddleware, SummarizationMiddleware

model="ollama:north-mini-code-1.0"

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
    ],
)

运行一个多轮会话来观察摘要功能的实际效果。在初始分析之后，提出会触发更多文件读取或脚本运行的后续问题。在 LangSmith 中，在后续的模型调用之前查找摘要步骤。更多信息，请参阅上下文工程。

添加技能

技能提供了一种在需要时通过渐进式披露向智能体提供按需领域知识的方式。技能可以包含多步骤工作流、规则和约定。通过将这些信息放在技能中，它默认不会添加到系统提示中，这确保了只有当任务需要该技能的信息时，才会使用相应的标记（tokens）。当智能体启动时，它只看到关于每个技能的轻量级元信息。当任务需要某个技能时，智能体会按需加载完整的技能文件。在 skills 目录下创建一个技能文件：

skills/
  pandas-patterns/
    SKILL.md

---
name: pandas-patterns
description: 用于数据分析和可视化的常见 pandas 和 matplotlib 模式
---

## 数据加载
对 CSV 文件使用 `pd.read_csv()`。务必先检查 `df.info()` 和 `df.describe()`。

## 可视化
柱状图使用 `matplotlib`，统计图使用 `seaborn`。
使用 `plt.savefig("output.png", dpi=150, bbox_inches="tight")` 保存图表。

## 报告
在生成图表的同时，将 markdown 格式的摘要写入 `report.md`。

此技能包含了关于如何进行可视化的信息。使用 LangSmithSandbox 时，技能路径解析在沙箱文件系统上，而不是你的本地机器。在配置 SkillsMiddleware 之前，先上传你本地的 skills/ 目录：

from pathlib import Path

# 确定技能目录的路径
skills_dir = (Path(__file__).resolve().parent / "skills").resolve()
skill_files: list[tuple[str, bytes]] = []
# 遍历目录下所有文件并排序
for path in sorted(skills_dir.rglob("*")):
    # 跳过非文件项
    if not path.is_file():
        continue
    # 计算相对路径
    rel = path.resolve().relative_to(skills_dir)
    # 将文件路径和内容作为元组添加到列表中
    skill_files.append((f"/skills/{rel.as_posix()}", path.read_bytes()))
# 上传所有技能文件
backend.upload_files(skill_files)

然后，通过添加 SkillsMiddleware 来创建带有你技能的智能体：

from deepagents.middleware import FilesystemMiddleware, SkillsMiddleware, SummarizationMiddleware

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
        SkillsMiddleware(backend=backend, sources=["/skills/"]),
    ],
)

你可以尝试一个提示，如“使用我们的 pandas 模式分析 sales.csv”。当需要绘图或报告指导时，智能体会加载该技能。如果你问一个不需要该技能的不同问题，智能体将不会加载它。

添加可视化子智能体

某些任务会产生大量中间输出（脚本草稿、失败的运行、文件读取），如果保留在同一线程中，会挤占主智能体的上下文。一个子智能体在自己的上下文窗口中运行，因此监督者只看到最终结果，而不是沿途的每一个工具调用。这使得主分析保持专注，并为后续问题留出空间。使用子智能体的一个合理场景是图表生成。绘图通常意味着在图表准备好之前，需要在 Python 脚本上迭代、安装包和读取错误输出。下面的 visualizer 子智能体可以独立处理这项工作，同时主智能体继续规划和分析。使用 TodoListMiddleware，主智能体还可以并行委托图表工作，而不是在每个绘图上阻塞。通过添加 TodoListMiddleware 和 SubAgentMiddleware 来更新你的第 4 步智能体：

from deepagents import SubAgent
from deepagents.middleware import (
    FilesystemMiddleware,
    SkillsMiddleware,
    SubAgentMiddleware,
    SummarizationMiddleware,
)
from langchain.agents.middleware import TodoListMiddleware

visualizer: SubAgent = {
    "name": "visualizer",
    "description": "根据沙箱中的数据文件生成图表和可视化。",
    "system_prompt": "你是一名数据可视化专家。请使用 matplotlib 和 seaborn 编写 Python 脚本。将所有图表保存为 PNG 文件。",
    "tools": [],
    "model": "anthropic:claude-sonnet-4-6",
}

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        FilesystemMiddleware(backend=backend),
        SummarizationMiddleware(model=model, backend=backend),
        SkillsMiddleware(backend=backend, sources=["/skills/"]),
        TodoListMiddleware(),
        SubAgentMiddleware(backend=backend, subagents=[visualizer]),
    ],
)

尝试一个提示，如“分析 sales.csv，然后创建一个按产品划分收入的柱状图”。主智能体处理分析和规划，并通过 task 工具将图表生成委托给 visualizer 子智能体。如果你在设置中启用了跟踪功能，请在 LangSmith 中打开该运行记录。你应该会看到一个对 visualizer 的 task 调用，一个带有自己工具循环的独立子运行，以及一个返回给监督者的简短结果。

你构建了什么

你使用以下中间件构建了一个定制的智能体：

中间件	它添加的功能
`FilesystemMiddleware` + `LangSmithSandbox`	隔离的文件系统 + `execute` 工具
`SummarizationMiddleware`	自动上下文压缩
`SkillsMiddleware`	按需加载的领域知识
`TodoListMiddleware` + `SubAgentMiddleware`	并行的可视化子智能体

这与 create_deep_agent 的基础相同：手动组装，因此你可以精确控制包含的内容。可能性远不止于此：查看预构建中间件了解所有可组合功能的完整列表，以及 create_agent 参考了解所有配置选项。要使用预组装版本，请参阅定制 Deep Agent。要查看使用 create_deep_agent 的完整数据分析示例，请参阅数据分析。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tutorials

Conceptual overviews

Additional resources

从零开始构建数据分析智能体

你将学到什么

设置

构建智能体

创建最小智能体

添加沙箱后端

添加上下文管理

添加技能

添加可视化子智能体

你构建了什么

​你将学到什么

​设置

​构建智能体

​创建最小智能体

​添加沙箱后端

​添加上下文管理

​添加技能

​添加可视化子智能体

​你构建了什么

你将学到什么

设置

构建智能体

创建最小智能体

添加沙箱后端

添加上下文管理

添加技能

添加可视化子智能体

你构建了什么