【DeepAgent】概述

文档链接：

https://docs.langchain.com/oss/python/deepagents/overview

Deep Agents 核心定义

Deep Agents 是构建 LLM 智能体最简单的方式，专门用来做复杂多步任务，自带四大核心能力：

任务规划

虚拟文件系统管理上下文

生成子代理

长期记忆

1. 技术定位：Agent Harness（智能体脚手架）

agent harness：智能体脚手架 / 封装层，不是从零造轮子

核心逻辑和其他 Agent 框架一致（工具调用循环），但提前封装好了所有常用工具和能力，不用自己手写

2.底层技术栈（关键！）

这是三者的核心关系，彻底理清：

底层核心：LangChain（提供 Agent 基础组件，比如工具、提示词、LLM 调用）

运行时引擎：LangGraph（负责持久化执行、流式输出、人机交互、状态管理）

上层封装：Deep Agents（基于前两者，做成开箱即用的独立库，pip 直接装）

3. 库包含内容

复制代码

The `deepagents` library contains:
- Deep Agents SDK：构建智能体的核心包
- Deep Agents CLI：基于SDK做的终端代码智能体

SDK：写 Python 代码自定义 Agent

CLI：直接在终端用命令行调用 Agent，不用写代码

快速上手：创建第一个 Deep Agent（代码逐行讲解）

开始之前，请确保您已从模型提供商（例如 Anthropic、OpenAI）处获得 API 密钥。

见文档：https://docs.langchain.com/oss/python/deepagents/quickstart#step-2-set-up-your-api-keys

步骤 1：安装依赖项：

复制代码

pip install deepagents tavily-python

步骤 2：设置您的 API 密钥（选择不同的api厂家）

Anthropic：

复制代码

export ANTHROPIC_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"```

OpenAI：

复制代码

export OPENAI_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Google：

复制代码

export GOOGLE_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

OpenRouter：

复制代码

export GOOGLE_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Fireworks

复制代码

export FIREWORKS_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Baseten：

复制代码

export BASETEN_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Ollama：

复制代码

# Local: Ollama must be running (https://ollama.com)
# Cloud: Set your Ollama API key for hosted inference
export OLLAMA_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

安装命令

pip install -qU deepagents

复制代码

# 导入核心创建函数
from deepagents import create_deep_agent

# 自定义工具：获取天气
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

# 创建Deep Agent
agent = create_deep_agent(
    tools=[get_weather],  # 绑定自定义工具
    system_prompt="You are a helpful assistant",  # 系统提示词
)

# 运行Agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

逐行解读

安装：pip install -qU deepagents 一键安装独立库，无需单独配置 LangChain/LangGraph
导入：仅需一个 create_deep_agent 函数，就能创建 Agent，极简 API
自定义工具：写普通 Python 函数，加文档字符串，自动变成 Agent 可调用的工具
创建 Agent：只需传工具列表 + 系统提示词，无需配置状态、流程、循环
运行 Agent：invoke 传入用户消息，Agent 自动完成思考→调用工具→返回结果全流程

用 LangSmith 追踪、调试 Agent 行为

配置环境变量：LANGSMITH_TRACING=true + 你的 API Key，即可开启日志追踪

可能存在报错：

复制代码

Could not resolve authentication method. Expected either api_key or auth_token to be set.

翻译：Deep Agents 默认使用 Anthropic Claude 大模型，但你没有配置 Claude 的 API Key，模型无法调用，所以报错。

修改实例：使用本地ollama大模型

安装依赖：

复制代码

pip install langchain-ollama

查询本地ollama运行大模型的类型：

复制代码

ollama ps

NAME           ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3.5:27b    7653528ba5cb    44 GB    100% GPU     262144     Forever

需要复制name qwen3.5:27b

代码调整：

复制代码

# 加载.env中的LangSmith配置（可选，若不需要追踪可删除前3行）
from dotenv import load_dotenv
import os
load_dotenv()

