LangChain + DeepResearch 实战 ：从 0 到 1 构建深度研究智能体（附源码）

DeepSeek-v3.2 + LangChain DeepResearch 开发实战

随着 Manus、Claude Code 以及 Deep Research 等应用的爆火，其背后的核心技术------深层代理（Deep Agents） 正在成为 AI 领域的新焦点。

LangChain 官方推出的 DeepAgents 框架，为开发者复现 Deep Research 类体验提供了标准化基础设施，可用于构建复杂、长时程任务的智能体。

同时 LangChain 官方博客也发布了题为《Doubling down on deepagents》的重磅文章

论文地址：> 论文地址：https://arxiv.org/pdf/2510.21618

本文深度拆解 DeepAgents 架构，并基于 DeepSeek-v3.2 + LangChain DeepAgents，实战打造具备自主规划、文件管理与联网搜索能力的"数字员工"。

---

一、DeepAgents 是什么？核心架构解析

DeepAgents 的核心定位是：用于构建能够处理复杂、多步骤任务的智能体框架。

它不仅仅是一个对话机器人，而是一个能够操作物理世界数据、具有持久化生命周期的"数字员工"。其核心架构基于 LangGraph 构建，集成了以下四大关键机制：

1. 规划工具（Todo 清单）：红色部分。引导代理在行动前生成任务清单，帮助代理拆解大型任务，防止遗忘步骤。
2. 文件系统集成 ：绿色部分。内置虚拟文件系统（支持映射到本地磁盘），代理可以使用 ls, read_file, write_file 等工具管理"工作记忆"，实现跨步骤的持久化。
3. 子代理（Sub-Agents）：橙色部分。支持将特定任务（如深度搜索、数据分析）委派给隔离上下文的子代理，实现职责分离与并行处理。
4. 详细系统提示词：蓝色部分。内置借鉴 Claude Code 的长提示模板，包含详细的工具使用说明和思维链引导。

DeepAgents vs LangChain vs LangGraph

三者的关系如下表所示：

平台组件	角色定位	侧重场景与特点
LangGraph	智能体运行时	提供底层执行框架，将逻辑表示为有状态图，适合编排复杂工作流。
LangChain	智能体开发框架	提供核心循环机制和工具接口，适合自定义提示词和工具的灵活开发。
DeepAgents	智能体工具套件	预设了规划、文件系统等高级能力的骨架，适合快速构建更自主的深度代理。

---

二、环境准备与 DeepSeek-v3.2 接入

加入👉 赋范空间 ：免费领取本项目完整代码及教程，获取 DeepAgents 最佳实践指南。

在构建 Deep Agent 之前，我们需要先配置好环境并接入 DeepSeek-v3.2 模型。

1. 安装 DeepAgents 及依赖

# 安装核心库
pip install -U deepagents openai python-dotenv langchain-community langchain-experimental langchain-tavily pandas rich

2. 获取 API Key

前往 DeepSeek 开放平台：https://platform.deepseek.com/api_keys 申请 API Key。DeepSeek 的 API 完全兼容 OpenAI 格式，支持 Function Calling 和 JSON Output。

前往 tavily官网：https://www.tavily.com/注册并获得API-KEY（每月有免费额度）。用于联网搜索。

3. 配置环境变量

在项目根目录创建 .env 文件：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxx  

4. LangChain 接入模型

我们使用 LangChain 的 init_chat_model 统一接口来初始化 DeepSeek 模型。

import os
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

# 加载环境变量
load_dotenv(override=True)

deepseek_api_key = os.environ.get("DEEPSEEK_API_KEY")
deepseek_base_url = os.environ.get("DEEPSEEK_BASE_URL")

# 初始化 DeepSeek 模型
model = init_chat_model(
    api_key=deepseek_api_key,
    base_url=deepseek_base_url,
    model_provider="deepseek",
    model="deepseek-chat"
)

