DeepAgent 完全教程:从零到精通构建智能体

DeepAgent 完全教程:从零到精通构建智能体

为什么有DeepAgent

想象一下这样的场景:

你是一名开发者,收到这样的需求:

• 构建一个能够自动调研行业趋势并生成报告的系统
• 创建一个可以分析代码库、修复bug、运行测试的全栈开发助手
• 开发一个能够跨多个数据源、处理复杂业务流程的自动化引擎

传统做法,你需要:

• 手动编写任务分解逻辑
• 自己管理上下文和状态
• 重复实现工具调用框架
• 花费数周时间搭建基础设施

使用DeepAgent,只需要:

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "调研LangGraph并生成500字总结"}]
})

DeepAgent是LangChain团队推出的革命性智能体开发框架,它通过内置的任务规划、文件系统管理、子代理生成和长期记忆等能力,让你能够用最少的代码构建最复杂的智能体应用。

本教程将带你从零开始,深度掌握DeepAgent的每一个细节,从基础概念到高级应用,从理论原理到实战落地。

---

目录

• [一、DeepAgent 核心概念](#一、DeepAgent 核心概念)
• 二、架构与原理
• 三、环境搭建
• 四、快速上手
• 五、核心功能详解
• 六、高级特性
• 七、实战案例
• 八、生产环境部署
• 九、性能优化
• 十、故障排除
• 十一、最佳实践

---

一、DeepAgent 核心概念

1.1 什么是DeepAgent?

DeepAgent是LangChain团队推出的开源智能体开发套件(Agent Harness),它是一个"开箱即用"的智能体构建器。

核心定位:

• 在LangChain生态中处于最上层
• 专为复杂、长运行、多步骤任务设计
• 旨在降低企业级智能体应用的开发与落地成本

1.2 与其他框架的对比

在LangChain生态中,三者形成清晰的分层架构:

层级	组件	核心定位	适用场景
最上层	DeepAgents	开箱即用的重型Agent构建器	深度调研、全栈代码生成、复杂工作流
中间层	LangChain	应用框架与组件库	快速原型、常规Agent/RAG应用
最底层	LangGraph	图编排运行时引擎	极致自定义、高可靠多智能体协作

核心差异:

传统Agent框架:

• 需要手动实现规划、上下文管理、子代理协作
• 开发者需要编写大量胶水代码
• 工具调用与推理过程相互割裂

DeepAgent:

• 内置规划、文件系统、子代理等能力
• 开发者只需关注业务逻辑
• 推理链与工具使用深度融合

1.3 四大核心能力

1.3.1 任务规划与分解

内置write_todos工具,能够:

• 自动将复杂任务拆解为离散子任务
• 支持动态调整计划与进度跟踪
• 适配多轮推理与自适应执行

示例:

用户输入: "研究LangGraph并生成报告"

自动规划:
1. 搜索LangGraph相关信息
2. 阅读官方文档
3. 提取核心特性
4. 整理关键要点
5. 撰写结构化报告

1.3.2 文件系统上下文管理

提供ls、read_file、write_file、edit_file、grep等工具:

• 将大上下文卸载到文件系统
• 避免token溢出
• 支持可变长度结果处理
• 可插拔后端:内存/本地磁盘/LangGraph Store/沙盒

可插拔后端:

• InMemoryBackend: 内存存储,适合测试
• FilesystemBackend: 本地磁盘,适合本地开发
• StoreBackend: LangGraph Store,支持跨线程持久化
• SandboxBackend: 隔离环境执行,适合生产环境
• CompositeBackend: 组合多个后端,灵活路由

1.3.3 子智能体(Subagent)生成

通过内置task工具:

• 主智能体可动态派生上下文隔离的专用子智能体
• 专注处理细分任务
• 避免主上下文污染
• 提升执行效率与专业性

应用场景:

主Agent: "分析这个项目"
  ├─ 子Agent1: "阅读代码文件"
  ├─ 子Agent2: "运行测试"
  └─ 子Agent3: "生成文档"

1.3.4 长期记忆与持久化

集成LangGraph Store:

• 支持跨会话/线程的持久化记忆
• 智能体可保存并复用历史对话信息
• 适配长周期任务与多轮交互

1.4 适用场景

✅ 适合使用DeepAgent:

• 🔍 深度调研: 自动多轮搜索、文档阅读、笔记整理,生成长篇行业报告
• 💻 全栈开发: 类似Claude Code,在沙盒中编写、运行、测试、重构代码库
• 📊 复杂数据分析: 自动生成SQL、执行查询、可视化分析,处理多源异构数据
• ⚙️ 自动化工作流: 跨系统任务编排、日志分析、运维自动化

❌ 不适合使用DeepAgent:

• 单步简单工具调用 → 用LangChain的create_agent
• 需要精细控制图结构 → 直接用LangGraph
• 任务简单到不需要规划 → 直接调用模型

---

二、架构与原理

2.1 核心架构

DeepAgent采用分层架构设计:

┌─────────────────────────────────────┐
│     应用层 (Application Layer)      │
│  - 业务逻辑                         │
│  - 自定义工具                       │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│    DeepAgent SDK 层 (Harness)       │
│  - create_deep_agent()             │
│  - 内置工具规划、文件系统、子代理    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│     LangChain 框架层 (Framework)   │
│  - Agent核心构建块                  │
│  - Tool定义与调用                   │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│    LangGraph 运行时层 (Runtime)     │
│  - 图编排引擎                       │
│  - 状态管理                         │
│  - 流式输出、检查点、HITL           │
└─────────────────────────────────────┘

2.2 执行流程

标准执行循环:

1. 用户输入 (User Input)
   ↓
2. 感知层 (Perception)
   - 理解用户意图
   - 上下文分析
   ↓
3. 规划层 (Planning)
   - 任务分解 (write_todos)
   - 动态调整计划
   ↓
4. 决策层 (Decision)
   - 判断是否需要调用工具
   - 选择合适的工具
   - 决定是否派生子代理
   ↓
5. 执行层 (Execution)
   - 工具调用
   - 子代理执行
   - 文件系统操作
   ↓
6. 反馈层 (Feedback)
   - 结果收集
   - 状态更新
   - 记忆持久化
   ↓
7. 循环判断 (Loop Check)
   - 是否需要继续?
   - 是 → 回到规划层
   - 否 → 输出结果

2.3 关键组件

2.3.1 状态管理 (State Management)

DeepAgent使用TypedDict定义状态:

from typing import TypedDict, Annotated, List
import operator

class AgentState(TypedDict):
    messages: Annotated[List[BaseMessage], operator.add]  # 消息历史
    tool_results: List[Dict[str, Any]]                     # 工具调用结果
    files: Dict[str, Any]                                  # 文件系统状态
    memory: Dict[str, Any]                                 # 长期记忆

2.3.2 中间件管道 (Middleware Pipeline)

DeepAgent使用中间件模式处理请求:

class AgentMiddleware:
    def before_tool_call(self, context: Context) -> Context:
        """工具调用前处理"""
        pass

    def after_tool_call(self, context: Context) -> Context:
        """工具调用后处理"""
        pass

    def before_subagent(self, context: Context) -> Context:
        """子代理生成前处理"""
        pass

    def after_subagent(self, context: Context) -> Context:
        """子代理生成后处理"""
        pass

2.3.3 后端系统 (Backend System)

文件系统后端接口:

class FilesystemBackend(ABC):
    @abstractmethod
    def read_file(self, path: str) -> str:
        """读取文件"""
        pass

    @abstractmethod
    def write_file(self, path: str, content: str):
        """写入文件"""
        pass

    @abstractmethod
    def list_files(self, path: str) -> List[str]:
        """列出文件"""
        pass

---

三、环境搭建

3.1 系统要求

组件	最低要求	推荐配置
Python	3.9+	3.10+
内存	8GB	16GB+
存储	20GB	50GB+ SSD
操作系统	macOS/Linux/Windows	Ubuntu 22.04 LTS

3.2 安装步骤

方式一: 使用pip安装

# 创建虚拟环境
python -m venv deepagent-env
source deepagent-env/bin/activate  # Linux/macOS
# 或
deepagent-env\Scripts\activate  # Windows

# 安装DeepAgents
pip install -qU deepagents

# 安装LangChain(如果需要自定义)
pip install -qU langchain langchain-core

方式二: 使用uv安装(推荐)

# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目并安装
uv init my-deepagent
cd my-deepagent
uv add deepagents

方式三: 使用Homebrew安装CLI

# 安装DeepAgents CLI
curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

# 验证安装
deepseek --version

3.3 配置API密钥

创建.env文件:

# .env
OPENAI_API_KEY=sk-your-openai-api-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
LANGCHAIN_TRACING=true
LANGCHAIN_API_KEY=your-langsmith-api-key

加载环境变量:

from dotenv import load_dotenv
import os

load_dotenv()

# 验证配置
api_key = os.getenv("OPENAI_API_KEY")
print(f"API Key configured: {bool(api_key)}")

3.4 验证安装

创建测试文件test_install.py:

from deepagents import create_deep_agent

def test_basic_agent():
    """测试基础Agent功能"""
    agent = create_deep_agent()
    result = agent.invoke({
        "messages": [{"role": "user", "content": "你好"}]
    })
    print("✅ 基础Agent测试通过")
    print(f"回复: {result['messages'][-1]['content']}")

if __name__ == "__main__":
    test_basic_agent()

运行测试:

python test_install.py

---

四、快速上手

4.1 第一个DeepAgent

创建first_agent.py:

from deepagents import create_deep_agent

# 创建基础Agent
agent = create_deep_agent()

# 执行简单任务
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "用Python写一个计算斐波那契数列的函数"}
    ]
})

