大模型开发手记（十三）：langchain skills（下）：构建skills架构agent实战

目录前言一、整体架构预览二、实战2.1 第一步定义Skill文件酒店预订Skill景点推荐Skill2.2 第二步编写Skill加载工具2.3 第三步构建Skill中间件2.4 第四步创建agent.py第四步运行与验证三、扩展思路前言在上一篇博客中我们深入理解了Agent Skill的核心概念——它是一种通过渐进式披露来扩展Agent专业能力的模块化方式。理论说完了今天我们就来真刀真枪地实现一个。我们的目标构建一个旅行助手Agent它拥有两个独立的Skill酒店预订Skill包含酒店预订的业务规则、政策、操作流程。景点推荐Skill包含热门景点的介绍、推荐逻辑、注意事项。Agent启动时只知道这两个Skill的名字和一句话描述只有当你问及具体问题时它才会动态加载对应Skill的详细内容。一、整体架构预览travel-agent/├── skills/# 存放所有Skill│ ├── hotel_booking/# 酒店预订Skill目录│ │ ├── skill.json# 元数据name, description│ │ └── content.md# 详细内容业务规则、示例等│ └── attraction/# 景点推荐Skill目录│ ├── skill.json │ └── content.md ├── agent.py# 主程序构建Agent、加载Skill└── skill_loader.py# 工具函数从文件系统加载Skill核心流程Agent启动时扫描skills/目录读取所有子目录中的skill.json文件提取元数据名称描述。将这些元数据注入到系统提示词中让Agent“知道”自己有哪些能力。提供load_skill工具Agent可以在需要时调用它传入技能名称从而加载对应目录下content.md的完整内容。通过中间件自动完成系统提示词的注入。二、实战2.1 第一步定义Skill文件每个Skill都是一个独立的目录元数据和内容分离。未来新增Skill只需新建一个子目录并放入对应的skill.json和content.md即可。酒店预订Skill先定义元数据我们先创建skills/hotel_booking/skill.json这是酒店预订Skill的元数据{name:hotel_booking,description:酒店预订助手支持查询房型、预订流程、取消政策等。}再创建同目录下的skills/hotel_booking/content.md这是详细的技能内容# 酒店预订助手## 可用的酒店-海景大床房每晚680元含双早-山景双床房每晚520元含单早-行政套房每晚1280元含双早行政酒廊权益## 预订流程1.确认入住日期和离店日期2.选择合适的房型3.提供入住人姓名和联系电话4.确认订单后用户需支付30%定金5.入住当天18:00前可免费取消之后取消收取首晚房费## 注意事项-每间房最多入住2名成人1名儿童-加床服务每晚200元-宠物不可入内## 特殊政策-连住3晚以上可享受9折优惠-金卡会员可享延迟退房至14:00## 示例对话用户我想订一间海景大床房住两晚 助手好的海景大床房每晚680元两晚共1360元。请问您计划什么时候入住景点推荐Skill创建元数据skills/attraction/skill.json{name:attraction,description:城市景点推荐助手提供热门景点、游玩路线、门票信息等。}创建content.md文件存储详细的技能内容skills/attraction/content.md# 景点推荐助手## 热门景点### 滨海公园-门票免费-开放时间全天-推荐理由城市地标适合散步、骑行傍晚看日落### 古城文化街-门票30元-开放时间09:00-21:00-推荐理由明清建筑风格汇聚特色小吃和手工艺品### 海洋世界-门票成人180元儿童120元-开放时间09:00-17:30-推荐理由适合亲子游有海豚表演和海底隧道## 推荐逻辑-亲子游优先推荐海洋世界-文艺青年优先推荐古城文化街-休闲放松优先推荐滨海公园## 注意事项-节假日期间景点人流量大建议提前购票-古城文化街周末有民俗表演下午2点和4点各一场## 示例对话用户带孩子去哪里玩比较好 助手如果带孩子的话强烈推荐海洋世界里面有海豚表演和海底隧道孩子会很喜欢。成人票180元儿童票120元开放时间是09:00到17:30。2.2 第二步编写Skill加载工具创建skill_loader.py负责扫描目录、加载元数据和按需加载内容importjsonfrompathlibimportPathfromtypingimportDict,List,Optionalfromlangchain.toolsimporttool# Skill根目录SKILLS_ROOTPath(__file__).parent/skillsclassSkillLoader:负责加载Skill元数据和内容def__init__(self,skills_root:Path):self.skills_rootskills_root self._metadata_cache:Optional[List[Dict[str,str]]]Nonedefload_all_metadata(self)-List[Dict[str,str]]:扫描所有Skill目录返回元数据列表ifself._metadata_cacheisnotNone:returnself._metadata_cache metadata_list[]forskill_dirinself.skills_root.iterdir():ifnotskill_dir.is_dir():continuejson_pathskill_dir/skill.jsonifnotjson_path.exists():continuewithopen(json_path,r,encodingutf-8)asf:datajson.load(f)metadata_list.append({name:data[name],description:data[description]})self._metadata_cachemetadata_listreturnmetadata_listdefload_full_content(self,skill_name:str)-Optional[str]:根据技能名称加载完整的content.md内容forskill_dirinself.skills_root.iterdir():ifnotskill_dir.is_dir():continuejson_pathskill_dir/skill.jsonifnotjson_path.exists():continuewithopen(json_path,r,encodingutf-8)asf:datajson.load(f)ifdata[name]skill_name:content_pathskill_dir/content.mdifcontent_path.exists():withopen(content_path,r,encodingutf-8)ascf:returnf# 已加载技能{skill_name}\n\n{cf.read()}else:returnf技能{skill_name}缺少 content.md 文件returnNone# 全局加载器实例loaderSkillLoader(SKILLS_ROOT)tooldefload_skill(skill_name:str)-str:按需加载技能的详细内容。 当你需要某个技能的具体信息如业务规则、操作流程、详细知识时 调用此工具加载对应技能。 Args: skill_name: 技能名称可选值由系统提示词中的可用技能列表提供。 contentloader.load_full_content(skill_name)ifcontentisNone:available, .join(s[name]forsinloader.load_all_metadata())returnf未找到名为{skill_name}的技能。可用技能{available}returncontent这个类做了几件事load_all_metadata扫描skills/下的所有子目录读取skill.json提取name和description。load_full_content根据技能名称找到对应的目录读取其中的content.md文件返回完整的Markdown内容。通过tool装饰器将load_skill暴露给Agent使用。2.3 第三步构建Skill中间件中间件负责在模型调用前将技能元数据注入系统提示词。通过模型上下文的方式wrap_model_call中间件在模型调用前将所有skills的元数据名称描述注入到系统提示词中让agent清晰地知道自己有哪些技能。importuuidfromtypingimportCallablefromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportAgentMiddleware,ModelRequest,ModelResponsefromlangchain.messagesimportSystemMessagefromlangchain_openaiimportChatOpenAIfromlanggraph.checkpoint.memoryimportInMemorySaverfromskill_loaderimportloader,load_skillclassSkillMiddleware(AgentMiddleware):将技能列表注入系统提示词的中间件# 注册工具让Agent可以调用load_skilltools[load_skill]def__init__(self):# 启动时加载所有技能的元数据self.skills_metadataloader.load_all_metadata()self.skills_promptself._build_skills_prompt()def_build_skills_prompt(self)-str:生成技能列表的描述文本ifnotself.skills_metadata:return当前没有可用技能。lines[## 可用技能列表\n]forskillinself.skills_metadata:lines.append(f- **{skill[name]}**{skill[description]})lines.append(\n当你需要某个技能的详细内容时请调用 load_skill 工具加载。)return\n.join(lines)defwrap_model_call(self,request:ModelRequest,handler:Callable[[ModelRequest],ModelResponse],)-ModelResponse:在调用模型前将技能描述追加到系统消息中# 构建追加的内容addendumf\n\n{self.skills_prompt}# 获取原有系统消息的内容块并追加新内容original_blocksrequest.system_message.content_blocks new_blocksoriginal_blocks[{type:text,text:addendum}]new_system_messageSystemMessage(contentnew_blocks)# 用新的系统消息覆盖原请求modified_requestrequest.override(system_messagenew_system_message)returnhandler(modified_request)2.4 第四步创建agent.py创建agent配置中间件在invoke或者stream 启动时会将 所有skills的元数据名称描述注入到系统提示词中然后agent运行中会调用工具将skills核心内容加载到上下文中发送给大模型defmain():# 初始化模型请替换为你的API Key或使用其他模型modelChatOpenAI(modelgpt-4o-mini)# 创建Agent使用我们的中间件agentcreate_agent(model,system_prompt你是一个友好的旅行助手帮助用户解决酒店预订和景点推荐等问题。,middleware[SkillMiddleware()],checkpointerInMemorySaver(),)# 对话线程ID用于维护状态thread_idstr(uuid.uuid4())config{configurable:{thread_id:thread_id}}# 测试1询问酒店预订print( 测试酒店预订 )resultagent.invoke({messages:[{role:user,content:我想订一间海景大床房住两晚多少钱}]},config)formsginresult[messages]:ifhasattr(msg,pretty_print):msg.pretty_print()else:print(f{msg.type}:{msg.content})print(\n*50\n)# 测试2询问景点推荐print( 测试景点推荐 )resultagent.invoke({messages:[{role:user,content:带孩子去哪里玩比较好}]},config)formsginresult[messages]:ifhasattr(msg,pretty_print):msg.pretty_print()else:print(f{msg.type}:{msg.content})if__name____main__:main()第四步运行与验证测试1的输出Human:我想订一间海景大床房住两晚多少钱 AI:[调用工具 load_skill(skill_namehotel_booking)]Tool:[返回酒店Skill的完整Markdown内容]AI:根据酒店政策海景大床房每晚680元两晚总价为1360元。如需预订请提供入住日期和联系人信息。测试2的输出Human:带孩子去哪里玩比较好 AI:[调用工具 load_skill(skill_nameattraction)]Tool:[返回景点Skill的完整Markdown内容]AI:如果您带孩子出行我强烈推荐海洋世界这里有海豚表演和海底隧道非常适合亲子游玩。成人票180元儿童票120元开放时间为09:00-17:30。关键观察点初始对话Agent的系统提示词中只包含两个Skill的简短描述没有加载任何详细内容。按需加载当用户提出具体问题后Agent先判断需要哪个Skill然后调用load_skill获取完整内容。上下文精简整个对话历史中只加载了被使用的Skill的内容另一个Skill从未被加载。三、扩展思路这个基础实现已经足够演示核心机制但在实际项目中你可能会需要以下增强支持动态刷新Skill如果Skill目录下的文件在运行时被修改你可以让中间件在wrap_model_call中重新读取元数据或者提供一个reload_skills工具供管理员调用。更复杂的加载逻辑当前load_skill一次性返回整个content.md。如果Skill内容非常庞大如完整的产品手册你可以改为分块返回或者让Agent在Skill内进行“二次搜索”。Markdown格式天然支持分节你可以先返回目录再让Agent根据需要加载具体章节。为Skill关联工具有些Skill可能需要配套的工具比如酒店预订Skill应该有一个make_booking工具。你可以在load_skill被调用时动态向Agent注册这些工具。LangChain的ToolRuntime和Command机制可以实现这一点