使用deepAgents框架加载Skills完成网络文档查询功能

1. 背景介绍本文演示了如何基于deepagents.create_deep_agent构建一个支持Skills 渐进披露机制的 Agent。目标是提出 LangGraph 相关问题示例How to define a code evaluatorAgent 从 Skills 列表识别到langgraph-docs技能读取技能说明后按步骤调用网页抓取工具检索 LangGraph/LangSmith 文档最终产出基于文档证据的回答。skill把“领域工作流”固化到SKILL.md让模型在推理时按标准流程执行而不是每次临时发挥。2. 样例代码2.1 依赖版本当前环境deepagents0.4.4 langgraph1.0.8 langchain1.2.10 langchain-core1.2.16 langchain-openai1.1.10 openai2.24.02.2 格式化后的样例代码fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportFilesystemBackendfromlangchain_openai.chat_models.baseimportChatOpenAIfromsrc.langchain_deepagent.fetch_url_toolimportfetch_url_toolfromdeepagents.middlewareimportSkillsMiddleware base_config{model:claude-sonnet-4.6,base_url:***“,api_key:***,temperature:0,presence_penalty:0.2,}modelChatOpenAI(**base_config)# 关键使用 FilesystemBackend才能从磁盘读取 skills 目录backendFilesystemBackend(root_dir/Users/user/PycharmProjects/lab/src/langchain_deepagent/)skills_middlewareSkillsMiddleware(backendbackend,sources[skills_dir],)agentcreate_deep_agent(modelmodel,tools[fetch_url_tool],backendbackend,middleware[skills_middleware],system_prompt,)responseagent.invoke(input{messages:[{role:user,content:tell me in langgraph How to define a code evaluator,}]})print(response)2.3 核心类/方法说明create_deep_agent(...)作用组装 Deep Agent模型 工具 默认中间件栈 自定义中间件。关键参数model支持工具调用的 Chat Modeltools可被模型调用的工具集合backend文件/状态后端middleware附加中间件本例手动注入SkillsMiddleware。FilesystemBackend(root_dir...)作用把文件读取能力绑定到指定目录根SkillsMiddleware会通过 backend 的ls_info/download_files扫描并读取SKILL.md。SkillsMiddleware(backend, sources)作用before_agent从sources加载技能元数据name/description/allowed-tools/pathwrap_model_call把技能列表与使用规范注入 system prompt渐进披露。sources技能来源目录列表后定义来源对同名 skill 有覆盖优先级last one wins。fetch_url_tool(url: str)作用拉取 URL 文本并转为 markdown供模型进一步选择和总结。3. Skills 执行流程说明结合交互消息3.1 加载与注入流程create_deep_agent 初始化组装中间件SkillsMiddleware.before_agent扫描 sources: skills_dir发现 langgraph-docs/SKILL.md解析 frontmatter: name/description/allowed-tools写入 state.skills_metadatawrap_model_call 注入 Skills System 到 system prompt在input_output中可见已注入的技能提示Available Skills中出现langgraph-docs明确给出- Allowed tools: fetch_url明确给出- Read .../langgraph-docs/SKILL.md for full instructions。这说明系统已完成“技能目录发现 元数据装配 系统提示注入”。3.2 按技能步骤执行基于日志证据langgraph-docs/SKILL.md定义的步骤是先抓取https://docs.langchain.com/llms.txt文档索引选取 2~4 个相关文档抓取这些文档回答用户问题。基于模型请求与响应消息核心交互如下用户消息tell me in langgraph How to define a code evaluator模型先发起read_file(.../langgraph-docs/SKILL.md)读取技能内容然后调用fetch_url_tool(urlhttps://docs.langchain.com/llms.txt)获取文档索引再调用fetch_url_tool抓取目标页面如 code-evaluator 相关文档最后再组织为回答输出。ModelTools(fetch_url_tool/read_file)SkillsMiddlewareDeepAgentUserModelTools(fetch_url_tool/read_file)SkillsMiddlewareDeepAgentUserask: how to define a code evaluatorbefore_agent()skills_metadata(langgraph-docs)system prompt Skills Systemread_file(SKILL.md)skill workflowfetch_url_tool(llms.txt)docs indexfetch_url_tool(selected docs)relevant docs contentfinal answerresponse3.3 交互消息列表3.2 完整交互消息列表简化内容说明以下严格按input_output出现顺序列出保留完整消息顺序只对每条消息内容做压缩不做流程抽象。A. System Message5 条 text blocktypetextDeep Agent 基础行为规范Core Behavior / Professional Objectivity / Doing Tasks / Progress Updates。typetextwrite_todos工具说明何时使用、何时不使用、不要并行调用。typetext通用约束先读后改、遵循现有风格和文件系统工具说明ls/read_file/write_file/edit_file/glob/grep。typetexttask子代理工具说明适用场景、生命周期、并行建议、非适用场景。typetextSkills System 注入内容包含skills_dir、可用技能langgraph-docs、Allowed tools: fetch_url、以及 progressive disclosure 使用方法。B. 会话消息9 条HumanMessagetell me in langgraph How to define a code evaluatorAIMessagetool callread_file(file_path/Users/PycharmProjects/lab/src/langchain_deepagent/skills_dir/langgraph-docs/SKILL.md)ToolMessageread_file返回langgraph-docs/SKILL.md内容frontmatter 4 步说明先读llms.txt再选文档再抓取再回答。AIMessagetool callfetch_url_tool(urlhttps://docs.langchain.com/llms.txt)ToolMessagefetch_url_tool返回LangChain 文档索引# Docs by LangChain包含大量可选文档链接。AIMessagetool call2 个并行请求fetch_url_tool(urlhttps://docs.langchain.com/langsmith/code-evaluator-sdk.md)fetch_url_tool(urlhttps://docs.langchain.com/langsmith/code-evaluator-ui.md)ToolMessagefetch_url_tool返回code-evaluator-sdk.md相关内容如何通过 SDK 定义 code evaluator。ToolMessagefetch_url_tool返回code-evaluator-ui.md相关内容如何通过 UI 定义 code evaluator。AIMessage最终回答汇总 SDK/UI 两条路径给出完整的 code evaluator 定义说明。为便于核对每条消息的完整原文保留在第 5 节“交互消息完整原文”。4. 注意事项必须指定backend不指定时create_deep_agent默认使用StateBackend内存态这会导致无法从磁盘读取skills_dir/.../SKILL.md从而出现“读不到 skills 文件”的问题。避免 skills 配置重复注入你当前是middleware[SkillsMiddleware(...)]手动注入若同时又给create_deep_agent(skills[...])框架会再注入一层SkillsMiddleware可能导致提示词重复或行为冲突建议二选一。模型与工具命名一致性SKILL.md中写的是allowed-tools: fetch_url代码里注册工具名是fetch_url_tool函数名决定工具名名称不一致时模型可能优先尝试不存在的工具名建议统一例如把函数命名成fetch_url。模型选择建议要优先选“工具调用稳定、遵循步骤能力强”的模型对于 Skills Tool 混合场景模型若函数调用能力弱会出现“会识别 skill 但不按 skill 调工具”的问题。Skill 文件规范每个技能目录必须包含SKILL.mdfrontmatter 至少包含name、description建议补全allowed-tools、compatibility提升模型选择技能与工具的准确率。