# 输出结果
print(result["messages"][-1]["content"])

输出示例:

def fibonacci(n):
    """
    计算斐波那契数列的第n项
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fibonacci(n-1) + fibonacci(n-2)

# 使用示例
print(fibonacci(10))  # 输出: 55

4.2 添加自定义工具

创建custom_tools_agent.py:

from deepagents import create_deep_agent
from langchain_core.tools import tool
from typing import Dict, Any
import requests
import json

# 定义天气查询工具
@tool
def get_weather(city: str) -> str:
    """查询指定城市的天气"""
    # 这里使用模拟数据,实际应用中应调用真实天气API
    weather_data = {
        "北京": "晴天, 温度25°C",
        "上海": "多云, 温度28°C",
        "广州": "小雨, 温度30°C",
    }
    return weather_data.get(city, f"抱歉,没有{city}的天气数据")

# 定义新闻查询工具
@tool
def get_news(topic: str, limit: int = 5) -> str:
    """查询指定主题的新闻"""
    # 模拟新闻数据
    news_list = [
        f"{topic}相关新闻1: 最新研究表明...",
        f"{topic}相关新闻2: 行业动态更新...",
        f"{topic}相关新闻3: 专家观点分享...",
    ]
    return "\n".join(news_list[:limit])

# 创建带工具的Agent
agent = create_deep_agent(
    tools=[get_weather, get_news],
    system_prompt="你是一个智能助手,可以使用天气和新闻查询工具。"
)

# 测试
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "帮我查询北京的天气和AI相关的新闻"}
    ]
})

print(result["messages"][-1]["content"])

4.3 使用文件系统

创建filesystem_agent.py:

from deepagents import create_deep_agent
from langchain_community.tools import (
    ReadFileTool,
    WriteFileTool,
    EditFileTool,
)

# 创建带文件系统工具的Agent
agent = create_deep_agent(
    tools=[
        ReadFileTool(),
        WriteFileTool(),
        EditFileTool(),
    ],
    system_prompt="你是一个文件处理助手,可以读取、写入和编辑文件。"
)

# 测试文件操作
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "创建一个名为hello.txt的文件,写入'Hello, DeepAgent!'"
        }
    ]
})

print(result["messages"][-1]["content"])

# 读取文件
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "读取hello.txt的内容"}
    ]
})

print(result["messages"][-1]["content"])

4.4 子代理协作

创建subagent_agent.py:

from deepagents import create_deep_agent

# 创建主Agent
agent = create_deep_agent(
    system_prompt="你是一个任务协调员,可以将任务分配给不同的子代理。"
)

# 测试子代理协作
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": """
            我需要你完成以下任务:
            1. 研究Python的最新特性
            2. 分析JavaScript的发展趋势
            3. 生成一份对比报告

            请为每个子任务创建一个专门的子代理来处理。
            """
        }
    ]
})

print(result["messages"][-1]["content"])

---

五、核心功能详解

5.1 任务规划与分解

5.1.1 工作原理

DeepAgent使用write_todos工具进行任务规划:

from deepagents import create_deep_agent

agent = create_deep_agent()

# 复杂任务自动分解
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "帮我开发一个简单的Web爬虫,需要:"
            "1. 能够爬取网页内容"
            "2. 支持多线程"
            "3. 保存结果到数据库"
        }
    ]
})

自动生成的计划:

1. 设计爬虫架构
2. 实现网页请求模块
3. 实现内容解析模块
4. 实现多线程功能
5. 实现数据库存储模块
6. 编写测试用例
7. 生成使用文档

5.1.2 动态调整计划

# 在执行过程中根据结果调整计划
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "开发一个数据分析工具,但发现数据格式不符合预期,请调整计划"
        }
    ]
})

5.2 文件系统管理

5.2.1 基础文件操作

from deepagents import create_deep_agent
from langchain_community.tools import (
    ReadFileTool,
    WriteFileTool,
    EditFileTool,
    DeleteFileTool,
)

agent = create_deep_agent(
    tools=[
        ReadFileTool(),
        WriteFileTool(),
        EditFileTool(),
        DeleteFileTool(),
    ]
)

# 创建项目结构
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": """
            创建以下项目结构:
            my_project/
            ├── src/
            │   ├── main.py
            │   └── utils.py
            ├── tests/
            │   └── test_main.py
            └── README.md

            并在README.md中写入项目描述。
            """
        }
    ]
})

5.2.2 高级文件操作

from deepagents import create_deep_agent

agent = create_deep_agent()

# 批量处理文件
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": """
            将src目录下的所有.py文件中的:
            - print语句替换为logger.info
            - 添加类型注解
            - 优化导入语句
            """
        }
    ]
})

5.2.3 配置可插拔后端

使用内存后端:

from deepagents import create_deep_agent
from deepagents.filesystem import InMemoryBackend

backend = InMemoryBackend()
agent = create_deep_agent(backend=backend)

使用本地磁盘后端:

from deepagents import create_deep_agent
from deepagents.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="./workspace")
agent = create_deep_agent(backend=backend)

使用LangGraph Store后端:

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
agent = create_deep_agent(checkpointer=checkpointer)

5.3 子智能体系统

5.3.1 定义子智能体

from deepagents import create_deep_agent, CompiledSubAgent
from langchain_openai import ChatOpenAI

# 定义研究专家子智能体
researcher = CompiledSubAgent(
    model=ChatOpenAI(model="gpt-4"),
    tools=[search_tool, read_file_tool],
    system_prompt="你是一位研究专家,擅长信息收集和分析。",
    description="用于深度调研和信息收集任务"
)

# 定义代码专家子智能体
coder = CompiledSubAgent(
    model=ChatOpenAI(model="gpt-4"),
    tools=[write_file_tool, edit_file_tool],
    system_prompt="你是一位编程专家,擅长代码编写和重构。",
    description="用于代码开发和重构任务"
)

# 创建主Agent
agent = create_deep_agent(
    subagents=[researcher, coder]
)

5.3.2 动态派发子智能体

result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": """
            我需要:
            1. 研究最新的机器学习框架
            2. 基于研究结果开发一个示例项目
            3. 编写测试用例

            请分配合适的子智能体处理每个任务。
            """
        }
    ]
})

5.4 长期记忆

5.4.1 配置记忆系统

from deepagents import create_deep_agent
from langgraph.checkpoint.sqlite import SqliteSaver

# 使用SQLite持久化
memory = SqliteSaver.from_conn_string("agent_memory.db")

agent = create_deep_agent(
    checkpointer=memory
)

# 使用thread_id维护会话
config = {"configurable": {"thread_id": "user-session-1"}}
result = agent.invoke(
    {"messages": [{"role": "user", "content": "我叫张三"}]},
    config=config
)

# 后续对话可以记住之前的信息
result = agent.invoke(
    {"messages": [{"role": "user", "content": "我叫什么名字?"}]},
    config=config
)
# Agent会回答: "你叫张三"

5.4.2 结构化记忆

from deepagents import create_deep_agent
from typing import TypedDict

class UserPreferences(TypedDict):
    name: str
    language: str
    experience: str

agent = create_deep_agent()

# 保存用户偏好
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": """
            我的偏好:
            - 名字: 张三
            - 编程语言: Python
            - 经验: 3年
            请记住这些信息。
            """
        }
    ],
    "user_preferences": {
        "name": "张三",
        "language": "Python",
        "experience": "3年"
    }
})

---

六、高级特性

6.1 人类在环(HITL)

6.1.1 基础审批机制

from deepagents import create_deep_agent

# 创建需要审批的Agent
agent = create_deep_agent(
    interrupt_on=[
        "file_write",  # 文件写入前需要审批
        "api_call",    # API调用前需要审批
        "subagent"     # 子代理创建前需要审批
    ]
)

# 执行任务
config = {"configurable": {"thread_id": "session-1"}}
result = agent.invoke(
    {"messages": [{"role": "user", "content": "创建一个新文件"}]},
    config=config
)

# 在执行到中断点时,需要人工介入
# 获取当前状态
state = agent.get_state(config)

# 决定是否继续
if should_approve():
    # 继续执行
    agent.update_state(config, {"approval": "approved"})
    result = agent.invoke(None, config=config)
else:
    # 拒绝或修改
    agent.update_state(config, {"approval": "rejected"})

6.1.2 交互式审批

from deepagents import create_deep_agent

agent = create_deep_agent()

def interactive_approval(state):
    """交互式审批函数"""
    print(f"待审批操作: {state['pending_operation']}")
    print(f"操作详情: {state['operation_details']}")

    choice = input("是否批准? (y/n/edit): ")

    if choice == "y":
        return {"approval": "approved"}
    elif choice == "n":
        return {"approval": "rejected"}
    elif choice == "edit":
        new_details = input("请输入修改后的详情: ")
        return {"approval": "edited", "new_details": new_details}

# 配置交互式审批
agent = create_deep_agent(
    interrupt_on=["file_write", "api_call"],
    approval_function=interactive_approval
)

6.2 流式输出

from deepagents import create_deep_agent

agent = create_deep_agent()

# 流式执行
config = {"configurable": {"thread_id": "session-1"}}
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "研究LangGraph并生成报告"}]},
    config=config
):
    print(chunk)

# 或者使用astream异步流式
async def async_stream():
    async for chunk in agent.astream(
        {"messages": [{"role": "user", "content": "研究LangGraph并生成报告"}]},
        config=config
    ):
        print(chunk)

# 运行异步流式
import asyncio
asyncio.run(async_stream())

6.3 错误处理与重试

from deepagents import create_deep_agent
from typing import Optional

agent = create_deep_agent()

def execute_with_retry(task: str, max_retries: int = 3) -> Optional[str]:
    """带重试的任务执行"""
    for attempt in range(max_retries):
        try:
            result = agent.invoke({
                "messages": [{"role": "user", "content": task}]
            })
            return result["messages"][-1]["content"]
        except Exception as e:
            print(f"尝试 {attempt + 1} 失败: {e}")
            if attempt == max_retries - 1:
                print("达到最大重试次数,放弃")
                return None
            # 等待后重试
            import time
            time.sleep(2 ** attempt)

# 使用重试机制
result = execute_with_retry("分析这个复杂的数据集")

6.4 并行执行

from deepagents import create_deep_agent
import asyncio

agent = create_deep_agent()

async def parallel_tasks():
    """并行执行多个任务"""
    tasks = [
        "研究Python特性",
        "研究JavaScript特性",
        "研究Go特性"
    ]

    # 并行执行
    results = await asyncio.gather(*[
        agent.ainvoke({"messages": [{"role": "user", "content": task}]})
        for task in tasks
    ])

    for i, result in enumerate(results):
        print(f"任务{i+1}结果: {result['messages'][-1]['content'][:100]}...")

# 运行并行任务
asyncio.run(parallel_tasks())

---

七、实战案例

7.1 案例1:智能研究助手

需求: 自动调研特定主题并生成结构化报告

from deepagents import create_deep_agent
from langchain_community.tools import (
    TavilySearchResults,
    ReadFileTool,
    WriteFileTool,
)

# 创建研究工具
search_tool = TavilySearchResults(
    max_results=10,
    search_depth="advanced",
    include_answer=True,
    include_raw_content=True
)

# 创建研究助手
research_assistant = create_deep_agent(
    tools=[
        search_tool,
        ReadFileTool(),
        WriteFileTool(),
    ],
    system_prompt="""
    你是一位专业的研究助手,擅长:
    1. 多轮搜索收集信息
    2. 分析和整理资料
    3. 生成结构化报告

    工作流程:
    - 首先制定研究计划
    - 执行搜索和信息收集
    - 将重要信息保存到文件
    - 基于收集的信息撰写报告
    """,
)

# 执行研究任务
def conduct_research(topic: str, output_file: str = "research_report.md"):
    """执行研究任务"""
    result = research_assistant.invoke({
        "messages": [
            {
                "role": "user",
                "content": f"""
                请研究以下主题: {topic}

                要求:
                1. 深入调研该主题的最新发展
                2. 收集至少10个可靠信息源
                3. 分析主要趋势和挑战
                4. 提供未来发展预测
                5. 生成结构化的Markdown报告,保存到{output_file}

                报告应包含:
                - 执行摘要
                - 背景介绍
                - 核心发现
                - 分析与讨论
                - 结论与建议
                - 参考资料
                """
            }
        ]
    })

    return result["messages"][-1]["content"]

# 使用示例
if __name__ == "__main__":
    topic = "人工智能在医疗领域的应用"
    report = conduct_research(topic)
    print("研究完成!")
    print(f"报告摘要: {report[:200]}...")

7.2 案例2:全栈代码开发助手

需求: 能够理解需求、编写代码、运行测试、修复bug的全栈开发助手

from deepagents import create_deep_agent
from langchain_community.tools import (
    WriteFileTool,
    EditFileTool,
    ReadFileTool,
)

# 创建代码开发助手
code_assistant = create_deep_agent(
    tools=[
        WriteFileTool(),
        EditFileTool(),
        ReadFileTool(),
    ],
    system_prompt="""
    你是一位全栈开发工程师,擅长:
    1. 理解和分析需求
    2. 设计系统架构
    3. 编写高质量代码
    4. 编写测试用例
    5. 修复bug和优化代码

    代码规范:
    - 使用类型注解
    - 编写清晰的文档字符串
    - 遵循PEP 8规范
    - 添加适当的错误处理
    """,
    backend="./project_workspace"
)

# 开发任务
def develop_feature(feature_description: str):
    """开发新功能"""
    result = code_assistant.invoke({
        "messages": [
            {
                "role": "user",
                "content": f"""
                请帮我开发以下功能: {feature_description}

                请按照以下步骤进行:
                1. 分析需求并设计系统架构
                2. 编写核心代码
                3. 编写测试用例
                4. 运行测试并修复问题
                5. 生成使用文档

                项目结构:
                src/
                ├── main.py
                ├── utils.py
                ├── models.py
                tests/
                ├── test_main.py
                ├── test_utils.py
                README.md
                """
            }
        ]
    })

    return result["messages"][-1]["content"]

# 使用示例
if __name__ == "__main__":
    feature = """
    创建一个简单的REST API,实现以下功能:
    - 用户注册和登录
    - 创建、读取、更新、删除(CRUD)用户信息
    - 使用JWT进行身份验证
    - 使用SQLite作为数据库
    - 提供API文档
    """

    result = develop_feature(feature)
    print("开发完成!")
    print(f"结果: {result[:300]}...")

7.3 案例3:数据分析助手

需求: 自动分析数据、生成可视化、提供洞察

from deepagents import create_deep_agent
from langchain_community.tools import (
    ReadFileTool,
    WriteFileTool,
)
import pandas as pd
import matplotlib.pyplot as plt

# 定义数据分析工具
def analyze_data(file_path: str, analysis_type: str = "descriptive"):
    """数据分析工具"""
    df = pd.read_csv(file_path)

    if analysis_type == "descriptive":
        return df.describe().to_string()
    elif analysis_type == "correlation":
        return df.corr().to_string()
    elif analysis_type == "visualize":
        plt.figure(figsize=(10, 6))
        df.hist()
        plt.savefig("visualization.png")
        return "可视化图表已保存到visualization.png"

# 创建数据分析助手
data_analyst = create_deep_agent(
    tools=[
        ReadFileTool(),
        WriteFileTool(),
        analyze_data,
    ],
    system_prompt="""
    你是一位数据分析师,擅长:
    1. 数据清洗和预处理
    2. 描述性统计分析
    3. 相关性分析
    4. 数据可视化
    5. 提供业务洞察

    分析流程:
    1. 读取和探索数据
    2. 数据清洗和预处理
    3. 执行统计分析
    4. 生成可视化图表
    5. 撰写分析报告
    """,
)

# 分析任务
def analyze_dataset(file_path: str, output_report: str = "analysis_report.md"):
    """分析数据集"""
    result = data_analyst.invoke({
        "messages": [
            {
                "role": "user",
                "content": f"""
                请分析数据集: {file_path}

                请完成以下分析:
                1. 数据概览(列名、数据类型、缺失值)
                2. 描述性统计分析
                3. 关键特征的相关性分析
                4. 异常值检测
                5. 数据可视化
                6. 业务洞察和建议

                请将完整的分析报告保存到: {output_report}
                """
            }
        ]
    })

    return result["messages"][-1]["content"]

# 使用示例
if __name__ == "__main__":
    # 创建示例数据
    import numpy as np

    data = {
        "age": np.random.randint(18, 65, 1000),
        "income": np.random.randint(20000, 150000, 1000),
        "experience": np.random.randint(0, 40, 1000),
        "score": np.random.randint(0, 100, 1000)
    }
    df = pd.DataFrame(data)
    df.to_csv("user_data.csv", index=False)

    # 执行分析
    report = analyze_dataset("user_data.csv")
    print("分析完成!")
    print(f"报告摘要: {report[:200]}...")

7.4 案例4:自动化运维助手

需求: 监控系统日志、分析错误、提供修复建议

from deepagents import create_deep_agent
from langchain_community.tools import (
    ReadFileTool,
    WriteFileTool,
)
import re
from datetime import datetime

# 定义日志分析工具
def analyze_log_file(file_path: str, error_type: str = "error"):
    """分析日志文件"""
    with open(file_path, 'r') as f:
        log_lines = f.readlines()

    # 过滤特定类型的日志
    if error_type == "error":
        pattern = r"ERROR"
    elif error_type == "warning":
        pattern = r"WARNING"
    else:
        pattern = r"INFO"

    filtered_logs = [
        line for line in log_lines
        if re.search(pattern, line)
    ]

    return f"找到{len(filtered_logs)}条{error_type}日志\n" + \
           "\n".join(filtered_logs[-10:])  # 返回最近10条

# 创建运维助手
ops_assistant = create_deep_agent(
    tools=[
        ReadFileTool(),
        WriteFileTool(),
        analyze_log_file,
    ],
    system_prompt="""
    你是一位运维工程师,擅长:
    1. 分析系统日志
    2. 识别和诊断问题
    3. 提供修复建议
    4. 生成运维报告

    分析流程:
    1. 读取日志文件
    2. 过滤错误和警告信息
    3. 分析错误模式和频率
    4. 提供问题诊断
    5. 给出修复建议
    """,
)

# 运维任务
def monitor_logs(log_file: str, report_file: str = "ops_report.md"):
    """监控日志"""
    result = ops_assistant.invoke({
        "messages": [
            {
                "role": "user",
                "content": f"""
                请分析日志文件: {log_file}

                请完成以下任务:
                1. 识别所有ERROR级别的日志
                2. 统计错误发生的频率和时间分布
                3. 分析错误模式和可能的原因
                4. 提供具体的修复建议
                5. 生成运维报告,保存到{report_file}

                报告格式:
                - 错误摘要
                - 详细分析
                - 修复建议
                - 预防措施
                """
            }
        ]
    })

    return result["messages"][-1]["content"]

# 使用示例
if __name__ == "__main__":
    # 创建示例日志文件
    log_content = """
    2026-04-17 10:00:00 INFO  Application started
    2026-04-17 10:00:01 INFO  Loading configuration...
    2026-04-17 10:00:02 INFO  Database connection established
    2026-04-17 10:00:03 ERROR Failed to connect to API server
    2026-04-17 10:00:04 WARNING API server timeout, retrying...
    2026-04-17 10:00:05 ERROR API server unreachable after 3 retries
    2026-04-17 10:00:06 INFO  Switching to backup server
    2026-04-17 10:00:07 INFO  Backup server connection successful
    2026-04-17 10:00:08 ERROR Database query timeout
    2026-04-17 10:00:09 WARNING Optimizing query...
    """

    with open("application.log", "w") as f:
        f.write(log_content)

    # 执行监控
    report = monitor_logs("application.log")
    print("监控完成!")
    print(f"报告摘要: {report[:200]}...")

---

八、生产环境部署

8.1 容器化部署

Dockerfile:

FROM python:3.10-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 设置环境变量
ENV PYTHONUNBUFFERED=1
ENV LANGCHAIN_TRACING=true

# 暴露端口
EXPOSE 8000

# 运行应用
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt:

deepagents==0.1.0
langchain==0.1.0
langchain-openai==0.0.1
fastapi==0.104.0
uvicorn==0.24.0
python-dotenv==1.0.0

docker-compose.yml:

version: '3.8'

services:
  deepagent-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - LANGCHAIN_TRACING=true
      - LANGCHAIN_API_KEY=${LANGCHAIN_API_KEY}
    volumes:
      - ./workspace:/app/workspace
      - ./logs:/app/logs
    restart: unless-stopped

8.2 FastAPI集成

main.py:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from deepagents import create_deep_agent
from typing import Optional
import os
from dotenv import load_dotenv

load_dotenv()

app = FastAPI(title="DeepAgent API")

# 创建全局Agent实例
agent = create_deep_agent(
    checkpointer=MemorySaver()
)

class AgentRequest(BaseModel):
    message: str
    thread_id: Optional[str] = "default"

class AgentResponse(BaseModel):
    response: str
    thread_id: str

@app.post("/agent/chat", response_model=AgentResponse)
async def chat(request: AgentRequest):
    """Agent聊天接口"""
    try:
        config = {"configurable": {"thread_id": request.thread_id}}

        result = agent.invoke({
            "messages": [{"role": "user", "content": request.message}]
        }, config=config)

        response = result["messages"][-1]["content"]

        return AgentResponse(
            response=response,
            thread_id=request.thread_id
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/agent/history/{thread_id}")
async def get_history(thread_id: str):
    """获取对话历史"""
    try:
        config = {"configurable": {"thread_id": thread_id}}
        state = agent.get_state(config)

        return {
            "messages": state.get("messages", []),
            "thread_id": thread_id
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.delete("/agent/reset/{thread_id}")
async def reset_thread(thread_id: str):
    """重置对话"""
    try:
        config = {"configurable": {"thread_id": thread_id}}
        agent.update_state(config, {"messages": []})

        return {"message": "Thread reset successfully"}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

8.3 监控与日志

配置LangChain Tracing:

from langchain.callbacks.tracers import LangChainTracer

# 启用追踪
tracer = LangChainTracer()

agent = create_deep_agent(
    callbacks=[tracer]
)

自定义日志记录:

import logging
from deepagents import create_deep_agent

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('agent.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger("DeepAgent")

agent = create_deep_agent()

# 在执行前后添加日志
logger.info("Starting agent execution")
result = agent.invoke({
    "messages": [{"role": "user", "content": "测试任务"}]
})
logger.info(f"Agent execution completed. Result length: {len(result['messages'][-1]['content'])}")

8.4 安全性考虑

工具权限控制:

from deepagents import create_deep_agent

# 定义安全的工具白名单
SAFE_TOOLS = [
    "read_file",
    "write_file",
    "search",
    # 不包括危险的工具如"execute_shell", "delete_file"
]

agent = create_deep_agent(
    tools=[tool for tool in all_tools if tool.name in SAFE_TOOLS]
)

输入验证:

from pydantic import BaseModel, validator

class SafeAgentRequest(BaseModel):
    message: str

    @validator('message')
    def validate_message(cls, v):
        # 检查是否包含恶意命令
        dangerous_patterns = [
            "rm -rf",
            "format c:",
            "drop table",
            "__import__('os')",
        ]

        for pattern in dangerous_patterns:
            if pattern in v.lower():
                raise ValueError(f"Message contains dangerous pattern: {pattern}")

        return v

---

九、性能优化

9.1 缓存策略

from deepagents import create_deep_agent
from langchain.cache import InMemoryCache
from langchain.globals import set_llm_cache

# 启用内存缓存
set_llm_cache(InMemoryCache())

agent = create_deep_agent()

# 相同的查询会从缓存返回
result1 = agent.invoke({
    "messages": [{"role": "user", "content": "什么是Python?"}]
})
result2 = agent.invoke({
    "messages": [{"role": "user", "content": "什么是Python?"}]
})
# result2会从缓存返回,速度更快

9.2 批量处理

from deepagents import create_deep_agent
import asyncio

agent = create_deep_agent()

async def batch_process(tasks: list):
    """批量处理任务"""
    results = await asyncio.gather(*[
        agent.ainvoke({"messages": [{"role": "user", "content": task}]})
        for task in tasks
    ])
    return results

# 使用批量处理
tasks = [
    "任务1: 分析数据A",
    "任务2: 分析数据B",
    "任务3: 分析数据C"
]

results = asyncio.run(batch_process(tasks))

9.3 资源限制

from deepagents import create_deep_agent

# 配置资源限制
agent = create_deep_agent(
    max_iterations=10,        # 最大迭代次数
    max_tool_calls=20,        # 最大工具调用次数
    max_execution_time=300,    # 最大执行时间(秒)
    max_file_size=1024*1024,   # 最大文件大小(字节)
)

9.4 模型选择优化

from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# 为不同任务选择不同的模型
simple_model = ChatOpenAI(model="gpt-3.5-turbo")  # 快速、便宜
complex_model = ChatOpenAI(model="gpt-4")       # 智能、准确

agent = create_deep_agent(
    model=simple_model,  # 默认使用快速模型
)

# 根据任务复杂度动态切换模型
def smart_execute(task: str):
    """智能执行任务"""
    if len(task) > 1000 or "复杂" in task:
        # 复杂任务使用GPT-4
        result = agent.invoke(
            {"messages": [{"role": "user", "content": task}]},
            config={"model": complex_model}
        )
    else:
        # 简单任务使用GPT-3.5
        result = agent.invoke({
            "messages": [{"role": "user", "content": task}]
        })

    return result

---

十、故障排除

10.1 常见问题

问题1: Agent无限循环

症状: Agent一直在执行,没有输出结果

解决方案:

from deepagents import create_deep_agent

# 设置执行限制
agent = create_deep_agent(
    max_iterations=5,        # 限制迭代次数
    max_execution_time=60,   # 限制执行时间(秒)
)

# 添加超时机制
import signal

def timeout_handler(signum, frame):
    raise TimeoutError("Agent execution timeout")

signal.signal(signal.SIGALRM, timeout_handler)
signal.alarm(60)  # 60秒超时

try:
    result = agent.invoke({
        "messages": [{"role": "user", "content": "任务"}]
    })
except TimeoutError:
    print("Agent执行超时")
finally:
    signal.alarm(0)

问题2: 工具调用失败

症状: Agent无法调用工具或工具返回错误

解决方案:

from deepagents import create_deep_agent
from langchain_core.tools import tool
import logging

# 添加详细的日志记录
logging.basicConfig(level=logging.DEBUG)

@tool
def safe_tool(input: str) -> str:
    """带错误处理的安全工具"""
    try:
        # 工具逻辑
        result = process_input(input)
        return result
    except Exception as e:
        logging.error(f"Tool error: {e}")
        return f"工具执行失败: {str(e)}"

agent = create_deep_agent(
    tools=[safe_tool]
)

问题3: 内存溢出

症状: Agent执行过程中内存占用过高

解决方案:

from deepagents import create_deep_agent
from deepagents.filesystem import FilesystemBackend

# 使用文件系统后端,避免内存堆积
backend = FilesystemBackend(root_dir="./temp")

agent = create_deep_agent(
    backend=backend,
    max_context_length=4096,  # 限制上下文长度
)

# 定期清理临时文件
import os
import shutil

def cleanup_temp_files():
    """清理临时文件"""
    temp_dir = "./temp"
    if os.path.exists(temp_dir):
        shutil.rmtree(temp_dir)
        os.makedirs(temp_dir)

10.2 调试技巧

10.2.1 可视化执行流程

from deepagents import create_deep_agent

agent = create_deep_agent()

# 获取图结构
graph = agent.get_graph()

# 导出为Mermaid图表
png_data = graph.draw_mermaid_png()
with open("agent_graph.png", "wb") as f:
    f.write(png_data)

print("执行流程图已保存到agent_graph.png")

10.2.2 详细日志记录

from deepagents import create_deep_agent
from langchain.callbacks import get_openai_callback

agent = create_deep_agent()

# 记录详细的调用信息
with get_openai_callback() as cb:
    result = agent.invoke({
        "messages": [{"role": "user", "content": "任务"}]
    })

    print(f"Total Tokens: {cb.total_tokens}")
    print(f"Total Cost: ${cb.total_cost}")
    print(f"Prompt Tokens: {cb.prompt_tokens}")
    print(f"Completion Tokens: {cb.completion_tokens}")

10.2.3 单步执行

from deepagents import create_deep_agent

agent = create_deep_agent()

# 流式执行,查看每个步骤
for step in agent.stream(
    {"messages": [{"role": "user", "content": "任务"}]}
):
    print(f"Step: {step}")
    input("按Enter继续...")

---

十一、最佳实践

11.1 提示词工程

11.1.1 系统提示词最佳实践

# 好的系统提示词
GOOD_SYSTEM_PROMPT = """
你是一位专业的[角色],擅长[技能]。

