1. 为什么你的 deep agent 加载不上 SKILL如果你最近在 LangChain 里折腾 deep agent大概率会遇到一个很具体的场景代码里明明写了skills[./skills]启动之后 agent 却像没看见一样问它问题还是走通用推理压根不调用你写好的 SKILL。更让人抓狂的是控制台不报错日志也不提示你只能靠猜。这个问题的核心在于deep agent 加载 SKILL 不是「把文件夹路径塞进去」就完事。它依赖三个东西同时成立SKILL 目录结构符合约定、backend 能真实访问本地文件、settings.json 里的模型通道配置正确。任何一环断了SKILL 就是静默失效。我这次要解决的就是「一次配置跑通」这件事。目标很明确在本地开发环境里用一份可复制的settings.json骨架把 deep agent 和 SKILL 的加载链路打通启动后能确认 SKILL 注册成功并且 deep agent 真的能调用它。适合正在做本地 Agent 开发、被 SKILL 加载卡住的同学也适合刚接触 deep agent、想先跑通最小闭环的人。SKILL 这个概念本身不复杂你可以把它理解成「给 agent 准备的能力卡片」——每个 SKILL 是一个文件夹里面放一个SKILL.md描述这个能力干什么、怎么用再配上需要的脚本。agent 在需要的时候按需加载而不是把所有工具一次性塞进上下文。deep agent 对 SKILL 的支持就是让这套机制原生跑起来。但原生支持不等于零配置。下面我把整条链路拆开讲从统一 Key 通道到 settings.json 骨架再到验证和排障。2. TaoToken 前置统一 Key 与 API 通道在写 settings.json 之前先把模型通道这件事定下来。本地开发最容易乱的地方就是 Key 管理今天用这个平台的 Key明天换那个模型的 base_url配置文件改来改去最后自己都记不清哪个 Key 对应哪个通道。我的做法是走一个统一的 API 通道把模型调用收敛到一个入口。TaoToken 提供的就是这个能力官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用一套 Key 去访问不同的模型deep agent 里的ChatOpenAI只要把base_url指向这个通道模型切换就不用动业务代码。具体操作上你需要先拿到一个 API Key。登录之后进控制台在 API Keys 页面创建一个新的 Key复制出来备用。这个 Key 后面会写进 settings.json 或者环境变量里。这里有个细节要注意deep agent 底层用的是ChatOpenAI这类兼容 OpenAI 协议的客户端所以你的通道必须兼容 OpenAI 的/chat/completions接口格式。TaoToken 的 API 入口就是按这个协议来的直接把base_url设成https://taotoken.net/api即可不需要额外适配层。如果你后面要长期跑编码类任务或者 Agent 工作流可以考虑 Coding Plan它在持续调用场景下更省心。但本篇先聚焦最小闭环用按量 Key 就能跑通。3. 可复制的 settings.json 配置骨架现在进入正题。deep agent 加载 SKILL 的配置我建议拆成两部分一部分是settings.json管模型通道和运行参数另一部分是 agent 创建代码管 SKILL 目录和 backend。这样职责清晰出问题好定位。先看settings.json骨架。放在项目根目录{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model_name: Doubao-Seed-2.0-pro, temperature: 0 }, agent: { skills_dir: ./skills, virtual_mode: true, root_dir: ., checkpointer: memory, thread_id: local-dev-1 }, runtime: { python_env: auto, log_level: INFO } }逐项说明一下。base_url指向 TaoToken 的 API 入口api_key_env表示 Key 从环境变量TAOTOKEN_API_KEY读取不要把 Key 硬编码进文件。model_name按你实际要用的模型填这里用豆包系模型举例因为它兼容 OpenAI 协议ChatOpenAI能直接调。skills_dir是 SKILL 的根目录virtual_mode和root_dir对应LocalShellBackend的参数决定 backend 能不能访问本地文件。checkpointer设成memory表示用内存记忆本地调试够用。thread_id是会话标识invoke 时传给 config。然后是 agent 创建代码读取这份配置import os import json from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import LocalShellBackend from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import InMemorySaver load_dotenv() with open(settings.json, r, encodingutf-8) as f: cfg json.load(f) model_cfg cfg[model] agent_cfg cfg[agent] model ChatOpenAI( api_keyos.getenv(model_cfg[api_key_env]), model_namemodel_cfg[model_name], base_urlmodel_cfg[base_url], temperaturemodel_cfg[temperature], ) agent create_deep_agent( modelmodel, backendLocalShellBackend( root_diragent_cfg[root_dir], virtual_modeagent_cfg[virtual_mode], ), skills[agent_cfg[skills_dir]], checkpointerInMemorySaver(), system_prompt你是一个智能助手优先使用已注册的 SKILL 完成任务。, )关键点有三个。第一LocalShellBackend是加载本地 SKILL 的核心没有它 agent 访问不到本地文件SKILL 自然加载不了。第二skills参数传的是目录列表deep agent 会扫描这个目录下的 SKILL 文件夹。第三system_prompt里明确提示优先用 SKILL能提高调用命中率。SKILL 目录本身要符合约定。每个 SKILL 是一个小写命名的文件夹里面至少有一个SKILL.mdskills/ query-course/ SKILL.md run.py convert-id/ SKILL.md convert.pySKILL.md里写清楚这个技能的名称、用途、输入输出。deep agent 读取它来决定什么时候加载。文件夹名必须小写大写命名目前识别不了这是实测踩过的坑。4. 验证请求与成功结果配置写完怎么确认 SKILL 真的注册成功了不要靠感觉用两个动作验证。第一个动作启动时打印已注册的 SKILL 列表。deep agent 创建后可以检查 agent 的 skills 属性print(registered skills:, agent.skills)如果输出里包含你目录下的 SKILL 名称说明扫描和注册这一步过了。如果输出是空列表说明目录结构或 backend 有问题直接跳到下一节排障。第二个动作发一个必须依赖 SKILL 才能答对的请求。比如你有一个convert-id技能负责把 ID 转成人名。构造一个只有调用该技能才能得到正确结果的输入results agent.invoke( {messages: [{role: user, content: 查询 ID 1001 对应的名称}]}, config{configurable: {thread_id: local-dev-1}}, ) for message in results[messages]: message.pretty_print()成功的结果长这样agent 的中间步骤里会出现调用convert-id技能的动作最终返回的是人名而不是原始 ID。如果它直接返回1001或者答非所问说明 SKILL 没被调用。这里有个经验deep agent 和开箱即用的 Agent 产品不一样它更像脚手架。同样的 SKILL在封装好的产品里会自动做 ID 到人名的关联转换但在 deep agent 里如果你不写系统提示词引导它可能只返回原始 ID。所以验证时要把system_prompt写清楚明确告诉它「如果结果是 ID就调用对应 SKILL 转换」。跑通这两个动作最小闭环就成了。启动无报错、SKILL 列表非空、请求能触发技能调用三件事同时满足才算真的加载成功。5. 本篇常见错排查下面这几个错是我在本地环境里实际遇到过的按出现频率排。SKILL 列表为空但目录明明存在。先查文件夹命名必须全小写。QueryCourse这种驼峰命名识别不了改成query-course。再查SKILL.md是否存在且文件名大小写正确有些系统对大小写不敏感但 deep agent 的扫描逻辑是敏感的。agent 能启动但请求时不调用 SKILL。大概率是system_prompt没引导。deep agent 不会无条件加载所有技能它根据任务和提示词判断。在系统提示里明确「优先使用已注册 SKILL」「遇到 ID 先转换」这类指令命中率会明显提升。报错找不到模型或 401。检查TAOTOKEN_API_KEY环境变量是否真的注入了。load_dotenv()要在读取配置之前调用.env文件里写TAOTOKEN_API_KEY你的Key。另外确认base_url是https://taotoken.net/api不要多加路径后缀。Windows 下 SKILL 里的脚本跑不起来。MacOS 通常不用额外指定 Python 环境变量但 Windows 必须手动配。如果 SKILL 里有 Python 脚本确认python在 PATH 里或者用绝对路径调用解释器。这一步不配技能加载了也执行不了。backend 访问不到文件。LocalShellBackend的root_dir要设成项目根目录virtual_mode设true时路径解析走虚拟模式。如果你把root_dir设错SKILL 目录相对路径就找不到。建议root_dir.skills_dir./skills保持相对关系一致。改了配置不生效。deep agent 创建时读取一次配置改完settings.json要重启进程。热更新不适用于 SKILL 目录扫描别指望改完文件就自动重载。排障时如果卡在接入层可以直接看接入文档里面有通道配置的细节。验证模型通道是否通用模型对话页面发一条测试消息最快能排除是 Key 问题还是代码问题。6. 下一步怎么走最小闭环跑通之后你可以往两个方向走。一个是把 SKILL 做厚每个技能写清楚SKILL.md的输入输出契约让 agent 判断更准。另一个是把模型通道固定下来长期编码或 Agent 任务用 Coding Plan省去反复换 Key 的麻烦。回到最开始那个问题deep agent 加载 SKILL 失败本质不是代码写错而是链路里某个环节静默断了。把 settings.json 骨架、backend、目录命名、系统提示这四件事对齐一次配置就能跑通。我试过把这套骨架直接复制到新项目改一下skills_dir和模型名就能用省掉了反复试错的时间。如果你还没拿到 Key先去控制台创建一个再回来对着骨架填。跑通之后把agent.skills的输出截图存下来下次换环境时对比一下能快速判断是配置问题还是环境问题。
LangChain 加载 deep agent 与 SKILL：settings.json 配置骨架与验证
1. 为什么你的 deep agent 加载不上 SKILL如果你最近在 LangChain 里折腾 deep agent大概率会遇到一个很具体的场景代码里明明写了skills[./skills]启动之后 agent 却像没看见一样问它问题还是走通用推理压根不调用你写好的 SKILL。更让人抓狂的是控制台不报错日志也不提示你只能靠猜。这个问题的核心在于deep agent 加载 SKILL 不是「把文件夹路径塞进去」就完事。它依赖三个东西同时成立SKILL 目录结构符合约定、backend 能真实访问本地文件、settings.json 里的模型通道配置正确。任何一环断了SKILL 就是静默失效。我这次要解决的就是「一次配置跑通」这件事。目标很明确在本地开发环境里用一份可复制的settings.json骨架把 deep agent 和 SKILL 的加载链路打通启动后能确认 SKILL 注册成功并且 deep agent 真的能调用它。适合正在做本地 Agent 开发、被 SKILL 加载卡住的同学也适合刚接触 deep agent、想先跑通最小闭环的人。SKILL 这个概念本身不复杂你可以把它理解成「给 agent 准备的能力卡片」——每个 SKILL 是一个文件夹里面放一个SKILL.md描述这个能力干什么、怎么用再配上需要的脚本。agent 在需要的时候按需加载而不是把所有工具一次性塞进上下文。deep agent 对 SKILL 的支持就是让这套机制原生跑起来。但原生支持不等于零配置。下面我把整条链路拆开讲从统一 Key 通道到 settings.json 骨架再到验证和排障。2. TaoToken 前置统一 Key 与 API 通道在写 settings.json 之前先把模型通道这件事定下来。本地开发最容易乱的地方就是 Key 管理今天用这个平台的 Key明天换那个模型的 base_url配置文件改来改去最后自己都记不清哪个 Key 对应哪个通道。我的做法是走一个统一的 API 通道把模型调用收敛到一个入口。TaoToken 提供的就是这个能力官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用一套 Key 去访问不同的模型deep agent 里的ChatOpenAI只要把base_url指向这个通道模型切换就不用动业务代码。具体操作上你需要先拿到一个 API Key。登录之后进控制台在 API Keys 页面创建一个新的 Key复制出来备用。这个 Key 后面会写进 settings.json 或者环境变量里。这里有个细节要注意deep agent 底层用的是ChatOpenAI这类兼容 OpenAI 协议的客户端所以你的通道必须兼容 OpenAI 的/chat/completions接口格式。TaoToken 的 API 入口就是按这个协议来的直接把base_url设成https://taotoken.net/api即可不需要额外适配层。如果你后面要长期跑编码类任务或者 Agent 工作流可以考虑 Coding Plan它在持续调用场景下更省心。但本篇先聚焦最小闭环用按量 Key 就能跑通。3. 可复制的 settings.json 配置骨架现在进入正题。deep agent 加载 SKILL 的配置我建议拆成两部分一部分是settings.json管模型通道和运行参数另一部分是 agent 创建代码管 SKILL 目录和 backend。这样职责清晰出问题好定位。先看settings.json骨架。放在项目根目录{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model_name: Doubao-Seed-2.0-pro, temperature: 0 }, agent: { skills_dir: ./skills, virtual_mode: true, root_dir: ., checkpointer: memory, thread_id: local-dev-1 }, runtime: { python_env: auto, log_level: INFO } }逐项说明一下。base_url指向 TaoToken 的 API 入口api_key_env表示 Key 从环境变量TAOTOKEN_API_KEY读取不要把 Key 硬编码进文件。model_name按你实际要用的模型填这里用豆包系模型举例因为它兼容 OpenAI 协议ChatOpenAI能直接调。skills_dir是 SKILL 的根目录virtual_mode和root_dir对应LocalShellBackend的参数决定 backend 能不能访问本地文件。checkpointer设成memory表示用内存记忆本地调试够用。thread_id是会话标识invoke 时传给 config。然后是 agent 创建代码读取这份配置import os import json from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import LocalShellBackend from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import InMemorySaver load_dotenv() with open(settings.json, r, encodingutf-8) as f: cfg json.load(f) model_cfg cfg[model] agent_cfg cfg[agent] model ChatOpenAI( api_keyos.getenv(model_cfg[api_key_env]), model_namemodel_cfg[model_name], base_urlmodel_cfg[base_url], temperaturemodel_cfg[temperature], ) agent create_deep_agent( modelmodel, backendLocalShellBackend( root_diragent_cfg[root_dir], virtual_modeagent_cfg[virtual_mode], ), skills[agent_cfg[skills_dir]], checkpointerInMemorySaver(), system_prompt你是一个智能助手优先使用已注册的 SKILL 完成任务。, )关键点有三个。第一LocalShellBackend是加载本地 SKILL 的核心没有它 agent 访问不到本地文件SKILL 自然加载不了。第二skills参数传的是目录列表deep agent 会扫描这个目录下的 SKILL 文件夹。第三system_prompt里明确提示优先用 SKILL能提高调用命中率。SKILL 目录本身要符合约定。每个 SKILL 是一个小写命名的文件夹里面至少有一个SKILL.mdskills/ query-course/ SKILL.md run.py convert-id/ SKILL.md convert.pySKILL.md里写清楚这个技能的名称、用途、输入输出。deep agent 读取它来决定什么时候加载。文件夹名必须小写大写命名目前识别不了这是实测踩过的坑。4. 验证请求与成功结果配置写完怎么确认 SKILL 真的注册成功了不要靠感觉用两个动作验证。第一个动作启动时打印已注册的 SKILL 列表。deep agent 创建后可以检查 agent 的 skills 属性print(registered skills:, agent.skills)如果输出里包含你目录下的 SKILL 名称说明扫描和注册这一步过了。如果输出是空列表说明目录结构或 backend 有问题直接跳到下一节排障。第二个动作发一个必须依赖 SKILL 才能答对的请求。比如你有一个convert-id技能负责把 ID 转成人名。构造一个只有调用该技能才能得到正确结果的输入results agent.invoke( {messages: [{role: user, content: 查询 ID 1001 对应的名称}]}, config{configurable: {thread_id: local-dev-1}}, ) for message in results[messages]: message.pretty_print()成功的结果长这样agent 的中间步骤里会出现调用convert-id技能的动作最终返回的是人名而不是原始 ID。如果它直接返回1001或者答非所问说明 SKILL 没被调用。这里有个经验deep agent 和开箱即用的 Agent 产品不一样它更像脚手架。同样的 SKILL在封装好的产品里会自动做 ID 到人名的关联转换但在 deep agent 里如果你不写系统提示词引导它可能只返回原始 ID。所以验证时要把system_prompt写清楚明确告诉它「如果结果是 ID就调用对应 SKILL 转换」。跑通这两个动作最小闭环就成了。启动无报错、SKILL 列表非空、请求能触发技能调用三件事同时满足才算真的加载成功。5. 本篇常见错排查下面这几个错是我在本地环境里实际遇到过的按出现频率排。SKILL 列表为空但目录明明存在。先查文件夹命名必须全小写。QueryCourse这种驼峰命名识别不了改成query-course。再查SKILL.md是否存在且文件名大小写正确有些系统对大小写不敏感但 deep agent 的扫描逻辑是敏感的。agent 能启动但请求时不调用 SKILL。大概率是system_prompt没引导。deep agent 不会无条件加载所有技能它根据任务和提示词判断。在系统提示里明确「优先使用已注册 SKILL」「遇到 ID 先转换」这类指令命中率会明显提升。报错找不到模型或 401。检查TAOTOKEN_API_KEY环境变量是否真的注入了。load_dotenv()要在读取配置之前调用.env文件里写TAOTOKEN_API_KEY你的Key。另外确认base_url是https://taotoken.net/api不要多加路径后缀。Windows 下 SKILL 里的脚本跑不起来。MacOS 通常不用额外指定 Python 环境变量但 Windows 必须手动配。如果 SKILL 里有 Python 脚本确认python在 PATH 里或者用绝对路径调用解释器。这一步不配技能加载了也执行不了。backend 访问不到文件。LocalShellBackend的root_dir要设成项目根目录virtual_mode设true时路径解析走虚拟模式。如果你把root_dir设错SKILL 目录相对路径就找不到。建议root_dir.skills_dir./skills保持相对关系一致。改了配置不生效。deep agent 创建时读取一次配置改完settings.json要重启进程。热更新不适用于 SKILL 目录扫描别指望改完文件就自动重载。排障时如果卡在接入层可以直接看接入文档里面有通道配置的细节。验证模型通道是否通用模型对话页面发一条测试消息最快能排除是 Key 问题还是代码问题。6. 下一步怎么走最小闭环跑通之后你可以往两个方向走。一个是把 SKILL 做厚每个技能写清楚SKILL.md的输入输出契约让 agent 判断更准。另一个是把模型通道固定下来长期编码或 Agent 任务用 Coding Plan省去反复换 Key 的麻烦。回到最开始那个问题deep agent 加载 SKILL 失败本质不是代码写错而是链路里某个环节静默断了。把 settings.json 骨架、backend、目录命名、系统提示这四件事对齐一次配置就能跑通。我试过把这套骨架直接复制到新项目改一下skills_dir和模型名就能用省掉了反复试错的时间。如果你还没拿到 Key先去控制台创建一个再回来对着骨架填。跑通之后把agent.skills的输出截图存下来下次换环境时对比一下能快速判断是配置问题还是环境问题。