# 导入Deep Agents核心函数
from deepagents import create_deep_agent

# 自定义工具：获取天气（和你之前的示例一致）
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

# 🔥 核心配置：创建Deep Agent，指定本地Ollama的qwen3.5:27b模型
agent = create_deep_agent(
    model="ollama:qwen3.5:27b",  # 严格匹配ollama ps中的模型名，格式ollama:模型名
    tools=[get_weather],         # 绑定自定义工具
    system_prompt="You are a helpful assistant, use the get_weather tool to answer weather questions.",  # 引导模型调用工具
)

# 运行Agent，测试qwen3.5:27b调用工具
result = agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

# 打印结果
print("=== Deep Agents 运行结果 ===")
print(result["messages"][-1].content)

适用场景：什么时候用 Deep Agents？

1. Deep Agents SDK 适用场景

需要构建具备以下能力的 Agent 时，用 Deep Agents：

复杂多步任务：需要规划、拆解任务（比如写代码、做项目、数据分析）
海量上下文管理：通过文件系统避免上下文窗口溢出
可切换文件系统后端：内存、本地磁盘、持久化存储、沙箱、自定义后端
任务委派：生成子代理，隔离上下文，主代理专注统筹
跨会话持久记忆：不同对话线程间保留记忆

2. 不适合用 Deep Agents 的场景

简单 Agent：直接用LangChain 原生 create_agent

高度定制化、复杂工作流：用LangGraph自己编排

3. Deep Agents CLI 适用场景

终端场景下的代码智能体：

交互式 / 非交互式使用

自定义技能、记忆

让 Agent 学习你的项目规范、偏好

在本地 / 沙箱执行代码

核心能力（五大核心特性，官方卡片总结）

这是 Deep Agents 区别于普通 LangChain Agent 的核心优势，也是它能处理复杂任务的关键：

1. 任务规划与拆解（Planning and task decomposition）

内置 write_todos 工具

Agent 自动把复杂任务拆分成离散步骤，跟踪进度，动态调整计划

解决复杂任务不知道先做什么的问题

2. 上下文管理（Context management）

内置文件系统工具：ls/read_file/write_file/edit_file

把大上下文存到内存 / 文件系统，防止上下文窗口溢出

处理变长工具返回结果，不用手动截断

3. 可插拔文件系统后端（Pluggable filesystem backends）

虚拟文件系统支持切换后端：内存、本地磁盘、LangGraph 存储、沙箱（Modal/Daytona/Deno）

可自定义后端，适配不同部署场景（服务器、本地、云）

4. 子代理生成（Subagent spawning）

内置 task 工具，生成专业子代理

主代理上下文保持简洁，子代理专注处理细分任务，上下文隔离

适合多任务、多领域的复杂 Agent 系统

5. 长期记忆（Long-term memory）

基于 LangGraph Memory Store 实现跨会话持久记忆

Agent 能记住历史对话信息，不用每次重新输入上下文

入门学习路径（官方推荐学习顺序）

文档最后给出了 6 个核心学习入口，按新手优先级排序：

SDK Quickstart：构建第一个 Deep Agent（必看）

Customization：SDK 自定义配置

Backends：文件系统后端配置

Sandboxes：隔离环境执行代码

CLI：终端使用 Deep Agents

API Reference：API 官方参考文档

总结

对新手最友好：Deep Agents 是零门槛入门 Agent 开发的最优选择，不用理解 LangChain 组件、LangGraph 状态编排，一行函数创建 Agent

技术本质：是 LangChain+LangGraph 的高级封装，底层能力拉满，上层 API 极简

适合你的场景：你做 CV+Agent、复杂多步任务、需要上下文管理 / 子代理，用 Deep Agents 能快速落地，不用重复造轮子

进阶路径：先跑通 Deep Agents 示例 → 理解 LangChain 基础 → 再用 LangGraph 做深度定制