## 核心能力
1. [能力1的详细描述]
2. [能力2的详细描述]
3. [能力3的详细描述]

## 工作流程
对于每个任务,请遵循以下步骤:
1. [步骤1]
2. [步骤2]
3. [步骤3]

## 约束条件
- [约束1]
- [约束2]

## 输出格式
请按照以下格式输出:
- [格式说明1]
- [格式说明2]
"""

# 不好的系统提示词
BAD_SYSTEM_PROMPT = """
你是一个助手,帮我完成任务。
"""

11.1.2 上下文管理

# 上下文压缩
def compress_context(context: str, max_length: int = 1000):
    """压缩上下文"""
    if len(context) <= max_length:
        return context

    # 提取关键信息
    from langchain.text_splitter import RecursiveCharacterTextSplitter
    splitter = RecursiveCharacterTextSplitter(
        chunk_size=max_length,
        chunk_overlap=100
    )
    chunks = splitter.split_text(context)
    return chunks[0]

11.2 工具设计

11.2.1 工具命名规范

# 好的工具命名
@tool
def search_academic_papers(query: str, field: str = "computer_science") -> str:
    """搜索学术论文

    Args:
        query: 搜索关键词
        field: 学科领域(默认为计算机科学)

    Returns:
        论文列表和摘要
    """
    pass

# 不好的工具命名
@tool
def do_search(q: str) -> str:
    """搜索"""
    pass

11.2.2 工具组合

# 创建工具组
research_tools = [
    search_tool,
    read_file_tool,
    write_file_tool,
]

coding_tools = [
    read_file_tool,
    write_file_tool,
    edit_file_tool,
    execute_tool,
]

# 根据任务选择合适的工具组
def get_tools_for_task(task_type: str):
    """根据任务类型返回工具"""
    if task_type == "research":
        return research_tools
    elif task_type == "coding":
        return coding_tools
    else:
        return research_tools + coding_tools

11.3 测试策略

11.3.1 单元测试

import pytest
from deepagents import create_deep_agent

def test_basic_agent():
    """测试基础Agent功能"""
    agent = create_deep_agent()
    result = agent.invoke({
        "messages": [{"role": "user", "content": "1+1等于几?"}]
    })

    assert "2" in result["messages"][-1]["content"]

def test_tool_calling():
    """测试工具调用"""
    from langchain_core.tools import tool

    @tool
    def multiply(a: int, b: int) -> int:
        """乘法计算"""
        return a * b

    agent = create_deep_agent(tools=[multiply])
    result = agent.invoke({
        "messages": [{"role": "user", "content": "3 * 5等于几?"}]
    })

    assert "15" in result["messages"][-1]["content"]

11.3.2 集成测试

def test_research_workflow():
    """测试研究工作流"""
    agent = create_deep_agent(
        tools=[search_tool, write_file_tool]
    )

    result = agent.invoke({
        "messages": [{
            "role": "user",
            "content": "研究Python并生成报告"
        }]
    })

    # 验证报告文件已创建
    import os
    assert os.path.exists("research_report.md")

11.3.3 性能测试

import time

def test_performance():
    """性能测试"""
    agent = create_deep_agent()

    start_time = time.time()
    result = agent.invoke({
        "messages": [{"role": "user", "content": "简单任务"}]
    })
    execution_time = time.time() - start_time

    # 断言执行时间在合理范围内
    assert execution_time < 30, f"执行时间过长: {execution_time}秒"

11.4 安全实践

11.4.1 输入验证

from pydantic import BaseModel, validator
import re

class AgentInput(BaseModel):
    message: str

    @validator('message')
    def validate_message(cls, v):
        # 检查长度
        if len(v) > 10000:
            raise ValueError("消息过长")

        # 检查特殊字符
        if re.search(r'<script|javascript:', v, re.IGNORECASE):
            raise ValueError("包含潜在危险的脚本")

        # 检查SQL注入
        sql_patterns = [
            r"(?i)\b(select|insert|update|delete|drop|alter)\b",
            r"(?i)(union|join)\s+select"
        ]
        for pattern in sql_patterns:
            if re.search(pattern, v):
                raise ValueError("可能包含SQL注入")

        return v

11.4.2 输出过滤

def sanitize_output(output: str) -> str:
    """过滤输出内容"""
    # 移除敏感信息
    import re

    # 过滤API密钥
    output = re.sub(r'(api[_-]?key["\']?\s*[:=]\s*["\']?)[\w-]+', r'\1***', output, flags=re.IGNORECASE)

    # 过滤密码
    output = re.sub(r'(password["\']?\s*[:=]\s*["\']?)[\w]+', r'\1***', output, flags=re.IGNORECASE)

    # 过滤IP地址
    output = re.sub(r'\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b', '***.***.***.***', output)

    return output

---

总结

DeepAgent是一个强大的智能体开发框架,通过内置的任务规划、文件系统管理、子代理生成和长期记忆等能力,让开发者能够用最少的代码构建最复杂的智能体应用。

核心优势

1. 开箱即用: 一行代码初始化,内置核心能力
2. 高度可定制: 支持自定义工具、模型、提示词
3. 生产就绪: 基于LangGraph运行时,支持流式输出、检查点、HITL
4. 开源免费: MIT许可证,完全可商用

适用场景

• ✅ 深度调研和多轮分析
• ✅ 全栈代码开发
• ✅ 复杂数据处理
• ✅ 自动化工作流

快速开始

from deepagents import create_deep_agent

# 创建Agent
agent = create_deep_agent()

# 执行任务
result = agent.invoke({
    "messages": [{"role": "user", "content": "你的任务"}]
})

# 获取结果
print(result["messages"][-1]["content"])

###参考

1. 阅读官方文档: https://docs.langchain.com/oss/python/deepagents
2. 查看GitHub仓库: https://github.com/langchain-ai/deepagents
3. 加入社区讨论: https://github.com/langchain-ai/langchain/discussions