LangChain DeepAgents 学习笔记摘要LangChain的DeepAgents已经发布有段时间了最近的几个版本基本覆盖了大多数智能体都应该有的功能。本笔记基于 LangChain 的 DeepAgents 框架演示如何构建了一个具有角色扮演能力的 AI 助手并集成了自定义技能系统。以此方便后续的knowledge review以及vibe coding的reference。环境配置环境变量设置fromdotenvimportload_dotenvimportos# 加载 .env 文件中的环境变量load_dotenv()# 设置环境变量供 deepagents 使用OpenAI 兼容格式os.environ[OPENAI_API_KEY]os.getenv(DEEPSEEK_API_KEY,)os.environ[OPENAI_API_BASE]os.getenv(DEEPSEEK_API_BASE,https://api.deepseek.com/v1)这里我们使用在线版本的deepseek。尝试过使用本地的小模型需要留意的是deepseek的小参数量模型不支持工具的调用。即使换到qwen的小模型对工具的调用也总会出莫名其妙的问题。所以为方便学习和测试建议走在线的模型。工具函数定义为了演示方便这里创建两个方法作为DeepAgent的工具。时间查询工具fromdatetimeimportdatetimedefget_time():Get current timereturndatetime.now().strftime(%Y-%m-%d %H:%M:%S)位置查询工具defget_location():Get locationreturn北京为方便演示位置查询的output直接写死。注方法要有注释标注这个方法是干什么的方便智能体的了解不然会报错。核心组件记忆检查点Checkpointerfromlanggraph.checkpoint.memoryimportInMemorySaver checkpointer1InMemorySaver()由于大模型的对话都是无状态的比如你第一次对话问来一首唐诗第二次对话追问再来一首那么大模型会不知道到底再来一首啥。LangChain封装了这么一套方法来维护对话的状态。代码讲解InMemorySaver是 LangGraph 提供的内存检查点存储用于保存对话状态实现多轮对话的记忆功能每次对话后自动保存状态下次可以继续同一话题支持通过thread_id区分不同的对话线程中间件Middlewarefromlangchain.agents.middlewareimportSummarizationMiddleware middleware[SummarizationMiddleware(modeldeepseek:deepseek-chat,trigger(tokens,1000),keep(messages,3))]LangChain通过中间件的方式来处理模型对话历史过长的问题处理的方法有很多比如消息裁剪等。这里演示的是更常用的将历史对话进行大模型语义汇总的方式基本的方法就是将指定久远之外的消息汇总成一个简短的摘要。代码讲解SummarizationMiddleware摘要中间件用于优化长对话的上下文管理参数说明model用于生成摘要的模型trigger(tokens,1000)当上下文达到 1000 tokens 时触发摘要keep(messages,3)保留3 条消息作用当对话过长时自动将早期对话摘要为简短总结节省 token 并保持关键信息如果keep的messages设置为3那么最近的两条message会被完整保留第三条是根据以前的会话记录summaize下来的信息。本地 Shell 后端fromdeepagents.backendsimportLocalShellBackend backendLocalShellBackend(root_dir.,virtual_modeTrue)这个是用来确保智能体能够读取到skills并且能够运行里面的脚本。代码讲解LocalShellBackend本地 Shell 执行后端参数说明root_dir.工作目录根路径设置为当前目录virtual_modeTrue启用虚拟模式限制文件访问范围提高安全性作用允许 Agent 执行本地命令和脚本扩展其能力范围创建 Deep Agent核心代码fromdeepagentsimportcreate_deep_agent agentcreate_deep_agent(modeldeepseek:deepseek-chat,system_prompt你是于谦捧话之王说话坏简介明了直奔主题。,tools[get_time,get_location],checkpointercheckpointer1,middleware[SummarizationMiddleware(modeldeepseek:deepseek-chat,trigger(tokens,1000),keep(messages,3))],backendLocalShellBackend(root_dir.,virtual_modeTrue),skills[./skills],)跟传统的create_agent比创建deepagent的方法对应的是create_deep_agent。大多数的传入参数基本都是一样的。参数详解参数说明model使用的模型名称这里使用 DeepSeek 的 deepseek-chat 模型system_prompt系统提示词定义 Agent 的角色和行为风格tools工具函数列表Agent 可以调用这些函数checkpointer记忆检查点用于保存对话状态middleware中间件列表用于处理上下文摘要等任务backend执行后端用于运行本地命令skills技能目录列表加载自定义技能扩展对话循环智能体记忆的配置配合智能体的记忆功能使用的。config{configurable:{thread_id:1}}这个config是需要放在后续的invoke里的。其实这里没太想明白为什么不放在构造deepagent的构造函数里。代码讲解thread_id对话线程标识符相同的thread_id可以延续之前的对话不同的thread_id会开启新的对话线程主循环逻辑index1while(True):print(f### 第{index}轮对话 ###)queryinput(请输入)ifqueryexit:print(退出)breakresultsagent.invoke({messages:[{role:user,content:query}]},configconfig)formessageinresults[messages]:message.pretty_print()index1技能系统Skills这里我们演示一个HR的请假系统相应的代码我们只定义了接口为了演示方便不做具体的实现以及系统的对接只返回固定的output。技能目录结构通常我们建议单独的一个skills目录保存所有skills然后通过每个子目录来保存不同的skill。skills/ └── HR/ └── SKILL.mdHR 技能的介绍文件路径skills/HR/SKILL.md技能元数据--- name: HR assistant description: HR 助手 ---这两个配置是每个skill必须都要包含的包括name技能的唯一标识符description技能的简短描述功能说明本技能是 HR 系统的 AI 助手根据系统接口文档和用户的问题直接调用相应的接口完成操作。当用户说小赵时触发。根据这段声明我们定义了触发机制为触发词“小赵”当用户在对话中提到小赵时Agent 会自动调用此技能支持的功能这部分包含skill里都有什么功能### 1. 请假 - **功能**创建新的请假申请 - **需要确认的信息** - 姓名 - 请假开始时间 - 请假结束时间 - 请假类型病假事假年假婚假丧假产假其他 - **操作流程** 1. 检查用户提供的信息是否完整 2. 如果有任何信息不完整依次向用户确认 3. 所有信息确认后让用户再次确认所有信息 4. 调用 create_leave_application 函数创建请假申请根据这段描述我们可以看到这里我们要求skill信息收集主动询问缺失的信息一次只问一个问题避免用户困惑信息确认汇总所有信息展示给用户等待用户最终确认执行操作调用具体的函数实现业务逻辑SILLL完整代码--- name: HR assistant description: HR 助手 --- # HR 助手 ## 功能说明 本技能是HR系统的AI助手根据系统接口文档和用户的问题直接调用相应的接口完成操作。当用户说小赵时触发。 ## 支持的功能 ### 1. 请假 - **功能**创建新的请假申请 - **需要确认的信息** - 姓名 - 请假开始时间 - 请假结束时间 - 请假类型病假事假年假婚假丧假产假其他 - **操作流程** 1. 检查用户提供的信息是否完整 2. 如果有任何信息不完整依次向用户确认 3. 所有信息确认后让用户再次确认所有信息 4. 调用 create_leave_application 函数创建请假申请 ### 请假代码的具体实现 python def create_leave_application(name, start_time, end_time, leave_type): 创建新的请假申请 参数 - name: 姓名 - start_time: 请假开始时间格式YYYY-MM-DD HH:MM - end_time: 请假结束时间格式YYYY-MM-DD HH:MM - leave_type: 请假类型病假事假年假婚假丧假产假其他 返回 - 申请结果字典 #实现方法略 return { success: True, message: 请假申请已创建, data: { name: name, start_time: start_time, end_time: end_time, leave_type: leave_type, status: pending } } 技能使用示例用户对话流程以下是一段测试对话。我比较喜欢的一个点是通过skill以及智能体的加持对于参数的输入就灵活了很多在体验上更人性化。比如接口对日期格式的要求是yyyy-MM-dd跟智能体对话的时候你只要说明天或者后天那么智能体会根据接口的定义自动转换成符合要求的日期格式。用户小赵我想休一天的假 Agent好的我是 HR 助手小赵。请问您的姓名是 用户我是哈士奇 Agent好的哈士奇。请问您想请哪一天的假 用户后天 Agent好的后天2026-05-21。请问您想请什么类型的假 可选类型病假、事假、年假、婚假、丧假、产假、其他 用户年假 Agent请确认以下请假信息 - 姓名哈士奇 - 请假类型年假 - 开始时间2026-05-21 09:00 - 结束时间2026-05-21 18:00 以上信息是否正确 用户正确 Agent✅ 请假申请已成功创建 申请状态pending待审批关于上下文的汇总由于需要比较多的智能体对话所以测试结果不放在这里感兴趣的朋友可以自己跑下代码然后在输出部分看智能体是如何summarize历史对话记录的。关键技术点总结DeepAgents 架构优势模块化设计工具Tools扩展 Agent 能力中间件Middleware处理上下文管理技能Skills实现特定领域功能后端Backend支持本地执行记忆管理通过 Checkpointer 实现状态持久化支持多线程对话中间件自动摘要优化上下文技能系统基于 Markdown 文件定义触发词机制自动激活支持复杂的多轮交互流程最佳实践系统提示词设计明确角色定位定义语言风格简洁具体工具函数编写函数名清晰描述功能添加文档字符串返回值格式统一技能开发明确触发条件设计完整的交互流程提供详细的参数说明常见问题中间件重复问题错误信息AssertionError: Please remove duplicate middleware instances.原因只要使用middleware那么就会报这个错目前分析是版本的bug。以撰写此文的时间2026年5月18日为准默认版本是0.6.1经过我的测试如果用0.5.1的版本的话就不会有这个问题。解决pip卸载默认版本安装0.5.1这个版本具体方法可以参考我上一篇笔记。另目前很多vibe coding生成langchain的deepagents代码都会有很多问题主要是因为这个东西太新了很多智能体即使有再牛的上下文系统也不知道该如何去生成正确的代码所以需要自己去鉴别一下。总结目前LangChain的DeepAgents已经支持了跟智能体相关的大多数方法通过学习DeepAgents我们也可以顺便理解目前市面上主流的智能体其背后是如何工作的。此文做阶段性的学习总结方便后续的review以及供vibe coding参考。参考资料LangChain 官方文档DeepAgents 文档LangGraph 文档
LangChain DeepAgents 学习笔记
发布时间：2026/5/20 15:44:09
LangChain DeepAgents 学习笔记摘要LangChain的DeepAgents已经发布有段时间了最近的几个版本基本覆盖了大多数智能体都应该有的功能。本笔记基于 LangChain 的 DeepAgents 框架演示如何构建了一个具有角色扮演能力的 AI 助手并集成了自定义技能系统。以此方便后续的knowledge review以及vibe coding的reference。环境配置环境变量设置fromdotenvimportload_dotenvimportos# 加载 .env 文件中的环境变量load_dotenv()# 设置环境变量供 deepagents 使用OpenAI 兼容格式os.environ[OPENAI_API_KEY]os.getenv(DEEPSEEK_API_KEY,)os.environ[OPENAI_API_BASE]os.getenv(DEEPSEEK_API_BASE,https://api.deepseek.com/v1)这里我们使用在线版本的deepseek。尝试过使用本地的小模型需要留意的是deepseek的小参数量模型不支持工具的调用。即使换到qwen的小模型对工具的调用也总会出莫名其妙的问题。所以为方便学习和测试建议走在线的模型。工具函数定义为了演示方便这里创建两个方法作为DeepAgent的工具。时间查询工具fromdatetimeimportdatetimedefget_time():Get current timereturndatetime.now().strftime(%Y-%m-%d %H:%M:%S)位置查询工具defget_location():Get locationreturn北京为方便演示位置查询的output直接写死。注方法要有注释标注这个方法是干什么的方便智能体的了解不然会报错。核心组件记忆检查点Checkpointerfromlanggraph.checkpoint.memoryimportInMemorySaver checkpointer1InMemorySaver()由于大模型的对话都是无状态的比如你第一次对话问来一首唐诗第二次对话追问再来一首那么大模型会不知道到底再来一首啥。LangChain封装了这么一套方法来维护对话的状态。代码讲解InMemorySaver是 LangGraph 提供的内存检查点存储用于保存对话状态实现多轮对话的记忆功能每次对话后自动保存状态下次可以继续同一话题支持通过thread_id区分不同的对话线程中间件Middlewarefromlangchain.agents.middlewareimportSummarizationMiddleware middleware[SummarizationMiddleware(modeldeepseek:deepseek-chat,trigger(tokens,1000),keep(messages,3))]LangChain通过中间件的方式来处理模型对话历史过长的问题处理的方法有很多比如消息裁剪等。这里演示的是更常用的将历史对话进行大模型语义汇总的方式基本的方法就是将指定久远之外的消息汇总成一个简短的摘要。代码讲解SummarizationMiddleware摘要中间件用于优化长对话的上下文管理参数说明model用于生成摘要的模型trigger(tokens,1000)当上下文达到 1000 tokens 时触发摘要keep(messages,3)保留3 条消息作用当对话过长时自动将早期对话摘要为简短总结节省 token 并保持关键信息如果keep的messages设置为3那么最近的两条message会被完整保留第三条是根据以前的会话记录summaize下来的信息。本地 Shell 后端fromdeepagents.backendsimportLocalShellBackend backendLocalShellBackend(root_dir.,virtual_modeTrue)这个是用来确保智能体能够读取到skills并且能够运行里面的脚本。代码讲解LocalShellBackend本地 Shell 执行后端参数说明root_dir.工作目录根路径设置为当前目录virtual_modeTrue启用虚拟模式限制文件访问范围提高安全性作用允许 Agent 执行本地命令和脚本扩展其能力范围创建 Deep Agent核心代码fromdeepagentsimportcreate_deep_agent agentcreate_deep_agent(modeldeepseek:deepseek-chat,system_prompt你是于谦捧话之王说话坏简介明了直奔主题。,tools[get_time,get_location],checkpointercheckpointer1,middleware[SummarizationMiddleware(modeldeepseek:deepseek-chat,trigger(tokens,1000),keep(messages,3))],backendLocalShellBackend(root_dir.,virtual_modeTrue),skills[./skills],)跟传统的create_agent比创建deepagent的方法对应的是create_deep_agent。大多数的传入参数基本都是一样的。参数详解参数说明model使用的模型名称这里使用 DeepSeek 的 deepseek-chat 模型system_prompt系统提示词定义 Agent 的角色和行为风格tools工具函数列表Agent 可以调用这些函数checkpointer记忆检查点用于保存对话状态middleware中间件列表用于处理上下文摘要等任务backend执行后端用于运行本地命令skills技能目录列表加载自定义技能扩展对话循环智能体记忆的配置配合智能体的记忆功能使用的。config{configurable:{thread_id:1}}这个config是需要放在后续的invoke里的。其实这里没太想明白为什么不放在构造deepagent的构造函数里。代码讲解thread_id对话线程标识符相同的thread_id可以延续之前的对话不同的thread_id会开启新的对话线程主循环逻辑index1while(True):print(f### 第{index}轮对话 ###)queryinput(请输入)ifqueryexit:print(退出)breakresultsagent.invoke({messages:[{role:user,content:query}]},configconfig)formessageinresults[messages]:message.pretty_print()index1技能系统Skills这里我们演示一个HR的请假系统相应的代码我们只定义了接口为了演示方便不做具体的实现以及系统的对接只返回固定的output。技能目录结构通常我们建议单独的一个skills目录保存所有skills然后通过每个子目录来保存不同的skill。skills/ └── HR/ └── SKILL.mdHR 技能的介绍文件路径skills/HR/SKILL.md技能元数据--- name: HR assistant description: HR 助手 ---这两个配置是每个skill必须都要包含的包括name技能的唯一标识符description技能的简短描述功能说明本技能是 HR 系统的 AI 助手根据系统接口文档和用户的问题直接调用相应的接口完成操作。当用户说小赵时触发。根据这段声明我们定义了触发机制为触发词“小赵”当用户在对话中提到小赵时Agent 会自动调用此技能支持的功能这部分包含skill里都有什么功能### 1. 请假 - **功能**创建新的请假申请 - **需要确认的信息** - 姓名 - 请假开始时间 - 请假结束时间 - 请假类型病假事假年假婚假丧假产假其他 - **操作流程** 1. 检查用户提供的信息是否完整 2. 如果有任何信息不完整依次向用户确认 3. 所有信息确认后让用户再次确认所有信息 4. 调用 create_leave_application 函数创建请假申请根据这段描述我们可以看到这里我们要求skill信息收集主动询问缺失的信息一次只问一个问题避免用户困惑信息确认汇总所有信息展示给用户等待用户最终确认执行操作调用具体的函数实现业务逻辑SILLL完整代码--- name: HR assistant description: HR 助手 --- # HR 助手 ## 功能说明 本技能是HR系统的AI助手根据系统接口文档和用户的问题直接调用相应的接口完成操作。当用户说小赵时触发。 ## 支持的功能 ### 1. 请假 - **功能**创建新的请假申请 - **需要确认的信息** - 姓名 - 请假开始时间 - 请假结束时间 - 请假类型病假事假年假婚假丧假产假其他 - **操作流程** 1. 检查用户提供的信息是否完整 2. 如果有任何信息不完整依次向用户确认 3. 所有信息确认后让用户再次确认所有信息 4. 调用 create_leave_application 函数创建请假申请 ### 请假代码的具体实现 python def create_leave_application(name, start_time, end_time, leave_type): 创建新的请假申请 参数 - name: 姓名 - start_time: 请假开始时间格式YYYY-MM-DD HH:MM - end_time: 请假结束时间格式YYYY-MM-DD HH:MM - leave_type: 请假类型病假事假年假婚假丧假产假其他 返回 - 申请结果字典 #实现方法略 return { success: True, message: 请假申请已创建, data: { name: name, start_time: start_time, end_time: end_time, leave_type: leave_type, status: pending } } 技能使用示例用户对话流程以下是一段测试对话。我比较喜欢的一个点是通过skill以及智能体的加持对于参数的输入就灵活了很多在体验上更人性化。比如接口对日期格式的要求是yyyy-MM-dd跟智能体对话的时候你只要说明天或者后天那么智能体会根据接口的定义自动转换成符合要求的日期格式。用户小赵我想休一天的假 Agent好的我是 HR 助手小赵。请问您的姓名是 用户我是哈士奇 Agent好的哈士奇。请问您想请哪一天的假 用户后天 Agent好的后天2026-05-21。请问您想请什么类型的假 可选类型病假、事假、年假、婚假、丧假、产假、其他 用户年假 Agent请确认以下请假信息 - 姓名哈士奇 - 请假类型年假 - 开始时间2026-05-21 09:00 - 结束时间2026-05-21 18:00 以上信息是否正确 用户正确 Agent✅ 请假申请已成功创建 申请状态pending待审批关于上下文的汇总由于需要比较多的智能体对话所以测试结果不放在这里感兴趣的朋友可以自己跑下代码然后在输出部分看智能体是如何summarize历史对话记录的。关键技术点总结DeepAgents 架构优势模块化设计工具Tools扩展 Agent 能力中间件Middleware处理上下文管理技能Skills实现特定领域功能后端Backend支持本地执行记忆管理通过 Checkpointer 实现状态持久化支持多线程对话中间件自动摘要优化上下文技能系统基于 Markdown 文件定义触发词机制自动激活支持复杂的多轮交互流程最佳实践系统提示词设计明确角色定位定义语言风格简洁具体工具函数编写函数名清晰描述功能添加文档字符串返回值格式统一技能开发明确触发条件设计完整的交互流程提供详细的参数说明常见问题中间件重复问题错误信息AssertionError: Please remove duplicate middleware instances.原因只要使用middleware那么就会报这个错目前分析是版本的bug。以撰写此文的时间2026年5月18日为准默认版本是0.6.1经过我的测试如果用0.5.1的版本的话就不会有这个问题。解决pip卸载默认版本安装0.5.1这个版本具体方法可以参考我上一篇笔记。另目前很多vibe coding生成langchain的deepagents代码都会有很多问题主要是因为这个东西太新了很多智能体即使有再牛的上下文系统也不知道该如何去生成正确的代码所以需要自己去鉴别一下。总结目前LangChain的DeepAgents已经支持了跟智能体相关的大多数方法通过学习DeepAgents我们也可以顺便理解目前市面上主流的智能体其背后是如何工作的。此文做阶段性的学习总结方便后续的review以及供vibe coding参考。参考资料LangChain 官方文档DeepAgents 文档LangGraph 文档