# 测试模型调用
print("测试 DeepSeek 模型连接...")
result = model.invoke("你好，请用一句话介绍DeepSeek-v3.2。")
print(f"DeepSeek 回复: {result.content}")

---

三、构建实战：打造实时联网深度研究 Agent

接下来，我们将结合 DeepAgents 框架 、DeepSeek-v3.2 模型 以及 Tavily 搜索工具，构建一个能够自主进行互联网信息收集并撰写报告的智能体。

1. 接入 Tavily 联网搜索工具

Tavily 是专为 AI Agent 设计的搜索引擎，支持返回结构化的搜索结果。

from tavily import TavilyClient
from typing import Literal

# 初始化 Tavily 客户端
tavily_key = os.environ.get("TAVILY_API_KEY")
tavily_client = TavilyClient(api_key=tavily_key)

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """
    运行网络搜索
    
    这是一个用于网络搜索的工具函数，封装了 Tavily 的搜索功能。
    
    参数说明：
    - query: 搜索查询字符串
    - max_results: 最大返回结果数量，默认为 5
    - topic: 搜索主题类型
    - include_raw_content: 是否包含原始网页内容
    """
    try:
        result = tavily_client.search(
            query,
            max_results=max_results,
            include_raw_content=include_raw_content,
            topic=topic,
        )
        return result
    except Exception as e:
        return {"error": f"搜索失败: {str(e)}"}

# 测试搜索工具
print("搜索工具测试中...")
test_res = internet_search("DeepSeek-v3.2 特性", max_results=1)
print(f"搜索结果示例: {test_res['results'][0]['title']}")

2. 定义 System Prompt（数字员工手册）

我们需要为 Agent 定义一套行为准则，类似于员工入职手册。

# 系统提示词：指导智能体成为专家研究员
research_instructions = """
您是一位资深的研究人员。您的工作是进行深入的研究，然后撰写一份精美的报告。

您可以通过互联网搜索引擎作为主要的信息收集工具。

## `互联网搜索`

使用此功能针对给定的查询进行互联网搜索。您可以指定要返回的最大结果数量、主题以及是否包含原始内容。

在进行研究时：
1. 首先将研究任务分解为清晰的步骤（使用 write_todos 工具）
2. 使用互联网搜索来收集全面的信息
3. 如果内容太大，将重要发现保存到文件中（使用 write_file 工具）
4. 将信息整合成一份结构清晰的报告
5. 务必引用你的资料来源
"""

3. 使用 create_deep_agent 构建智能体

这是最关键的一步。create_deep_agent 会自动装配规划器、文件系统中间件和我们传入的工具。

from deepagents import create_deep_agent

# 创建 Deep Agent
agent = create_deep_agent(
    model=model,                           # 使用 DeepSeek 模型
    tools=[internet_search],               # 传入我们定义的搜索工具
    system_prompt=research_instructions    # 传入系统提示词
)

print("Deep Agent 创建成功！开始执行任务...")

4. 运行智能体

现在，我们可以给它下达一个复杂的任务，观察它如何自动规划、搜索并生成结果。

query = "请帮我介绍一下DeepSeek-v3.2 最新模型的特性，并对比它与 DeepSeek-V2 的区别。注意：请用中文回答！"

# 执行 Agent
# 注意：DeepAgents 基于 LangGraph，因此 invoke 的输入是 messages 列表
result = agent.invoke({
    "messages": [
        {"role": "user", "content": query}
    ]
})

# 打印最后的消息内容
print("\n=== 最终回答 ===\n")
print(result["messages"][-1].content)

---

👉 欢迎加入 赋范空间 ：免费领取本项目完整代码 及教程，获取 DeepAgents 最佳实践指南。

🔥 更多实战课程 ：我们还有数据分析 Agent、多模态 RAG、企业级知识库构建等进阶课程等你来拿！

🤝 技术交流：与千名开发者共同探讨 AI 落地场景，解决开发中的疑难杂症。

四、DeepAgents 可视化与调试

