1. 先搞清楚 DeepAgents 到底解决什么问题DeepAgents 是一个基于 LangChain 和 LangGraph 构建的高级智能体框架它想做的事情很具体让长周期、多步骤的自主智能体开发变得像搭积木一样简单。如果你之前写过那种思考→调用工具→观察→重复的循环式 Agent你会发现它在处理超过 10 步的任务时特别容易迷路——要么忘了最初的目标要么陷入死循环要么上下文窗口被工具返回结果塞爆。DeepAgents 就是冲着这些痛点来的。它的定位可以用一句话概括LangChain 提供积木Prompt、Models、ToolsLangGraph 提供地基State、Node、Edge而 DeepAgents 是一套成品级的框架预置了规划、文件系统、子智能体这些最佳实践。你不需要从零去拼装这些组件直接调用create_deep_agent()就能得到一个具备完整能力的深度智能体。适合谁刚接触智能体开发、想快速跑通一个能处理复杂任务的小白程序员。它不适合拿来做简单的聊天机器人那是 LangChain 基础链的活。DeepAgents 面向的是深度调研、全栈代码生成、复杂数据分析、自动化运维、复杂工作流编排这类需要规划、需要长期记忆、需要多专家协作的场景。我试过用传统 Agent 做一个调研某个行业市场格局并生成报告的任务跑到第 15 步左右就开始重复搜索同样的关键词因为上下文里堆了太多工具返回的原始网页内容模型已经抓不住重点了。换成 DeepAgents 之后它会把中间结果写进虚拟文件系统主线程的上下文始终保持干净任务拆解和进度追踪由内置的 TodoList 中间件管理整个流程顺畅很多。理解 DeepAgents 的关键在于理解它的四大核心支柱系统提示词负责定义行为准则规划工具负责把模糊需求变成可执行的任务清单文件系统负责解决长任务中的信息溢出和状态持久化子智能体负责上下文隔离和专业分工。这四者通过中间件的形式注入构成了一个高可靠、可追溯、可恢复的完整闭环。从技术演进的角度看DeepAgents 标志着 AI Agent 从脚本化向产品化的关键一步。以前你写一个 Agent更像是在写一个一次性的脚本现在你用 DeepAgents是在构建一个可以长期运行、可以中断恢复、可以观测调试的产品级组件。这个思维转变对小白来说尤其重要——不要一上来就想着把所有逻辑塞进一个 prompt 里而是学会用框架提供的抽象来组织你的智能体。2. 环境安装与 TaoToken 前置配置在开始写代码之前你需要先把运行环境搭好。DeepAgents 本身是一个 Python 包依赖 LangChain 和 LangGraph 生态。我建议用 Python 3.10 以上的版本太老的版本在依赖解析上容易出问题。第一步是安装核心依赖。打开终端执行pip install deepagents安装完成后可以顺手确认一下版本pip list | grep -E langchain|deepagents你会看到类似这样的输出deepagents 0.3.0 langchain 1.2.0 langchain-core 1.2.1 langchain-openai 1.0.2 langchain-deepseek 1.0.0 langchain-tavily 0.2.13版本号不用完全一致但 deepagents 建议在 0.3.0 以上langchain 在 1.2.0 以上这样能保证create_deep_agent的接口是稳定的。接下来是模型接入。DeepAgents 默认会使用 Claude Sonnet 4 作为模型但你可以指定任何 LangChain 支持的模型。这里我推荐通过 TaoToken 来统一管理模型调用它的 API 兼容 OpenAI 格式接入成本很低。TaoToken 的 API 地址是https://taotoken.net/api你需要在官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后拿到 API Key。拿到 Key 之后在项目根目录创建一个.env文件TAOTOKEN_API_KEY你的APIKey TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 代码里这样初始化模型import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv(overrideTrue) model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0 ) # 快速验证模型是否可用 print(model.invoke(你好).content)如果你更习惯用 DeepSeek也可以换成langchain_deepseek的ChatDeepSeek同样把 base_url 指向 TaoToken 的地址即可。关键点是Base URL、API Key、Model ID 这三件套要配对缺一个都会报 401。这里有个小坑要注意load_dotenv(overrideTrue)里的overrideTrue很重要。如果你之前已经在系统环境变量里设置过同名的 Key不加这个参数的话.env文件里的值不会覆盖系统变量你会一直用错 Key 却找不到原因。另外如果你打算用 Tavily 做联网搜索还需要额外安装pip install langchain-tavily并在.env里加上TAVILY_API_KEY。Tavily 的搜索质量在智能体场景下比直接调搜索引擎 API 要好它返回的是已经清洗过的摘要内容能减少上下文污染。环境准备好之后建议先跑一个最小验证确认模型能正常返回from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv(overrideTrue) model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL) ) response model.invoke(用一句话解释什么是智能体) print(response.content)如果这一步能打印出正常的中文回答说明模型接入没问题可以进入下一步了。3. 最小可运行智能体配置与代码现在我们来写第一个 DeepAgents 智能体。核心入口是create_deep_agent()这个函数会返回一个配置好的深度智能体。它的关键参数包括参数作用是否必填model指定语言模型建议填否则用默认 Claude Sonnet 4tools自定义工具集可选system_prompt系统提示词可选框架有默认值subagents子智能体配置可选backend文件存储后端可选interrupt_on人机交互配置可选checkpointer状态持久化可选下面是一个完整的最小可运行示例包含 Tavily 搜索工具和内存检查点from deepagents import create_deep_agent from langchain_tavily import TavilySearch from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import InMemorySaver from dotenv import load_dotenv import os load_dotenv(overrideTrue) # 1. 初始化模型 model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0 ) # 2. 初始化搜索工具 tavily TavilySearch(max_results3) # 3. 编写系统提示词 research_instructions 你是一位资深的研究人员。你的工作是进行深入的研究然后撰写一份精美的报告。 你可以通过互联网搜索工具作为主要的信息收集工具。 ## 可用工具 ### 互联网搜索 使用此功能针对给定的查询进行互联网搜索。 ### 写入本地文件 使用此功能将研究报告保存到本地文件。 - 文件路径建议使用 .md 格式 - 请确保报告内容完整、结构清晰 ## 工作流程 1. 首先将研究任务分解为清晰的步骤 2. 使用互联网搜索来收集全面的信息 3. 将信息整合成一份结构清晰的报告 4. 务必使用写入本地文件工具将完整报告保存 5. 务必引用你的资料来源 # 4. 创建智能体 agent create_deep_agent( nameDeepAgents_Agent, tools[tavily], modelmodel, system_promptresearch_instructions, checkpointerInMemorySaver() ) # 5. 调用智能体 config {configurable: {thread_id: 1}} result agent.invoke( {messages: [{role: user, content: 帮我查询一下有关 deepagents 框架的最新动态}]}, configconfig ) print(result[messages][-1].content)这段代码跑起来之后你会看到智能体先规划任务然后调用 Tavily 搜索把结果整理后写入文件最后返回一份报告。整个过程你不需要手动干预。有几个细节值得展开说。第一system_prompt可以不写框架有默认的提示词但默认提示词比较通用针对具体场景自定义效果会好很多。第二model一定要指定否则会走默认的 Claude Sonnet 4如果你没有对应的 Key 就会报错。第三checkpointer用InMemorySaver适合本地测试生产环境建议换成持久化的后端。如果你想把配置写成 JSON 或 TOML 形式方便管理可以这样组织{ agent: { name: DeepAgents_Agent, model: gpt-4o, temperature: 0, system_prompt_file: ./prompts/research.md, tools: [tavily_search], checkpointer: memory }, tavily: { max_results: 3 } }然后在代码里读取这个配置来初始化。这样做的好处是提示词和代码分离改提示词不用动 Python 文件。创建完智能体之后你可以用一段小代码看看它到底加载了哪些工具def print_agent_tools(agent): if hasattr(agent, nodes) and tools in agent.nodes: tools_node agent.nodes[tools] if hasattr(tools_node, bound): tool_node tools_node.bound if hasattr(tool_node, tools_by_name): tools tool_node.tools_by_name for name, tool in tools.items(): print(f- {name}: {getattr(tool, description, 无描述)[:60]}) print_agent_tools(agent)你会看到除了自己传入的 Tavily 搜索框架还自动加了ls、read_file、write_file、edit_file、glob、grep、execute这七个文件系统工具以及write_todos和task两个系统工具。这些就是 DeepAgents 的出厂配置也是它区别于普通 Agent 的核心所在。4. 验证请求与成功结果分析代码写完之后怎么确认它真的跑通了我建议分三步验证。第一步验证模型连通性。单独调用一次model.invoke(你好)确认能拿到返回。如果这一步就报 401说明 API Key 或 Base URL 有问题先解决这个再往下走。第二步验证智能体创建。执行create_deep_agent()之后打印一下 agent 的类型和节点信息print(type(agent)) print(agent.nodes.keys() if hasattr(agent, nodes) else 无 nodes 属性)正常情况下你会看到类似dict_keys([agent, tools])的输出说明图结构已经构建好了。第三步验证完整调用。用agent.invoke()发一个简单任务观察返回结果。一个成功的调用应该包含以下特征返回的messages列表长度大于 2说明经过了多轮工具调用最后一条消息的content是一段完整的自然语言回答中间能看到tool_calls字段说明工具被正确调用了如果你想看得更清楚可以用流式输出把每一步都打印出来config {configurable: {thread_id: 2}} for event in agent.stream( {messages: [{role: user, content: 调研 LangChain DeepAgents 框架的核心特性}]}, stream_modevalues, configconfig ): if messages in event: msg event[messages][-1] if hasattr(msg, tool_calls) and msg.tool_calls: for tc in msg.tool_calls: print(f[工具调用] {tc[name]} 参数: {tc[args]}) elif hasattr(msg, name) and msg.name: print(f[工具返回] {msg.name}: {str(msg.content)[:200]}) elif msg.content: print(f[AI 回复] {msg.content[:300]})跑起来之后你会看到类似这样的输出[工具调用] write_todos 参数: {todos: [{task: 搜索 DeepAgents 核心特性, status: pending}, ...]} [工具调用] tavily_search 参数: {query: LangChain DeepAgents framework features} [工具返回] tavily_search: DeepAgents is a framework built on LangChain and LangGraph... [工具调用] write_file 参数: {path: research_report.md, content: # DeepAgents 调研报告...} [AI 回复] 根据调研DeepAgents 的核心特性包括...这个过程中write_todos是规划工具在起作用它把任务拆成了待办清单tavily_search是信息收集write_file是把结果落盘。整个链路走通说明你的第一个深度智能体已经成功运行了。如果任务比较复杂你还可以观察子智能体的调用。当主智能体判断某个子任务需要独立上下文时它会调用task工具启动一个子智能体。子智能体有自己独立的 messages 和 files 命名空间执行完之后只把总结性结果返回给主智能体。这个机制是 DeepAgents 控制上下文长度的关键。验证成功的另一个标志是你可以在项目目录下找到智能体写入的文件。比如上面例子里的research_report.md打开看看内容是否完整、结构是否清晰。如果文件存在且内容合理说明文件系统中间件工作正常。5. 本篇常见错误排查即使按照步骤来也难免遇到报错。下面是我踩过的一些坑对照着排查能省不少时间。报错一401 Unauthorizedopenai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}这是最常见的错误原因通常是 API Key 没配对。检查三个地方.env文件里的TAOTOKEN_API_KEY是否正确load_dotenv(overrideTrue)是否加了overrideTrueChatOpenAI初始化时api_key和base_url是否都传了。如果用的是 TaoTokenBase URL 应该是https://taotoken.net/api不要多加斜杠或路径。报错二local proxy failed / Connection errorhttpx.ConnectError: [Errno 111] Connection refused这种一般是网络层的问题。先确认你的 Base URL 能通可以用 curl 测一下curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:hi}]}如果 curl 能通但 Python 不通检查是不是环境变量里有残留的代理设置。另外某些公司网络会拦截外部 API 请求这种情况需要换网络环境。报错三reading choices 相关错误KeyError: choices这个错误通常出现在模型返回格式不符合预期的时候。可能的原因是你指定的 model ID 在 TaoToken 那边不存在或者返回的是错误信息而不是正常的 completion 结构。解决办法是先单独用model.invoke()测一下确认模型名正确。TaoToken 支持的模型 ID 可以在模型对话页面查到。报错四OAuth 相关错误Error: OAuth token expired or invalid如果你用的是某些需要 OAuth 的模型服务token 过期会报这个。换成 API Key 方式接入 TaoToken 就不会有这个问题因为 TaoToken 用的是标准的 Bearer Token 认证。报错五智能体跑很久不返回如果调用超过 1 分钟还没结果可能是陷入了死循环。DeepAgents 默认的系统提示词会引导模型先规划再执行但如果你自定义的 system_prompt 太模糊模型可能会反复调用同一个工具。解决办法是检查你的提示词明确告诉它完成任务后必须输出最终答案。另外可以用 LangSmith 做链路追踪看看卡在哪一步。报错六子智能体调用失败ValueError: subagent xxx not found如果你在subagents参数里配置了子智能体但主智能体调用时找不到检查子智能体的name字段是否和调用时一致。子智能体配置必须包含name、description、prompt三个字段缺一个都会导致注册失败。报错七文件写入失败PermissionError: [Errno 13] Permission deniedDeepAgents 默认用的是内存级虚拟文件系统不会真的写到你本地磁盘。如果你配置了backend指向本地路径确保那个目录有写权限。本地测试建议先用默认的内存后端避免权限问题干扰。排查问题的通用思路是先隔离变量。把模型调用、工具调用、智能体创建分开测哪一步报错就集中解决那一步。不要一上来就怀疑框架有问题大部分情况都是配置或环境的问题。6. 从跑通到用好下一步怎么走第一个智能体跑通之后你可能会想接下来怎么把它用在实际项目里这里给几个方向。第一把系统提示词写得更具体。默认提示词是通用的针对你的业务场景定制之后效果会明显提升。比如你做代码审查就在提示词里明确审查标准、输出格式、常见问题清单。提示词的质量直接决定智能体的表现上限。第二学会用子智能体做分工。当任务涉及多个独立领域时给每个领域配一个专门的子智能体主智能体只负责调度和汇总。这样既能隔离上下文又能让每个子智能体用最适合的模型和工具。比如一个负责查官方文档一个负责搜社区实践最后主智能体对比两者输出。第三配置持久化存储。本地测试用InMemorySaver就够了但生产环境需要把状态存到数据库或 Redis这样智能体中断后可以恢复多个会话之间也能共享文件。DeepAgents 支持切换StateBackend具体配置可以参考接入文档。第四接入可观测性。LangSmith 能让你看到每一步的输入输出、token 消耗、耗时排查问题时非常有用。尤其是智能体行为不符合预期时看 trace 比看日志高效得多。如果你在配置模型或排查报错时遇到问题可以直接去 TaoToken 的 API Keys 页面检查 Key 状态或者翻一下接入文档里的示例。想先体验一下模型对话效果可以用模型对话页面快速测试。如果打算长期做编码类智能体Coding Plan 会更划算。最后说一个实用技巧DeepAgents 的interrupt_on参数可以让你在关键节点暂停智能体等人工确认后再继续。比如删除文件、执行 shell 命令这类高风险操作配置成需要人工审批能避免很多意外。这个功能在自动化运维场景下特别有用值得花时间研究一下。 
长河君 · 2026/10/7 7:05:17 · 阅读 1.2k 小白程序员必看：轻松入门 DeepAgents 框架，构建深度智能体（收藏版）
1. 先搞清楚 DeepAgents 到底解决什么问题DeepAgents 是一个基于 LangChain 和 LangGraph 构建的高级智能体框架它想做的事情很具体让长周期、多步骤的自主智能体开发变得像搭积木一样简单。如果你之前写过那种思考→调用工具→观察→重复的循环式 Agent你会发现它在处理超过 10 步的任务时特别容易迷路——要么忘了最初的目标要么陷入死循环要么上下文窗口被工具返回结果塞爆。DeepAgents 就是冲着这些痛点来的。它的定位可以用一句话概括LangChain 提供积木Prompt、Models、ToolsLangGraph 提供地基State、Node、Edge而 DeepAgents 是一套成品级的框架预置了规划、文件系统、子智能体这些最佳实践。你不需要从零去拼装这些组件直接调用create_deep_agent()就能得到一个具备完整能力的深度智能体。适合谁刚接触智能体开发、想快速跑通一个能处理复杂任务的小白程序员。它不适合拿来做简单的聊天机器人那是 LangChain 基础链的活。DeepAgents 面向的是深度调研、全栈代码生成、复杂数据分析、自动化运维、复杂工作流编排这类需要规划、需要长期记忆、需要多专家协作的场景。我试过用传统 Agent 做一个调研某个行业市场格局并生成报告的任务跑到第 15 步左右就开始重复搜索同样的关键词因为上下文里堆了太多工具返回的原始网页内容模型已经抓不住重点了。换成 DeepAgents 之后它会把中间结果写进虚拟文件系统主线程的上下文始终保持干净任务拆解和进度追踪由内置的 TodoList 中间件管理整个流程顺畅很多。理解 DeepAgents 的关键在于理解它的四大核心支柱系统提示词负责定义行为准则规划工具负责把模糊需求变成可执行的任务清单文件系统负责解决长任务中的信息溢出和状态持久化子智能体负责上下文隔离和专业分工。这四者通过中间件的形式注入构成了一个高可靠、可追溯、可恢复的完整闭环。从技术演进的角度看DeepAgents 标志着 AI Agent 从脚本化向产品化的关键一步。以前你写一个 Agent更像是在写一个一次性的脚本现在你用 DeepAgents是在构建一个可以长期运行、可以中断恢复、可以观测调试的产品级组件。这个思维转变对小白来说尤其重要——不要一上来就想着把所有逻辑塞进一个 prompt 里而是学会用框架提供的抽象来组织你的智能体。2. 环境安装与 TaoToken 前置配置在开始写代码之前你需要先把运行环境搭好。DeepAgents 本身是一个 Python 包依赖 LangChain 和 LangGraph 生态。我建议用 Python 3.10 以上的版本太老的版本在依赖解析上容易出问题。第一步是安装核心依赖。打开终端执行pip install deepagents安装完成后可以顺手确认一下版本pip list | grep -E langchain|deepagents你会看到类似这样的输出deepagents 0.3.0 langchain 1.2.0 langchain-core 1.2.1 langchain-openai 1.0.2 langchain-deepseek 1.0.0 langchain-tavily 0.2.13版本号不用完全一致但 deepagents 建议在 0.3.0 以上langchain 在 1.2.0 以上这样能保证create_deep_agent的接口是稳定的。接下来是模型接入。DeepAgents 默认会使用 Claude Sonnet 4 作为模型但你可以指定任何 LangChain 支持的模型。这里我推荐通过 TaoToken 来统一管理模型调用它的 API 兼容 OpenAI 格式接入成本很低。TaoToken 的 API 地址是https://taotoken.net/api你需要在官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后拿到 API Key。拿到 Key 之后在项目根目录创建一个.env文件TAOTOKEN_API_KEY你的APIKey TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 代码里这样初始化模型import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv(overrideTrue) model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0 ) # 快速验证模型是否可用 print(model.invoke(你好).content)如果你更习惯用 DeepSeek也可以换成langchain_deepseek的ChatDeepSeek同样把 base_url 指向 TaoToken 的地址即可。关键点是Base URL、API Key、Model ID 这三件套要配对缺一个都会报 401。这里有个小坑要注意load_dotenv(overrideTrue)里的overrideTrue很重要。如果你之前已经在系统环境变量里设置过同名的 Key不加这个参数的话.env文件里的值不会覆盖系统变量你会一直用错 Key 却找不到原因。另外如果你打算用 Tavily 做联网搜索还需要额外安装pip install langchain-tavily并在.env里加上TAVILY_API_KEY。Tavily 的搜索质量在智能体场景下比直接调搜索引擎 API 要好它返回的是已经清洗过的摘要内容能减少上下文污染。环境准备好之后建议先跑一个最小验证确认模型能正常返回from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv(overrideTrue) model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL) ) response model.invoke(用一句话解释什么是智能体) print(response.content)如果这一步能打印出正常的中文回答说明模型接入没问题可以进入下一步了。3. 最小可运行智能体配置与代码现在我们来写第一个 DeepAgents 智能体。核心入口是create_deep_agent()这个函数会返回一个配置好的深度智能体。它的关键参数包括参数作用是否必填model指定语言模型建议填否则用默认 Claude Sonnet 4tools自定义工具集可选system_prompt系统提示词可选框架有默认值subagents子智能体配置可选backend文件存储后端可选interrupt_on人机交互配置可选checkpointer状态持久化可选下面是一个完整的最小可运行示例包含 Tavily 搜索工具和内存检查点from deepagents import create_deep_agent from langchain_tavily import TavilySearch from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import InMemorySaver from dotenv import load_dotenv import os load_dotenv(overrideTrue) # 1. 初始化模型 model ChatOpenAI( modelgpt-4o, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0 ) # 2. 初始化搜索工具 tavily TavilySearch(max_results3) # 3. 编写系统提示词 research_instructions 你是一位资深的研究人员。你的工作是进行深入的研究然后撰写一份精美的报告。 你可以通过互联网搜索工具作为主要的信息收集工具。 ## 可用工具 ### 互联网搜索 使用此功能针对给定的查询进行互联网搜索。 ### 写入本地文件 使用此功能将研究报告保存到本地文件。 - 文件路径建议使用 .md 格式 - 请确保报告内容完整、结构清晰 ## 工作流程 1. 首先将研究任务分解为清晰的步骤 2. 使用互联网搜索来收集全面的信息 3. 将信息整合成一份结构清晰的报告 4. 务必使用写入本地文件工具将完整报告保存 5. 务必引用你的资料来源 # 4. 创建智能体 agent create_deep_agent( nameDeepAgents_Agent, tools[tavily], modelmodel, system_promptresearch_instructions, checkpointerInMemorySaver() ) # 5. 调用智能体 config {configurable: {thread_id: 1}} result agent.invoke( {messages: [{role: user, content: 帮我查询一下有关 deepagents 框架的最新动态}]}, configconfig ) print(result[messages][-1].content)这段代码跑起来之后你会看到智能体先规划任务然后调用 Tavily 搜索把结果整理后写入文件最后返回一份报告。整个过程你不需要手动干预。有几个细节值得展开说。第一system_prompt可以不写框架有默认的提示词但默认提示词比较通用针对具体场景自定义效果会好很多。第二model一定要指定否则会走默认的 Claude Sonnet 4如果你没有对应的 Key 就会报错。第三checkpointer用InMemorySaver适合本地测试生产环境建议换成持久化的后端。如果你想把配置写成 JSON 或 TOML 形式方便管理可以这样组织{ agent: { name: DeepAgents_Agent, model: gpt-4o, temperature: 0, system_prompt_file: ./prompts/research.md, tools: [tavily_search], checkpointer: memory }, tavily: { max_results: 3 } }然后在代码里读取这个配置来初始化。这样做的好处是提示词和代码分离改提示词不用动 Python 文件。创建完智能体之后你可以用一段小代码看看它到底加载了哪些工具def print_agent_tools(agent): if hasattr(agent, nodes) and tools in agent.nodes: tools_node agent.nodes[tools] if hasattr(tools_node, bound): tool_node tools_node.bound if hasattr(tool_node, tools_by_name): tools tool_node.tools_by_name for name, tool in tools.items(): print(f- {name}: {getattr(tool, description, 无描述)[:60]}) print_agent_tools(agent)你会看到除了自己传入的 Tavily 搜索框架还自动加了ls、read_file、write_file、edit_file、glob、grep、execute这七个文件系统工具以及write_todos和task两个系统工具。这些就是 DeepAgents 的出厂配置也是它区别于普通 Agent 的核心所在。4. 验证请求与成功结果分析代码写完之后怎么确认它真的跑通了我建议分三步验证。第一步验证模型连通性。单独调用一次model.invoke(你好)确认能拿到返回。如果这一步就报 401说明 API Key 或 Base URL 有问题先解决这个再往下走。第二步验证智能体创建。执行create_deep_agent()之后打印一下 agent 的类型和节点信息print(type(agent)) print(agent.nodes.keys() if hasattr(agent, nodes) else 无 nodes 属性)正常情况下你会看到类似dict_keys([agent, tools])的输出说明图结构已经构建好了。第三步验证完整调用。用agent.invoke()发一个简单任务观察返回结果。一个成功的调用应该包含以下特征返回的messages列表长度大于 2说明经过了多轮工具调用最后一条消息的content是一段完整的自然语言回答中间能看到tool_calls字段说明工具被正确调用了如果你想看得更清楚可以用流式输出把每一步都打印出来config {configurable: {thread_id: 2}} for event in agent.stream( {messages: [{role: user, content: 调研 LangChain DeepAgents 框架的核心特性}]}, stream_modevalues, configconfig ): if messages in event: msg event[messages][-1] if hasattr(msg, tool_calls) and msg.tool_calls: for tc in msg.tool_calls: print(f[工具调用] {tc[name]} 参数: {tc[args]}) elif hasattr(msg, name) and msg.name: print(f[工具返回] {msg.name}: {str(msg.content)[:200]}) elif msg.content: print(f[AI 回复] {msg.content[:300]})跑起来之后你会看到类似这样的输出[工具调用] write_todos 参数: {todos: [{task: 搜索 DeepAgents 核心特性, status: pending}, ...]} [工具调用] tavily_search 参数: {query: LangChain DeepAgents framework features} [工具返回] tavily_search: DeepAgents is a framework built on LangChain and LangGraph... [工具调用] write_file 参数: {path: research_report.md, content: # DeepAgents 调研报告...} [AI 回复] 根据调研DeepAgents 的核心特性包括...这个过程中write_todos是规划工具在起作用它把任务拆成了待办清单tavily_search是信息收集write_file是把结果落盘。整个链路走通说明你的第一个深度智能体已经成功运行了。如果任务比较复杂你还可以观察子智能体的调用。当主智能体判断某个子任务需要独立上下文时它会调用task工具启动一个子智能体。子智能体有自己独立的 messages 和 files 命名空间执行完之后只把总结性结果返回给主智能体。这个机制是 DeepAgents 控制上下文长度的关键。验证成功的另一个标志是你可以在项目目录下找到智能体写入的文件。比如上面例子里的research_report.md打开看看内容是否完整、结构是否清晰。如果文件存在且内容合理说明文件系统中间件工作正常。5. 本篇常见错误排查即使按照步骤来也难免遇到报错。下面是我踩过的一些坑对照着排查能省不少时间。报错一401 Unauthorizedopenai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}这是最常见的错误原因通常是 API Key 没配对。检查三个地方.env文件里的TAOTOKEN_API_KEY是否正确load_dotenv(overrideTrue)是否加了overrideTrueChatOpenAI初始化时api_key和base_url是否都传了。如果用的是 TaoTokenBase URL 应该是https://taotoken.net/api不要多加斜杠或路径。报错二local proxy failed / Connection errorhttpx.ConnectError: [Errno 111] Connection refused这种一般是网络层的问题。先确认你的 Base URL 能通可以用 curl 测一下curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:gpt-4o,messages:[{role:user,content:hi}]}如果 curl 能通但 Python 不通检查是不是环境变量里有残留的代理设置。另外某些公司网络会拦截外部 API 请求这种情况需要换网络环境。报错三reading choices 相关错误KeyError: choices这个错误通常出现在模型返回格式不符合预期的时候。可能的原因是你指定的 model ID 在 TaoToken 那边不存在或者返回的是错误信息而不是正常的 completion 结构。解决办法是先单独用model.invoke()测一下确认模型名正确。TaoToken 支持的模型 ID 可以在模型对话页面查到。报错四OAuth 相关错误Error: OAuth token expired or invalid如果你用的是某些需要 OAuth 的模型服务token 过期会报这个。换成 API Key 方式接入 TaoToken 就不会有这个问题因为 TaoToken 用的是标准的 Bearer Token 认证。报错五智能体跑很久不返回如果调用超过 1 分钟还没结果可能是陷入了死循环。DeepAgents 默认的系统提示词会引导模型先规划再执行但如果你自定义的 system_prompt 太模糊模型可能会反复调用同一个工具。解决办法是检查你的提示词明确告诉它完成任务后必须输出最终答案。另外可以用 LangSmith 做链路追踪看看卡在哪一步。报错六子智能体调用失败ValueError: subagent xxx not found如果你在subagents参数里配置了子智能体但主智能体调用时找不到检查子智能体的name字段是否和调用时一致。子智能体配置必须包含name、description、prompt三个字段缺一个都会导致注册失败。报错七文件写入失败PermissionError: [Errno 13] Permission deniedDeepAgents 默认用的是内存级虚拟文件系统不会真的写到你本地磁盘。如果你配置了backend指向本地路径确保那个目录有写权限。本地测试建议先用默认的内存后端避免权限问题干扰。排查问题的通用思路是先隔离变量。把模型调用、工具调用、智能体创建分开测哪一步报错就集中解决那一步。不要一上来就怀疑框架有问题大部分情况都是配置或环境的问题。6. 从跑通到用好下一步怎么走第一个智能体跑通之后你可能会想接下来怎么把它用在实际项目里这里给几个方向。第一把系统提示词写得更具体。默认提示词是通用的针对你的业务场景定制之后效果会明显提升。比如你做代码审查就在提示词里明确审查标准、输出格式、常见问题清单。提示词的质量直接决定智能体的表现上限。第二学会用子智能体做分工。当任务涉及多个独立领域时给每个领域配一个专门的子智能体主智能体只负责调度和汇总。这样既能隔离上下文又能让每个子智能体用最适合的模型和工具。比如一个负责查官方文档一个负责搜社区实践最后主智能体对比两者输出。第三配置持久化存储。本地测试用InMemorySaver就够了但生产环境需要把状态存到数据库或 Redis这样智能体中断后可以恢复多个会话之间也能共享文件。DeepAgents 支持切换StateBackend具体配置可以参考接入文档。第四接入可观测性。LangSmith 能让你看到每一步的输入输出、token 消耗、耗时排查问题时非常有用。尤其是智能体行为不符合预期时看 trace 比看日志高效得多。如果你在配置模型或排查报错时遇到问题可以直接去 TaoToken 的 API Keys 页面检查 Key 状态或者翻一下接入文档里的示例。想先体验一下模型对话效果可以用模型对话页面快速测试。如果打算长期做编码类智能体Coding Plan 会更划算。最后说一个实用技巧DeepAgents 的interrupt_on参数可以让你在关键节点暂停智能体等人工确认后再继续。比如删除文件、执行 shell 命令这类高风险操作配置成需要人工审批能避免很多意外。这个功能在自动化运维场景下特别有用值得花时间研究一下。