LangChain Agent Skills架构：12个实战案例详解

LangChain 新版本里Agent Skills 架构是近期讨论度很高的一类设计。它实际上是把你给 Agent 的“能力”做成可复用模块既不是简单塞一段 Prompt也不是单独挂一个 Tool而是把指令、工具、输入输出约束、错误处理一起封装成 Skill。我最近用新版 LangChain 跑了 12 个案例从单轮问答到多步骤任务、RAG 接入、MCP 服务和批量任务都过了一遍。这篇文章就按我实测的顺序展开适合正在做 Agent 原型、想把 Agent 能力模块化、或者准备从 LangChain 转向 LangGraph 编排的人。先说结论Agent Skills 架构最值得关注的不是“新增了多少个类”而是它逼着你在设计阶段把 Agent 的边界、工具触发条件、输出格式和失败处理想清楚。很多人跑 LangChain 项目时觉得乱不是 LangChain 不行而是把工具、提示词、状态和控制流全搅在一起。Skill 正好提供了一个比较轻量的隔离单元。下面我按实际落地顺序拆开讲。1. Agent Skills 是能力封装不是新的 Agent 框架1.1 Agent、Tool、Skill 有什么区别先把三个词对齐后面才不容易混。Agent 是决策和执行主体。它接收用户问题判断该调用什么能力怎么组织结果最后返回给用户。Agent 本身不一定要包含具体业务逻辑更多是“调度者”。Tool 是单个可执行函数。比如搜索、读文件、查数据库、调用某个 HTTP 接口。Tool 解决“某个动作怎么做”但它不管在什么场景下该不该被调用。Skill 是介于 Agent 和 Tool 之间的能力封装单元。一个 Skill 可以包含一段用于描述何时使用的说明一个或多个 Tool 的调用逻辑输入输出的格式约束超时、重试、降级等错误处理策略必要的前置处理比如把用户问题转换成工具参数。用一句话概括Tool 是手脚Skill 是“带操作手册的手脚”Agent 是决定用哪套手脚的人。很多人在设计第一版 Agent 时习惯把 Tool 直接列给模型。文档少、工具多时没有大问题但工具多了以后模型经常不知道该选哪个。Skill 的封装价值在于把一个完整任务所需的前置条件、执行步骤和后备方案收敛在一起而不是把几十个 Tool 平铺在 Prompt 里。1.2 为什么 Skill 适合做架构化改造LangChain 被问得最多的一个问题是“是不是过时了”。我的看法是LangChain 里 Agent 相关 API 的迭代速度确实非常快但它的核心价值不是某个固定写法而是让 Agent 的能力可以拆成可替换模块。Agent Skills 就是朝着这个方向走把能力从“临时拼 Prompt”变成“可注册、可复用、可组合”。普通 Prompt 写法的典型问题是这样想改一个工具的行为得去改一大段 Prompt多个 Agent 要复用同一套能力只能复制粘贴某个工具报错后没有统一兜底批量跑时经常挂在同一个地方模型不知道该在什么时候用哪个工具描述稍微含糊就乱调。Skill 解决了其中一部分。它把工具描述、输入输出约定和错误处理放到同一个模块里。你在多个 Agent 里复用同一个 Skill只需要改 Skill 定义不需要逐个 Agent 改 Prompt。所以Agent Skills 不是“又造了一个 Agent 框架”而是给 Agent 的能力管理增加了一层更清晰的边界。后面 12 个案例里很多问题都是围绕这层边界展开的。2. 跑第一个 Skill 前先把环境和控制变量理清楚2.1 环境依赖和最小安装LangChain 新版的 API 变化比较频繁我这里不写死版本号因为不同版本之间的 import 路径可能不同。建议你落地时先创建一个干净的虚拟环境再安装依赖。python -m venv .venv source .venv/bin/activate pip install langchain langchain-openai langchain-community我这批案例里有一部分跑的是 LangGraph 编排所以还装了langgraph。如果你只测 Agent Skills 本身先不要一次装太多否则出了问题很难判断到底是哪个依赖影响。在模型接入上OpenAI 兼容接口是最省事的路线。很多本地模型服务也会提供 OpenAI 兼容端点所以代码里可以先统一走ChatOpenAI的接口。比如from langchain_openai import ChatOpenAI llm ChatOpenAI( base_url你的模型服务地址, api_key你的API Key, model你的模型名 )这里要提醒一句不要把所有模型都用一个温度参数。默认温度适合写作和开放回答但 Skill 做结构化解析时温度太高会输出不稳定的 JSON太低又可能让模型不按描述触发工具。建议先都用默认值跑通一条任务后再根据实际输出调整。2.2 最小可运行案例先跑单条任务我第一次测 Skill 时没有直接做复杂业务而是先写了一个最简单的搜索型 Skill。目的是验证三件事Skill 能被正确注册Agent 能根据问题描述调用它返回值能正常落到最终回答里。示例结构如下注意这是演示结构不保证和你的具体版本完全一致。重点是看分层方式。from langchain.agents import create_agent from langchain.skills import Skill def search(query: str) - str: # 真实项目里这里会调用搜索 API return fmock result for {query} search_skill Skill( nameweb_search, description( 当用户需要查找最新资料、事件、名词解释时 使用这个 skill 获取搜索结果。 ), functionsearch, input_schema{query: string}, output_typestring, ) agent create_agent( llmllm, skills[search_skill], ) resp agent.run(请查一下 LangChain Agent Skills 的常见用法) print(resp)如果这一条能跑通说明链路已经正常。如果模型没有调用 Skill先不要急着调模型优先看 Skill 的description是否把触发条件写清楚了。很多模型不调用工具不是因为工具不存在而是描述里全是功能名词没有说明“什么场景下用”。2.3 观察输出和日志不要直接开批量跑通单条之后我会先看两样东西输出格式和日志。输出格式要检查三点最终回答是否自然而不是把内部 JSON 原样抛出来是否出现幻觉字段比如模型自己编造了一个 Skill 名多轮对话时历史消息是否正确传入。日志要看模型是否真的调用了被声明的 Skill还是误用了别的能力。如果日志里显示 Tool 调用链很乱说明 Skill 注册方式或者描述有问题。在这个阶段不要直接开并发、不要开批量。先把一条完整链路跑稳再谈吞吐和稳定性。控制变量永远是排查问题的最短路径。3. 12 个案例拆解从单任务到架构化编排我这次把 12 个案例分成四组覆盖了常见 Agent 场景。下面这张表可以先给个整体视图。案例组覆盖场景关键考察点1-3单轮问答、多轮对话、网页总结输入输出、记忆、格式化4-6任务规划、数据库问答、代码执行步骤顺序、状态传递、安全边界7-9RAG 检索、MCP 服务、LangGraph 编排知识增强、外部工具、流程控制10-12批量处理、失败重试、多模型调度并发、稳定性、降级3.1 案例 1-3先跑输入输出型 Skill案例 1 是单轮问答。这是最基础的场景Skill 里只有一个函数Agent 调它拿到结果再组合成回答。这里的核心验证点不是准确率而是模型是否在正确的时候调用 Skill。如果问题本身不需要外部信息模型却调用了 Skill说明 Skill 的描述边界太宽。案例 2 是多轮对话。多轮场景下要额外处理历史消息。有些 Skill 不需要历史有些则需要根据上一轮结果继续追问。我的建议是把历史消息作为 Agent 的上下文而不是塞进每个 Skill 的输入里。Skill 内部只处理“当次任务需要的最小输入”否则会让技能变得很难复用。案例 3 是网页总结。这个场景看起来简单但很容易踩坑。输入不是一段干净文本而是 URL、HTML 或 Markdown。需要先做内容提取再判断摘要长度。如果直接把大段 HTML 塞给模型不仅慢还容易把页面导航也摘要进去。我当时先写了一个fetch_web_content函数把正文提取和摘要分成两步再让 Skill 控制顺序。这三个案例的共同点输入可控、输出可检验。它们的作用是把 Agent 的基础链路打牢尤其要验证“输入格式改变时Skill 的调用是否依然稳定”。3.2 案例 4-6多步骤任务与状态传递案例 4 是任务规划。让 Agent 把一个复杂问题拆成多个子任务再逐个执行。这里不能只把“拆解”写进 Prompt而是要把规划结果当成结构化输出。否则模型在回答里列了步骤却没有真正执行。我用的结构很简单先用一个 planner 生成子任务列表再让 executor 按顺序执行每个子任务最后把子任务结果汇总成一个答案。这个流程里Skill 的作用是让每个子任务都对应一个明确能力。如果不做 Skill 隔离planner 的输出稍微一歪后面全部跟着乱。案例 5 是数据库问答。这类任务不能一上来就让模型直接生成 SQL 执行。更稳的做法是先让模型查看表结构再根据用户问题生成查询条件最后把查询结果转成自然语言。Skill 内部可以把“查表结构”和“执行 SQL”拆成两个小 Tool但对外只暴露一个统一入口。这里最容易忽略的是安全边界。不要让模型无条件执行任意 SQL。至少在本地测试阶段要用只读账号并且给查询加上超时。这不是 LangChain 的限制而是所有数据类 Agent 都必须考虑的工程问题。案例 6 是代码执行。模型生成代码然后执行代码再把输出返回给用户。这个场景非常容易踩资源问题。我建议把执行环境隔离到一个临时容器或沙箱里不要直接在本机跑任意代码。即使测试场景也要限制执行时间、输出大小和依赖安装权限。3.3 案例 7-9RAG、MCP 和 LangGraph 组合案例 7 是 RAG 检索。RAG 和 Agent 的区别在于“什么时候检索”。纯 RAG 是固定的“检索再生成”Agent 则可以根据问题判断是否需要检索。Skill 的优势是可以把 retriever 包装成一个带触发条件的技能只有问题涉及私有知识或需要事实校验时才调用。我在这个案例里最想验证的不是检索质量而是“误召回的代价”。如果模型对普通问题也去检索响应速度会明显变慢。判断标准是日志里retrieve调用次数和问题数量是否匹配。如果 10 个问题里有 8 个都检索说明 Skill 的触发描述写得太宽松。案例 8 是接入 MCP 服务。MCP 本身解决的是 Agent 和外部工具之间的标准化连接。在 Agent Skills 架构里MCP 服务可以作为一个 Skill 的执行后端。也就是说Skill 负责定义“什么时候调用”和“怎么处理结果”MCP 负责实际的数据传输。这个组合的好处是如果以后换工具不需要改 Skill 的决策逻辑只要替换 Skill 背后的执行实现。坏处是排错链条变长。一次失败可能来自 MCP 配置、工具服务、网络超时或者 Skill 的参数映射。所以 MCP 类 Skill 一定要加超时和错误描述减少排查时间。案例 9 是用 LangGraph 做编排。很多人在问 LangChain 和 LangGraph 的区别。我的理解是LangChain 提供 Agent、Tool、Skill 等组件LangGraph 提供状态图和控制流。当你需要固定执行顺序、人工确认节点、分支判断、循环重试时用 LangGraph 更可控如果只是让模型自由决策调用哪些能力直接用 LangChain Agent 就够了。实践里我通常把 Skill 放在 LangGraph 的节点里执行。每个节点要么是一个 Skill要么是一个判断逻辑。这样既保留了 Agent 的灵活性又把流程控制交给图来管理避免模型在复杂流程里“放飞”。3.4 案例 10-12批量、重试和模型调度案例 10 是批量处理一批文件。批量不等于把同一条 Skill 循环跑一百遍。要单独处理输入列表、输出命名、中间状态、失败跳过和最终汇总。我一开始用最简单的方式跑循环结果某一条卡住后整个任务都停住。后来改成一条条记录状态每处理一条就写一次中间结果这样中断后可以继续。案例 11 是失败重试。重试不是简单地原地再跑一次。要区分失败类型超时、限流、模型返回格式错误、工具服务不可用。超时可以增加等待时间后重试格式错误可以重试但需要把错误信息回传给模型工具服务不可用则要降级到备用方案。Skill 里应该内置一个简单的失败处理函数而不是把重试逻辑散落在调用处。案例 12 是多模型调度。不同 Skill 不一定都用同一个模型。简单的文档提取可以用轻量模型复杂的规划任务可以用更强模型。Skill 可以保留一个“模型选择”的配置入口。但要注意切换模型后输出格式一致性会变差。所以给每个 Skill 定义明确的输出 Schema 比换模型更重要。这四组案例跑下来我的体会是Agent Skills 不是银弹但它能把“模型乱来”的范围缩小。只要每个 Skill 的边界清楚即使模型某次调用错了也可以通过日志快速定位到具体能力和参数。4. 架构落地时判断标准不是“能不能跑”4.1 Skill 设计好不好看四个维度能跑通只代表链路通不代表架构合理。我会用四个维度评估一个 Skill 设计维度判断标准常见问题复用性是否能被多个 Agent 无修改使用把业务上下文写死在 Skill Prompt 里可测性输入输出是否结构化、可离线验证返回值全是自然语言无法断言稳定性连续跑 10 次是否结果一致模型随机性导致同一个问题输出格式不同可维护性修改某个能力时只改一处多个 Agent 复制粘贴技能改一处漏一处复用性最容易出问题。比如把用户公司名、数据库账号、某个具体业务指标写进了 Skill 描述里那这个 Skill 只能在当前项目用。更合理的做法是Skill 的 Prompt 描述只写“什么场景、什么输入、什么输出”具体业务参数由调用时传入。可测性也很关键。如果 Skill 返回的是自由文本测试时很难判断它对不对。但如果你规定返回 JSON 结构比如{status: ok, data: ...}就可以写断言来自动验证。这个习惯在批量任务里尤其有用。4.2 参数先给保守值再按任务放大Agent Skills 涉及几个最常调的参数并发数、超时时间、重试次数、上下文长度、温度。我建议的初始值如下具体以你的环境为准。参数保守起点说明并发数1-2先跑通再逐步增加超时时间30 秒左右根据工具实际耗时调整重试次数2 次不要无限重试温度0-0.3结构化任务建议低一些上下文长度按模型默认不要为了省 token 无限截断低配置环境下不要一开始就把并发拉满。有些模型服务在并发高时会出现超时或返回错误这不是 Agent 代码的问题而是后端限流。先把并发从 1 加到 2、4、8观察成功率变化。这里特别说一下“上下文长度”。很多 Agent 跑着跑着变慢是因为消息列表越来越长每次调用都要重新发送所有历史。Skill 架构解决不了历史累积问题所以还要在编排层做摘要或裁剪。如果案例 2 的多轮对话跑慢了优先检查是不是历史消息没有压缩。4.3 性能验证要覆盖连续任务和失败场景性能验证不要只看单条响应时间。我一般用 10 条连续任务做一次小压测统计三个指标成功率成功完成的任务数 / 总任务数P50 和 P95 耗时P95 比 P50 更能反映异常失败类型超时、格式错误、工具调用失败分别占多少。如果 P95 明显高于 P50说明存在部分任务特别耗时常见原因是长文本输入或者某些工具接口响应慢。这时不要急着调模型先看日志里哪个 Skill 耗时最长。同时要验证“失败后系统能否恢复”。比如故意让某个 Skill 抛出一个错误观察 Agent 是会直接崩溃还是会返回错误信息并继续下一条。一个合格的架构设计至少要在 Skill 层捕获异常不要在循环外层才 try/except否则很难知道是哪个能力的问题。5. 遇到问题时的排查顺序和经典案例5.1 先看输入和后端日志再改参数遇到 Agent 不按预期工作时我的第一步不是改 Prompt也不是换模型而是看输入和日志。排查顺序先放在这里看现象是没输出、超时、报错还是结果格式不对看输入文件路径、编码、文本长度、参数类型是否正常看日志模型是否调用了正确的 Skill传参是什么看环境依赖版本、Python 环境、线程安全、磁盘空间看参数并发、超时、重试、模型名是否正确。很多“模型不调用工具”的问题最后都出在 Skill 描述和输入格式上。比如 input_schema 要求query字段但 Agent 每次都传question工具侧就会报参数缺失。这种情况不是模型问题而是参数契约没有对齐。5.2 依赖版本和运行环境最容易误判LangChain 新版的 import 路径变化很快。有时候你在网上复制的代码跑不了不是代码错而是版本不一致。遇到这类问题先检查当前环境里langchain和langgraph的版本再对比示例代码对应的版本说明。pip show langchain pip show langgraph pip show langchain-openai如果发现版本太新或太旧可以考虑固定到某个稳定版本再测试。不要迷信“最新版一定最好”Agent 这种多依赖项目稳定性往往比新功能更重要。另外批量任务里要特别注意运行目录。很多人在本地 Jupyter 里跑得好好的改成命令行批量脚本后就读不到文件原因是相对路径变了。建议所有文件路径都写成绝对路径或者在启动脚本里先打印当前工作目录。5.3 一个比较典型的批量失败场景我拿案例 10 复现过这样一个场景批量处理 50 个文本文件跑到第 17 个时突然退出。现象是没有任何报错只停在那里不动。一开始我以为模型卡住后来发现是输出目录不存在第 17 个文件的写入失败异常没有被捕获循环直接中断。这就是典型的“单条能跑批量不能跑”的问题。解决办法很简单每条任务写入前检查输出目录是否存在不存在就先创建每个子任务都套一层错误处理失败后记录原因每处理一条把任务状态写入一个 JSONL 或数据库方便断点续跑。这类问题在 Agent Skills 架构里尤其明显。因为 Skill 往往只关心“处理逻辑”而批量的“调度、状态、输出管理”不归 Skill 管。如果你把批量处理逻辑也塞进 SkillSkill 的复用性会大大降低。正确的做法是把 Skill 当作“单条能力”把批量调度放到外层流程两者职责分开。踩过几轮之后我发现Agent Skills 真正能改善的不是“模型变聪明”而是“工程变得可维护”。它让每个能力变成一个边界明确的模块出了问题可以单独测、单独修。如果只是跑一两个 Demo用最普通的 Tool 列表也够了但如果你要做多 Agent、多工具、长时间稳定运行那么这个架构思路值得认真用起来。