在前面的实战中，我们只能看到 Agent 的最终输出。在实际开发中，我们需要观察 Agent 的"思考过程"和执行流。本节将介绍三种可视化与调试方法。

1. 使用 LangGraph Studio 进行可视化

DeepAgents 底层基于 LangGraph，因此可以使用 LangGraph Studio 进行可视化调试。

环境配置步骤：

1. 安装 LangGraph CLI：

   pip install -U "langgraph-cli[inmem]"

2. 创建 langgraph.json 配置文件 ：

   在项目根目录下创建 langgraph.json：

   {
     "dependencies": ["./"],
     "graphs": {
       "agent": "./agent.py:agent"
     },
     "env": ".env"
   }

3. 创建 agent.py ：

   将之前的 Agent 构建代码保存为 agent.py，并确保暴露出 agent 变量。

4. 启动服务：

   langgraph dev

   启动后，打开浏览器访问显示的 Studio UI 地址，即可看到 Agent 的状态图和执行轨迹。

2. Deep Agents UI：专为深度代理设计的界面

LangChain 官方提供了专门的 Deep Agents UI，支持文件系统可视化。

安装与启动：

# 克隆仓库
git clone https://github.com/langchain-ai/deep-agents-ui.git
cd deep-agents-ui

# 安装依赖并启动
npm install
npm run dev

3. 【进阶】代码级实时调试（Rich 美化输出）

如果你更习惯在代码中调试，可以使用 agent.stream() 方法配合 rich 库，实时打印 Agent 的思考过程和工具调用。

import json
from rich.console import Console
from rich.panel import Panel
from rich.json import JSON

console = Console()

def debug_agent(query: str):
    """
    运行智能体并打印中间过程（使用 Rich 美化输出）
    """
    console.print(Panel.fit(f"[bold cyan]查询:[/bold cyan] {query}", border_style="cyan"))
    
    step_num = 0
    
    # 使用 stream 方法获取流式事件
    for event in agent.stream(
        {"messages": [{"role": "user", "content": query}]},
        stream_mode="values"
    ):
        step_num += 1
        console.print(f"\n[bold yellow]步骤 {step_num}[/bold yellow]")
        
        if "messages" in event:
            msg = event["messages"][-1]
            
            # 打印 AI 思考
            if hasattr(msg, 'content') and msg.content:
                console.print(Panel(msg.content, title="[bold green]AI 思考[/bold green]", border_style="green"))
            
            # 打印工具调用
            if hasattr(msg, 'tool_calls') and msg.tool_calls:
                for tool_call in msg.tool_calls:
                    tool_info = {"工具": tool_call.get('name'), "参数": tool_call.get('args')}
                    console.print(Panel(JSON(json.dumps(tool_info)), title="[bold blue]工具调用[/bold blue]", border_style="blue"))

# 运行调试
debug_agent("详细调研 LangChain DeepAgents 框架的核心特性")

---

总结

通过上述步骤，我们成功构建了一个具备以下能力的深度代理：

1. 自主规划：能够将"介绍模型特性"这样的大任务拆解为"搜索特性"、"搜索区别"、"整理报告"等子任务。
2. 联网能力：通过 Tavily 实时获取 DeepSeek-v3.2 的最新信息，克服了大模型的知识截止问题。
3. 深度思考：结合 DeepSeek-v3.2 强大的推理能力，能够对检索到的信息进行逻辑整合而非简单拼接。
4. 可视化调试：掌握了 LangGraph Studio、Deep Agents UI 和代码级调试三种方法，让 Agent 的"黑盒"变得透明。

DeepAgents 的出现，让构建复杂的 Agentic Workflow 变得前所未有的简单。结合国产高性价比模型 DeepSeek，开发者可以以极低的成本探索 AI Agent 的无限可能。

参考资料

• DeepAgents GitHub 仓库：https://github.com/langchain-ai/deepagents
• DeepSeek 开放平台：https://platform.deepseek.com/
• LangChain 官方文档：https://python.langchain.com/

---