2026-06-13-deep-agents-framework-guide

Deep Agents 框架：从入门到精通

LangChain 团队开源的 Agent Harness（智能体脚手架），基于 LangGraph 构建，开箱即用提供任务规划、虚拟文件系统、子智能体派发、长期记忆四大核心能力，专为复杂多步骤 Agent 任务设计。

基本信息

• 来源类型：网页文章
• 原文位置：raw/articles/2026-06-13-114141-tg-46c83c.md
• 原文 URL：https://juejin.cn/post/7626988865536507944
• 消化日期：2026-06-13

核心观点

1. Agent Harness 定位：Deep Agents 不是又一个 Agent 框架，而是在 LangChain + LangGraph 之上的一层”整车”抽象。LangGraph 是发动机（图编排执行），LangChain 是方向盘（组件库），Deep Agents 是开箱即用的越野车——开发者只需告诉它去哪，它自己规划路线、加油、绕路。

2. 虚拟文件系统是杀手级特性：传统 Agent 的致命问题是上下文窗口溢出。Deep Agents 内置 ls/read_file/write_file/edit_file 四个文件工具，Agent 可以把搜索结果等中间产物”卸载”到虚拟文件中，主上下文保持干净。底层由 FilesystemMiddleware 实现。

3. write_todos 自动任务规划：内置 TodoListMiddleware，Agent 面对复杂任务会自动调用 write_todos 拆解为 Todo List，逐步执行并动态更新进度。比传统的 ReAct 循环多了”计划-执行-检查”的结构化维度。

4. 子智能体派发实现上下文隔离：通过 task 工具和 SubAgentMiddleware，主 Agent 可以动态生成子智能体处理专项任务。子智能体有独立上下文窗口不会污染主 Agent，且支持并行执行。还可以用 CompiledSubAgent 包装预构建的 LangGraph 图作为子智能体。

5. 零配置即可启动：create_deep_agent() 一行代码即可获得具备规划、文件管理、子智能体派发能力的完整 Agent。支持通过 tools、system_prompt、middleware 参数自定义扩展。

实操内容保留

代码/配置

# 安装
pip install deepagents
# 或 uv（推荐）
uv add deepagents
 
# API Key
export ANTHROPIC_API_KEY="your-api-key"
# 或
export OPENAI_API_KEY="your-api-key"

# 最简示例（零配置）
from deepagents import create_deep_agent
 
agent = create_deep_agent()
 
result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 LangGraph 并写一份总结"}]
})
 
print(result["messages"][-1].content)

# 带自定义工具的示例
from deepagents import create_deep_agent
 
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    return f"{city} 今天天气晴朗，气温 25°C。"
 
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="你是一个友好的助手，擅长天气查询。"
)
 
result = agent.invoke({
    "messages": [{"role": "user", "content": "北京天气怎么样？"}]
})

# 研究助手（完整示例）
import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
 
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """在互联网上搜索信息"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
 
research_instructions = """你是一位专业研究员。你的工作是进行深入研究并撰写高质量报告。
 
你可以使用互联网搜索工具作为主要信息来源。
 
## `internet_search`
使用此工具运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否包含原始内容。
"""
 
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions
)
 
result = agent.invoke({
    "messages": [{"role": "user", "content": "什么是 LangGraph？它解决了什么问题？"}]
})
 
print(result["messages"][-1].content)

# 自定义中间件（任务规划）
from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware
 
agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        TodoListMiddleware(
            system_prompt="在处理复杂任务前，先用 write_todos 制定计划..."
        ),
    ],
)

# 子智能体配置
from langchain.tools import tool
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware
 
@tool
def get_weather(city: str) -> str:
    """获取城市天气"""
    return f"{city} 天气晴朗，25°C"
 
agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-5-20250929",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "这个子智能体可以查询城市天气。",
                    "system_prompt": "使用 get_weather 工具获取天气信息。",
                    "tools": [get_weather],
                    "model": "gpt-4o",
                    "middleware": [],
                }
            ],
        )
    ],
)

Prompt 模板

研究助手系统提示词示例：

你是一位专业研究员。你的工作是进行深入研究并撰写高质量报告。 你可以使用互联网搜索工具作为主要信息来源。

internet_search

使用此工具运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否包含原始内容。

操作步骤

1. 安装依赖：pip install deepagents tavily-python
2. 配置 API Key（ANTHROPIC_API_KEY 或 OPENAI_API_KEY）
3. 定义自定义工具（可选）：用 @tool 装饰器或普通函数
4. 创建 Agent：create_deep_agent(tools=[...], system_prompt="...")
5. 调用：agent.invoke({"messages": [{"role": "user", "content": "任务描述"}]})

关键概念

• LangGraph — Deep Agents 的执行引擎，提供图编排、状态管理、断点续跑
• LangChain — Deep Agents 的组件库，提供 Tool、Prompt、Memory 等抽象
• AI Agent 智能体 — Deep Agents 属于 Agent Harness 子类，比通用 Agent 框架更开箱即用
• Agent Harness — 智能体脚手架，在框架之上提供规划/文件/子智能体/记忆的即用层
• Agentic Workflow — Deep Agents 的 write_todos 是 Agentic Workflow 的结构化实现
• 子智能体（Sub-Agent） — 通过 task 工具派发，上下文隔离 + 并行执行

与其他素材的关联

• 与 2026-06-13-langchain-openai-agent-tutorial 互补：LangChain 教程讲从零搭建基础 Agent，本文讲在此基础上的高级脚手架
• 与 2026-06-10-agent-engineering-guide 呼应：Agent 工程化指南讲为什么大部分团队做无用功，Deep Agents 提供了开箱即用的解决方案
• 与 2026-06-03-hermes-agent-setup-guide 互补：Hermes 侧重五支柱架构+Telegram 移动办公，Deep Agents 侧重底层 Agent 框架能力

原文精彩摘录

与普通 Agent 框架的本质区别：普通框架给你积木让你自己搭，Deep Agents 直接给你一辆配置齐全的越野车——你只需告诉它去哪，它自己会规划路线、加油、绕路。

杀手级特性——虚拟文件系统：传统 Agent 的致命问题是上下文窗口溢出——工具返回结果太长，很快就把 token 用完了。Deep Agents 的解决方案：内置虚拟文件系统，Agent 可以把中间结果”卸载”到文件中。调用搜索工具返回大量结果后，使用 write_file 保存到文件，后续需要时用 read_file 读取，主上下文保持干净。

相关页面

• Deep Agents
• LangGraph
• LangChain
• AI Agent 智能体
• AI编程开发