Langchain 最近更新的 Agent Skills 机制值得所有做 Agent 应用的人重新看一遍。它不是又加了一个 API而是把“写死工具列表 写死 Prompt”那套玩法升级成了“给 Agent 一个技能包让它自己决定怎么用”。这个转变对开发方式的冲击比想象中更大。先说判断Agent Skills 真正解决的问题是 Agent 应用里最头疼的“组合爆炸”。以前每增加一个能力你要改 system prompt、改工具注册表、改任务路由逻辑功能越多代码越碎。现在官方把这层抽象成了 Skills 架构Agent 自身负责调用、编排和决策开发者只需要把“技能”描述清楚。这意味着写 Agent 的姿势正在从“写程序”变成“写说明书 配技能包”。这篇文章会用 12 个实际案例带你拆解这套架构到底是什么能解决什么问题有哪些坑。内容偏实操建议边读边试。1. 为什么 Agent Skills 突然火起来了先说背景。Langchain 在 Agent 方向已经迭代了很多版本从最早期单纯的 Chain 串联到后来引入 ReAct、Plan-and-Execute 等多种 Agent 范式再到 Langgraph 做图状态编排。能力在变强但开发者始终面临同一个尴尬构建一个稍微像样的 Agent要把 Prompt 工程、工具定义、记忆策略、路由逻辑全部揉在一起。没有 Agent Skills 时你想让 Agent 具备“数据库查询”的能力通常要经历这些步骤在 system prompt 里描述数据库有哪些表、字段含义。写几个 Tool 函数比如query_db、get_schema注册到 Agent 的工具列表。处理 Tool 返回的原始结果再拼装成自然语言。如果数据库类型变了或者换了业务场景又得重新调 prompt 和工具参数。这个过程不难但非常琐碎。问题在于Agent 的核心价值是自主决策但开发者却在替它把每一步都规定死。Agent Skills 的思路是把一组相关的指令、工具、模板、校验逻辑打包成一个“技能”。Agent 收到用户请求后自己判断需要哪些技能再加载这个技能的上下文和工具来执行。用生活中的类比来理解传统开发方式是你请了一个员工然后给他一本极其详细的 SOP每一步都写清楚。Agent Skills 的方式是你告诉员工“你具备数据分析、报告生成、可视化三种能力”具体怎么组合完成目标员工自己决定。这个转变真正解决的是Agent 能力的标准化封装与复用。技能包可以在不同 Agent 之间共享可以在社区分发也可以按场景组合。2. 核心概念Agent、Tool、Skill 的区别开始写案例之前必须先厘清三组概念否则后面容易混。2.1 Tool 与 Skill 的关系Tool工具是 Agent 可以直接调用的函数通常是独立、原子性的比如“执行 SQL”“调用天气 API”“计算两个日期差值”。Skill技能是一个更高层的抽象它将多个工具、指令模板、上下文说明、验证逻辑组合在一起。你可以理解为Tool 一个会做某件事的函数 Skill 一套完成某类任务的能力包包含工具、规则、步骤、校验和常见错误处理一个 Skill 内部可以包含多个 Tool。Skill 不只是工具的集合还包括如何使用这些工具的知识。比如“生成数据分析报告”这个技能里面要有数据库查询工具、Markdown 模板、图表生成工具还要有告诉模型“先了解表结构、再写查询、最后生成结论”的指令。2.2 Skill 与 Prompt 的关系很多人会问这不就是把 Prompt 写长一点吗区别在于Skill 不只是 Prompt 文本它附带了可执行的工具定义、输入输出约束、验证逻辑、示例数据。Prompt 只影响模型“怎么想”Skill 还决定了模型“能做什么”。换个角度说Prompt 是给模型的提示Skill 是给 Agent 的完整能力模块。2.3 Langchain 与 Langgraph 的定位差异Langchain 是构建 Agent 应用的综合框架提供了模型接入、Prompt 管理、Tool 封装、RAG、记忆等能力。Langgraph 专注于状态化、可编排的 Agent 工作流适用于需要多轮状态管理、条件跳转、复杂分支的 Agent。Agent Skills 不是一个独立的框架而是 Langchain 层面的能力抽象。它和 Langgraph 的关系是Langgraph 负责编排 Agent 的整体流程Skills 负责定义 Agent 在某一步调用的具体能力。做一个简单的对比表维度ToolSkillLanggraph 节点粒度最小可调用单元一组能力的封装工作流中的一个执行步骤是否包含指令否只有函数逻辑是包含指令和使用说明否包含状态转移逻辑典型例子查询天气的函数完整的数据分析技能包对话管理、任务分发节点理解到这层后面的 12 个案例才看得明白。3. Agent Skills 的整体架构先看架构层面。一个完整的 Agent Skills 方案通常由 5 个层次组成模型层底层大语言模型负责理解用户请求、调用技能、生成回复。技能注册层维护一个技能清单记录每个技能的 ID、名称、描述、所需工具、适用场景。技能加载层根据用户输入动态选择技能并将技能内的指令模板、工具定义注入模型上下文。工具执行层实际执行技能内部的工具调用完成数据获取、参数计算等操作。校验与反馈层校验执行结果是否符合预期出错时负责重试或降级。在 Langchain 中一个 Agent Skill 的典型设计包括以下部分name技能名称如data_analysis_skilldescription技能描述Agent 根据描述决定是否使用该技能instructions如何使用该技能的指令注入 system prompttools技能执行时用到的工具列表templates输入输出模板validators参数或输出校验器用户的请求进来后Agent 会先判断需要哪些技能然后按需加载。3.1 架构上的变化从“代码驱动”到“声明式驱动”过去你用 Langchain 构建 Agent核心代码是agent create_react_agent(llm, tools[tool1, tool2, tool3])所有工具对 Agent 来说都是平铺的Agent 只能根据描述自行选择。一旦工具多了模型容易选错工具或者不知道该先用哪个。有了 Agent Skills 后架构变成agent create_agent_with_skills(llm, skills[skill_a, skill_b])Agent 先选择技能再在技能范围内选择工具。这相当于把“工具选择空间”先缩小到“技能选择空间”再在技能内部执行工具显著降低了模型决策难度。3.2 为什么说这套架构是分水岭传统 Agent 是“模型 工具 提示词”的三明治结构所有逻辑都暴露在开发者的代码里。而 Skills 架构把任务能力从主流程中抽离变成了可插拔的模块。这带来三个直接好处复用性提升一个“数据分析技能”可以在客服 Agent、运营 Agent、研发辅助 Agent 中复用。维护成本下降修改某个技能内部逻辑时不需要动主 Agent 代码。协作边界清晰擅长 Prompt 的成员负责写技能指令擅长工程的同学负责写技能内部工具互不阻塞。4. 环境准备与前置条件进入实操前先准备好环境。以下步骤主要针对 Langchain 的新版本具体版本号以你实际安装为准。4.1 创建 Python 虚拟环境python -m venv agent_skills_env source agent_skills_env/bin/activate # Windows 系统使用 agent_skills_env\Scripts\activate4.2 安装 Langchainpip install --upgrade langchain langchain-openai langchain-core如果你需要用到 Langgraph 来做复杂的 Agent 编排再安装pip install langgraph4.3 准备模型 API Key本文中的示例以 OpenAI 兼容接口为例。你可以在环境变量中配置export OPENAI_API_KEYyour-api-key如果你的模型服务不是 OpenAI而是国内大模型平台或其他兼容接口只需要替换 Langchain 中的模型实例即可案例的 Agent Skills 逻辑是通用的。4.4 验证环境是否正常python -c import langchain; print(langchain.__version__)打印出版本号说明安装成功。接下来我们进入案例环节。5. 12 个案例拆解从入门到进阶接下来是全文最核心的部分。12 个案例按难度递增排列从最简单的最小技能到复杂的数据分析、多 Agent 协同、工具类技能组合。建议每个案例都自己跑一遍再修改参数测试效果。案例 1定义一个最基础的 Skill以“代码注释生成器”为例演示如何定义一个最小可用的 Skill。from langchain_core.tools import tool from langchain_core.language_models.chat_models import BaseChatModel from langchain_openai import ChatOpenAI from langchain.agents import create_agent tool def get_function_code(func_name: str) - str: 根据函数名称获取项目中该函数的源代码。 # 实际项目中这里会从代码仓库读取 return def add(a, b): return a b code_comment_skill { name: code_comment_generator, description: 为指定函数生成注释输入为函数名输出为带注释的代码。, instructions: 当用户要求为函数生成注释时 1. 使用 get_function_code 获取函数源代码。 2. 分析函数逻辑。 3. 在函数定义的下一行插入功能说明、参数说明、返回值说明。 , tools: [get_function_code], } llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 将技能中的 tools 平铺给 agent并将 instructions 注入 system prompt agent create_agent(llm, tools[get_function_code], system_promptcode_comment_skill[instructions]) response agent.invoke({input: 请为 add 函数生成注释}) print(response[output])这个案例有三个关键点Skill 是 Python 字典对象最重要的是description和instructions。description用于 Agent 判断何时使用该技能instructions是技能内部的使用方法。本例没有用官方的“技能注册/加载”高级 API而是先把技能手动平铺到 agent 中。目的是让你理解技能的本质不是魔法而是“指令 工具 逻辑的组合”。输出结果时模型会根据 instructions 中的步骤顺序执行先拿代码再写注释。案例 2多工具组合技能单个工具太简单真实场景往往需要多个工具配合。以“项目周报生成”为例这个技能需要两个工具获取 Git 提交记录、获取需求列表。from langchain_core.tools import tool from datetime import datetime, timedelta tool def get_git_commits(repo_path: str) - str: 获取指定仓库最近一个工作日的 git 提交记录。 # 真实场景中会执行 git log 命令 return feat: 添加登录功能\nfix: 修复订单超时问题\nrefactor: 重构用户模块 tool def get_task_list(project_id: str) - str: 获取指定项目的任务完成情况。 return 已完成: 3个任务\n进行中: 2个任务\n待开始: 1个任务 week_report_skill { name: weekly_report, description: 根据 git 提交记录和项目任务列表生成周报。, instructions: 生成周报时 1. 先调用 get_git_commits 获取代码提交记录。 2. 再调用 get_task_list 获取任务完成情况。 3. 将两者组织成周报格式本周完成 / 存在问题 / 下周计划。 , tools: [get_git_commits, get_task_list], } agent create_agent( llm, tools[get_git_commits, get_task_list], system_promptweek_report_skill[instructions], ) response agent.invoke({input: 生成项目 PROJ-1001 的本周周报}) print(response[output])这个案例想说明的是技能内部可以有多个工具且工具之间通常有执行顺序。在这个设计里指令模板就是告诉模型“你先查代码再查需求最后汇总”。相比让模型自己摸索顺序这种显式规定成功率更高。案例 3带输入校验的 Skill实际生产中技能参数经常会被传错。比如用户让 Agent“查询上周的数据”但技能只支持“按日期查”。如果没有校验机制Agent 会拿一个模糊的时间范围去调工具然后返回一堆脏数据。我们可以在技能中加入参数校验逻辑from pydantic import BaseModel, Field class DateQueryInput(BaseModel): start_date: str Field(description开始日期格式 YYYY-MM-DD) end_date: str Field(description结束日期格式 YYYY-MM-DD) tool(args_schemaDateQueryInput) def query_sales(start_date: str, end_date: str) - str: 查询指定日期范围内的销售数据。 # 模拟查询结果 return f销售数据: {start_date} 至 {end_date}, 总销售额 100000 元 data_query_skill { name: sales_query, description: 查询销售数据只支持按日期范围查询。, instructions: 当用户查询销售数据时 1. 必须先确认开始日期和结束日期。 2. 如果用户没有提供日期询问用户。 3. 日期格式必须是 YYYY-MM-DD。 , tools: [query_sales], }这个案例的价值点是args_schema让工具具备结构化的参数约束。模型在调用工具之前会先按 Pydantic 模型校验参数。参数不对时Langchain 会要求模型重新生成符合要求的参数。实际开发中不要偷懒省掉参数校验。AI 生成的内容再聪明也可能出现错误格式。案例 4使用模板引擎生成结构化输出很多技能的输出需要固定格式比如 JSON、Markdown、HTML。只靠模型“自觉”遵守格式会不稳定比较可靠的做法是给它一个模板让它“填空式”输出。下面这个案例是“生成数据库表设计文档”table_doc_template ## 表名: {table_name} ### 字段说明 | 字段名 | 类型 | 是否必填 | 说明 | | --- | --- | --- | --- | {field_rows} ### 索引设计 {index_rows} ### 备注 {notes} tool def get_table_meta(table_name: str) - str: 获取数据库表结构元数据。 return [ {field: id, type: bigint, nullable: 否, comment: 主键}, {field: name, type: varchar(64), nullable: 否, comment: 用户名}, ] table_doc_skill { name: table_doc_generator, description: 根据表名生成数据库表结构说明文档。, instructions: 1. 使用 get_table_meta 工具获取表结构元数据。 2. 将元数据填充到 table_doc_template 模板中。 3. 最终输出完整的 Markdown 文档。 , tools: [get_table_meta], }模板方式的核心价值是减少生成式输出的不确定性。只要模板约束了结构模型输出的部分就只有内容格式是稳定可控的。如果你正在做报表、合同、代码生成、API 文档等场景建议都采用模板方案。案例 5带记忆的 SkillAgent 的上下文记忆问题一直是被问得最多的问题之一。Langchain 中记忆组件五花八门但在技能架构里记忆应该如何设计推荐的做法是把记忆设计成技能内部的一个工具而不是全局的一团状态。from langchain_core.tools import tool memory_store {} tool def save_note(key: str, content: str) - str: 保存一条笔记到长期记忆。 memory_store[key] content return 已保存 tool def get_note(key: str) - str: 读取指定键的笔记。 return memory_store.get(key, 未找到相关笔记) note_skill { name: meeting_memory, description: 记录会议中的关键结论和待办事项并在后续对话中调用。, instructions: 当用户提到会议、结论、待办事项时 1. 如果是第一次提到使用 save_note 保存。 2. 如果用户后续询问使用 get_note 查询。 3. 注意区分不同会议key 建议使用 会议名称_日期。 , tools: [save_note, get_note], }这里的关键是记忆不再是黑盒而是显式的“保存”和“读取”工具。这有 3 个好处Agent 知道自己在什么时候“记住了东西”什么时候该“调用记忆”。调试容易你可以直接查看 memory_store 里的内容。后续可以无缝替换成 Redis、向量数据库只需要改工具内部实现。案例 6数据分析类技能多步骤编排数据分析是 Agent 场景里最常见的需求之一。一个完整的数据分析技能至少包含以下步骤获取数据表结构。生成 SQL 并执行。对结果做聚合计算。输出分析结论。用一个简化示例展示from langchain_core.tools import tool tool def get_schema() - str: 获取数据库所有表的结构。 return table: orders columns: order_id, customer_id, amount, created_at table: customers columns: customer_id, name, city tool def run_sql(sql: str) - str: 执行 SQL 查询只允许 SELECT 语句。 # 生产环境需要严格校验 SQL防止注入 return 北京, 1500\n上海, 1200\n广州, 900 analysis_skill { name: sales_analysis, description: 分析销售数据输出结论和趋势。, instructions: 数据分析步骤 1. 先调用 get_schema 了解表结构。 2. 根据用户问题编写 SQL关键只允许 SELECT。 3. 调用 run_sql 执行查询。 4. 根据结果总结趋势、指出异常最后给出建议。 , tools: [get_schema, run_sql], }这个案例真正体现了 Agent 结合技能和执行能力的价值。模型负责拆解问题、编写 SQL、解读结果工具负责真实的数据访问。你自己看数据可能半天才能得出结论Agent 在几秒内就能输出一份包含结论的回复。实际项目中需要注意的地方是 run_sql 的实现必须要做安全过滤不能让模型拼接出DROP TABLE这类危险语句。案例 7RAG 检索问答技能Langchain 最经典的场景之一就是 RAG。把 RAG 做成技能好处是可以针对不同知识库配置不同的检索策略。from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings from langchain_core.tools import tool # 假设已有一个向量数据库 vectorstore FAISS.load_local(faiss_index, OpenAIEmbeddings(), allow_dangerous_deserializationTrue) retriever vectorstore.as_retriever(search_kwargs{k: 4}) tool def search_docs(query: str) - list: 在知识库中检索与问题相关的内容。 docs retriever.invoke(query) return [doc.page_content for doc in docs] rag_skill { name: internal_docs_qa, description: 基于内部知识库回答员工问题适用于制度、流程、产品文档。, instructions: 当用户询问内部制度或流程时 1. 调用 search_docs 检索相关文档片段。 2. 优先基于检索内容回答不要编造。 3. 如果检索内容不足以回答告诉用户“该问题暂未找到相关信息”。 , tools: [search_docs], }这个技能值得注意的地方是第 3 条指令。如果不加这条模型很容易在检索不到信息时强行编造答案。加上了就引导模型保守回答。做企业知识库问答时这几乎是必须的设计。案例 8代码生成 自动执行技能代码类 Agent 很受欢迎但实际使用中最怕代码生成错误、运行报错。可以把代码生成、执行、报错修复三个步骤封装在一个技能中。import subprocess tool def write_and_run_code(code: str) - str: 将生成的 Python 代码保存并运行返回执行结果或报错信息。 with open(generated_code.py, w, encodingutf-8) as f: f.write(code) result subprocess.run( [python, generated_code.py], capture_outputTrue, textTrue, timeout30, ) if result.returncode 0: return f运行成功:\n{result.stdout} return f运行失败:\n{result.stderr} coding_skill { name: python_coder, description: 编写并运行 Python 代码帮助用户解决编程问题。, instructions: 1. 根据用户需求编写完整 Python 代码。 2. 调用 write_and_run_code 执行代码。 3. 如果执行失败根据报错信息修改代码后再次运行。 4. 最终将运行结果反馈给用户。 , tools: [write_and_run_code], }这个技能模式下Agent 成为一个简单的“自动编程执行器”。测试环境可以这么玩但生产环境要非常谨慎因为让模型直接执行生成的代码有安全风险。只建议在沙箱环境、测试环境中开启。案例 9工作流路由技能一个复杂的 Agent往往内部有多个技能。技能之间不是相互独立的而是根据用户意图做路由分发。用“需求分析助手”举例它既能写 PRD也能面 SQL还能生成原型描述。路由怎样做tool def route_request(query: str) - str: 判断用户请求属于哪个技能。 if prd in query.lower() or 需求文档 in query: return write_prd elif sql in query.lower() or 数据库 in query: return write_sql else: return unknown router_skill { name: request_router, description: 将用户请求路由到合适的技能。, instructions: 当用户提出需求时 1. 先调用 route_request 判断属于哪个技能。 2. 如果路由结果是 write_prd调用 write_prd_skill。 3. 如果路由结果是 write_sql调用 write_sql_skill。 , tools: [route_request], }这个路由方案在实现上还可以升级为向量相似度匹配。把每个技能的描述向量化用户输入进来后用余弦相似度找最合适的技能。Langchain 里可以用VectorStoreToolkit做类似的事。案例 10组合式技能一个技能调用另一个技能高级场景下技能之间也需要协作。比如“生成数据分析报告”技能内部要调用“数据查询”技能和“图表生成”技能。tool def get_report_data(metric: str) - str: 获取某个指标的数据序列。 return f{metric}: 10, 15, 23, 42, 56 tool def generate_chart(data: str) - str: 将数据序列转换为图表 Markdown 代码。 images [] return images[0] composite_skill { name: data_report, description: 生成一份完整的数据分析报告。, instructions: 生成数据分析报告的步骤: 1. 使用 get_report_data 获取原始数据。 2. 使用 generate_chart 生成趋势图。 3. 综合数据和图表输出 Markdown 格式的报告。 , tools: [get_report_data, generate_chart], }这种设计把“查询数据”和“生成图表”拆成两个可复用的工具但组合逻辑依然由 Agent 完成。如果你有很多报表需求可以基于这个思路构建一个报表技能族。案例 11多 Agent 协同下的 Skills规模再大一点就需要 Langgraph 来编排多个 Agent每个 Agent 拥有不同的 Skills。比如一个“项目复盘助手”系统数据收集 Agent拥有git_log_skill、task_query_skill分析 Agent拥有metrics_calculation_skill报告生成 Agent拥有report_template_skillLanggraph 负责 Flow每个节点是 Agent每个 Agent 有自己的 Skills。下面是一个极简示意from langgraph.graph import StateGraph class AgentState(dict): messages: list def collect_node(state): # 调用数据收集 Agent内部使用 git_log_skill return state def analyze_node(state): # 调用分析 Agent内部使用 metrics_calculation_skill return state def report_node(state): # 调用报告 Agent内部使用 report_template_skill return state graph StateGraph(AgentState) graph.add_node(collect, collect_node) graph.add_node(analyze, analyze_node) graph.add_node(report, report_node) graph.add_edge(collect, analyze) graph.add_edge(analyze, report) graph.set_entry_point(collect) graph.set_finish_point(report) app graph.compile()这个案例说明了一个重要架构判断单 Agent 单技能的思路只能做 Demo生产中复杂任务要靠 Langgraph 编排多个 Agent每个 Agent 拥有专职技能。这样每个 Agent 的上下文更短、决策更准确调试也更容易。案例 12对外发布一个可复用的技能包最后一个案例是把自己开发的技能做成可复用的包分享给团队或社区。Langchain 支持自定义工具和技能封装。一个典型技能包目录如下my_agent_skills/ ├── pyproject.toml ├── my_agent_skills/ │ ├── __init__.py │ ├── analysis_skill.py │ ├── report_skill.py │ └── utils.py └── examples/ └── demo.py其中pyproject.toml声明依赖[project] name my-agent-skills version 0.1.0 dependencies [ langchain-core0.2, langchain-openai0.1 ]技能模块里把 Skill 定义导出# my_agent_skills/analysis_skill.py from langchain_core.tools import tool tool def analyze_text(text: str) - dict: 分析文本的情感倾向和关键词。 return { sentiment: positive, keywords: [高效, 稳定, 易用], } analysis_skill { name: text_analysis, description: 分析用户文本的关键词和情感。, instructions: 当用户请求分析文本时使用 analyze_text 工具。, tools: [analyze_text], }团队成员可以直接引用这个模块from my_agent_skills.analysis_skill import analysis_skill这个案例的核心价值是工程化。技能的封装和发布最终会决定团队协作效率。规范接口、版本管理、依赖声明都是实际落地中会让你少踩很多坑的细节。6. 运行结果与效果验证上面 12 个案例每个都可以独立运行。但运行只是第一步如何验证 Agent 真的“拥有”了技能才是关键。6.1 验证技能是否生效最简单的验证方式是直接输入一个覆盖技能场景的问题response agent.invoke({input: 请分析项目 PROJ-1001 的周报}) print(response[output])预期应该看到 Agent 按 Skill 中 instructions 规定的顺序执行工具先获取 git 记录再获取任务列表最后输出周报。6.2 调试手段如果 Agent 没有按预期执行技能建议做这几步检查查看模型原始调用链Langchain 支持回调回调机制通过LangSmithTracer或自定义BaseCallbackHandler来看每一步究竟调用了哪个工具。检查系统提示词确认system_prompt确实注入了技能的instructions。单测每个工具直接用 Python 调用工具函数看返回值是否符合预期。工具本身出错Agent 再聪明也没用。# 验证工具 print(get_git_commits.invoke({repo_path: /tmp/repo}))6.3 失败时的第一排查思路如果技能完全没有被调用优先检查技能的description是否清晰。description直接决定了模型是否会在正确场景触发该技能。比如查询销售数据只支持按日期范围查询这样的描述模型很容易理解。如果写成sales_data_query_function模型大概率不会触发。7. 常见问题与排查思路问题现象可能原因排查方式解决方案Agent 不调用技能description 不清晰或没有触发场景检查技能描述是否包含用户常见的说法重写 description加入同义词和典型问法工具参数传错args_schema 未定义或定义过于宽泛查看 Langchain 日志中的 tool call 参数用 Pydantic 定义严格的参数模型技能内部工具执行顺序混乱instructions 步骤不够明确在 instructions 中增加“先…再…最后…”显式规定工具调用顺序模型回答与工具返回结果不符system prompt 和工具输出之间缺少衔接指令检查 tool 结果是否被截断加长工具返回的上下文或让模型完整引用工具结果并发执行时内存溢出技能内部缓存/store 设计不当查看进程内存占用将存储迁移到 Redis 等独立中间件生产环境技能更新不生效技能代码被缓存检查 Agent 启动方式改为动态加载技能配置支持热更新工具执行报错Agent 无法恢复缺少错误恢复指令观察重试次数在 instructions 中加入“如果工具报错请尝试修复参数后重试或告知用户失败原因”数据泄露风险工具未做权限隔离审核工具对应的数据范围为不同场景配置独立的数据访问控制8. 最佳实践与工程建议8.1 技能拆分原则一个技能不应该太大也不应该太小。判断标准是技能是否具备完整的目标闭环技能是否可以被多个场景复用技能内部工具是否高度内聚比如“生成数据分析报告”可以作为一个技能但“查询数据库” “生成图表” “生成文字结论”如果拆成三个独立技能会让 Agent 面对不必要的路由压力如果硬放在一个技能里复用性又差。推荐的折中方案是把“查询数据库”做成底层能力把“生成图表”做成另一个底层能力然后再封装一个“数据分析报告”组合技能。8.2 指令模板设计建议写instructions时要避免模糊表述。看两个对比错误示范当用户查询数据时你应该分析数据并给出答案。正确示范当用户查询数据时 1. 使用 get_schema 获取表结构。 2. 编写 SQL校验 SQL 只包含 SELECT 关键字。 3. 调用 run_sql 执行查询。 4. 如果结果为空告知用户“暂无数据”不要凭空编造。 5. 输出结论时列出关键数据指标。Agent 对确定性步骤的执行成功率远高于模糊指示。把步骤拆细是成本最低也最有效的提升 Agent 性能的方法。8.3 安全与权限控制技能内部工具具有真实的执行能力必须遵循最小权限原则数据库工具只开放 SELECT 或指定表禁止 DDL、DML。文件操作工具限制在指定目录内防止路径穿越。外部 API 调用需要在网关层限制域名和频次。涉及隐私数据查询时需要接入权限校验不能让模型权限成为权限后门。安全边界是 Agent 应用落地中最严肃的部分不要因为“只是 Demo”而放松。8.4 监控与日志日志至少要覆盖用户问题原文Agent 选择了哪个技能技能内部调用了哪些工具工具执行结果摘要模型最终输出这些日志不仅是调试的依据也是你判断技能是否好用的数据来源。如果某个技能总是触发失败从日志里能很快看出来。8.5 多技能时的路由策略技能数量超过 5 个后一次把全部技能的描述都塞给模型会拉长上下文也会影响决策准确率。两种方案显式路由先用一个小的分类器或关键词规则判断意图再加载对应的技能包。向量检索路由将技能描述向量化用户请求进来后用相似度匹配 TopN 技能。Langchain 的create_retriever_tool可以辅助实现。在实战场景里显式路由通常比完全依赖模型做技能选择更稳定。8.6 版本管理与治理技能也是代码。团队协作时要纳入版本管理遵循以下规范一个技能一个目录目录内包含描述文件、工具代码、测试用例。技能变更走 MR 流程附带变更说明。对技能做版本标记Agent 端固定引用指定版本防止“昨天还能用今天不行了”。9. 对 Langchain 与 Langgraph 架构选型的建议很多读者纠结到底应该直接用 Langchain 的 Agent还是用 Langgraph 自己编排谈谈判断标准如果你的 Agent 只有 1 到 3 个技能任务链路短直接用 Langchain Agent Skills 完全够用。如果你的 Agent 需要处理多轮状态、条件分支、人工审核、超时重试使用 Langgraph 编排把每个环节做成一个节点技能放在各节点内部。还要提一下 Langchain 和 Langgraph 的关系。Langgraph 更底层的定位是“Agent 工作流引擎”Langchain 提供的是“构建 Agent 的组件库”。两者不是二选一而是可以并存Langgraph 做流程控制Langchain 提供工具、技能、模型接入能力。从当前 Langchain 的迭代趋势看Agent Skills 正在成为核心抽象层。它解决的是 Agent 开发中最痛的问题能力如何标准化如何复用如何治理这也是这篇文章最想让你理解的点Agent Skills 不是一个新功能而是一套关于 Agent 能力组织方式的架构设计。沿着这个思路做下去不只是使用一个框架的某个 API而是在建立你自己的 Agent 工程化方法论。10. 总结与后续学习方向这 12 个案例从最小技能定义、工具组合、参数校验、模板输出一直讲到多 Agent 协同和技能包发布。核心想传达的判断是Agent Skills 把“Agent 的能力”从一个抽象概念变成了一个可定义、可组合、可复用、可治理的工程对象。有了这套抽象开发 Agent 的方式会从“写死一切逻辑”变成“定义能力边界让模型在边界内自主决策”。建议你的下一步实践路径从案例 1 开始先定义一个属于自己业务场景的最简技能。跑通之后逐步增加工具、校验、指令模板。当你觉得技能变多了再引入 Langgraph 做流程编排。关注 Langchain 官方仓库中关于 Agent Skills 的更新架构还在快速迭代。如果想深入优先看这几个方向Langchain 官方文档中 Agent 与 Tool 的部分。Langgraph 教程里的多 Agent 协作例子。Pydantic 官方文档掌握参数校验工具。收藏这篇文章找个周末跑通前 5 个案例你对 Agent Skills 的理解会超过大部分人。
Langchain Agent Skills 机制详解：12个案例教你构建可复用技能包
Langchain 最近更新的 Agent Skills 机制值得所有做 Agent 应用的人重新看一遍。它不是又加了一个 API而是把“写死工具列表 写死 Prompt”那套玩法升级成了“给 Agent 一个技能包让它自己决定怎么用”。这个转变对开发方式的冲击比想象中更大。先说判断Agent Skills 真正解决的问题是 Agent 应用里最头疼的“组合爆炸”。以前每增加一个能力你要改 system prompt、改工具注册表、改任务路由逻辑功能越多代码越碎。现在官方把这层抽象成了 Skills 架构Agent 自身负责调用、编排和决策开发者只需要把“技能”描述清楚。这意味着写 Agent 的姿势正在从“写程序”变成“写说明书 配技能包”。这篇文章会用 12 个实际案例带你拆解这套架构到底是什么能解决什么问题有哪些坑。内容偏实操建议边读边试。1. 为什么 Agent Skills 突然火起来了先说背景。Langchain 在 Agent 方向已经迭代了很多版本从最早期单纯的 Chain 串联到后来引入 ReAct、Plan-and-Execute 等多种 Agent 范式再到 Langgraph 做图状态编排。能力在变强但开发者始终面临同一个尴尬构建一个稍微像样的 Agent要把 Prompt 工程、工具定义、记忆策略、路由逻辑全部揉在一起。没有 Agent Skills 时你想让 Agent 具备“数据库查询”的能力通常要经历这些步骤在 system prompt 里描述数据库有哪些表、字段含义。写几个 Tool 函数比如query_db、get_schema注册到 Agent 的工具列表。处理 Tool 返回的原始结果再拼装成自然语言。如果数据库类型变了或者换了业务场景又得重新调 prompt 和工具参数。这个过程不难但非常琐碎。问题在于Agent 的核心价值是自主决策但开发者却在替它把每一步都规定死。Agent Skills 的思路是把一组相关的指令、工具、模板、校验逻辑打包成一个“技能”。Agent 收到用户请求后自己判断需要哪些技能再加载这个技能的上下文和工具来执行。用生活中的类比来理解传统开发方式是你请了一个员工然后给他一本极其详细的 SOP每一步都写清楚。Agent Skills 的方式是你告诉员工“你具备数据分析、报告生成、可视化三种能力”具体怎么组合完成目标员工自己决定。这个转变真正解决的是Agent 能力的标准化封装与复用。技能包可以在不同 Agent 之间共享可以在社区分发也可以按场景组合。2. 核心概念Agent、Tool、Skill 的区别开始写案例之前必须先厘清三组概念否则后面容易混。2.1 Tool 与 Skill 的关系Tool工具是 Agent 可以直接调用的函数通常是独立、原子性的比如“执行 SQL”“调用天气 API”“计算两个日期差值”。Skill技能是一个更高层的抽象它将多个工具、指令模板、上下文说明、验证逻辑组合在一起。你可以理解为Tool 一个会做某件事的函数 Skill 一套完成某类任务的能力包包含工具、规则、步骤、校验和常见错误处理一个 Skill 内部可以包含多个 Tool。Skill 不只是工具的集合还包括如何使用这些工具的知识。比如“生成数据分析报告”这个技能里面要有数据库查询工具、Markdown 模板、图表生成工具还要有告诉模型“先了解表结构、再写查询、最后生成结论”的指令。2.2 Skill 与 Prompt 的关系很多人会问这不就是把 Prompt 写长一点吗区别在于Skill 不只是 Prompt 文本它附带了可执行的工具定义、输入输出约束、验证逻辑、示例数据。Prompt 只影响模型“怎么想”Skill 还决定了模型“能做什么”。换个角度说Prompt 是给模型的提示Skill 是给 Agent 的完整能力模块。2.3 Langchain 与 Langgraph 的定位差异Langchain 是构建 Agent 应用的综合框架提供了模型接入、Prompt 管理、Tool 封装、RAG、记忆等能力。Langgraph 专注于状态化、可编排的 Agent 工作流适用于需要多轮状态管理、条件跳转、复杂分支的 Agent。Agent Skills 不是一个独立的框架而是 Langchain 层面的能力抽象。它和 Langgraph 的关系是Langgraph 负责编排 Agent 的整体流程Skills 负责定义 Agent 在某一步调用的具体能力。做一个简单的对比表维度ToolSkillLanggraph 节点粒度最小可调用单元一组能力的封装工作流中的一个执行步骤是否包含指令否只有函数逻辑是包含指令和使用说明否包含状态转移逻辑典型例子查询天气的函数完整的数据分析技能包对话管理、任务分发节点理解到这层后面的 12 个案例才看得明白。3. Agent Skills 的整体架构先看架构层面。一个完整的 Agent Skills 方案通常由 5 个层次组成模型层底层大语言模型负责理解用户请求、调用技能、生成回复。技能注册层维护一个技能清单记录每个技能的 ID、名称、描述、所需工具、适用场景。技能加载层根据用户输入动态选择技能并将技能内的指令模板、工具定义注入模型上下文。工具执行层实际执行技能内部的工具调用完成数据获取、参数计算等操作。校验与反馈层校验执行结果是否符合预期出错时负责重试或降级。在 Langchain 中一个 Agent Skill 的典型设计包括以下部分name技能名称如data_analysis_skilldescription技能描述Agent 根据描述决定是否使用该技能instructions如何使用该技能的指令注入 system prompttools技能执行时用到的工具列表templates输入输出模板validators参数或输出校验器用户的请求进来后Agent 会先判断需要哪些技能然后按需加载。3.1 架构上的变化从“代码驱动”到“声明式驱动”过去你用 Langchain 构建 Agent核心代码是agent create_react_agent(llm, tools[tool1, tool2, tool3])所有工具对 Agent 来说都是平铺的Agent 只能根据描述自行选择。一旦工具多了模型容易选错工具或者不知道该先用哪个。有了 Agent Skills 后架构变成agent create_agent_with_skills(llm, skills[skill_a, skill_b])Agent 先选择技能再在技能范围内选择工具。这相当于把“工具选择空间”先缩小到“技能选择空间”再在技能内部执行工具显著降低了模型决策难度。3.2 为什么说这套架构是分水岭传统 Agent 是“模型 工具 提示词”的三明治结构所有逻辑都暴露在开发者的代码里。而 Skills 架构把任务能力从主流程中抽离变成了可插拔的模块。这带来三个直接好处复用性提升一个“数据分析技能”可以在客服 Agent、运营 Agent、研发辅助 Agent 中复用。维护成本下降修改某个技能内部逻辑时不需要动主 Agent 代码。协作边界清晰擅长 Prompt 的成员负责写技能指令擅长工程的同学负责写技能内部工具互不阻塞。4. 环境准备与前置条件进入实操前先准备好环境。以下步骤主要针对 Langchain 的新版本具体版本号以你实际安装为准。4.1 创建 Python 虚拟环境python -m venv agent_skills_env source agent_skills_env/bin/activate # Windows 系统使用 agent_skills_env\Scripts\activate4.2 安装 Langchainpip install --upgrade langchain langchain-openai langchain-core如果你需要用到 Langgraph 来做复杂的 Agent 编排再安装pip install langgraph4.3 准备模型 API Key本文中的示例以 OpenAI 兼容接口为例。你可以在环境变量中配置export OPENAI_API_KEYyour-api-key如果你的模型服务不是 OpenAI而是国内大模型平台或其他兼容接口只需要替换 Langchain 中的模型实例即可案例的 Agent Skills 逻辑是通用的。4.4 验证环境是否正常python -c import langchain; print(langchain.__version__)打印出版本号说明安装成功。接下来我们进入案例环节。5. 12 个案例拆解从入门到进阶接下来是全文最核心的部分。12 个案例按难度递增排列从最简单的最小技能到复杂的数据分析、多 Agent 协同、工具类技能组合。建议每个案例都自己跑一遍再修改参数测试效果。案例 1定义一个最基础的 Skill以“代码注释生成器”为例演示如何定义一个最小可用的 Skill。from langchain_core.tools import tool from langchain_core.language_models.chat_models import BaseChatModel from langchain_openai import ChatOpenAI from langchain.agents import create_agent tool def get_function_code(func_name: str) - str: 根据函数名称获取项目中该函数的源代码。 # 实际项目中这里会从代码仓库读取 return def add(a, b): return a b code_comment_skill { name: code_comment_generator, description: 为指定函数生成注释输入为函数名输出为带注释的代码。, instructions: 当用户要求为函数生成注释时 1. 使用 get_function_code 获取函数源代码。 2. 分析函数逻辑。 3. 在函数定义的下一行插入功能说明、参数说明、返回值说明。 , tools: [get_function_code], } llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 将技能中的 tools 平铺给 agent并将 instructions 注入 system prompt agent create_agent(llm, tools[get_function_code], system_promptcode_comment_skill[instructions]) response agent.invoke({input: 请为 add 函数生成注释}) print(response[output])这个案例有三个关键点Skill 是 Python 字典对象最重要的是description和instructions。description用于 Agent 判断何时使用该技能instructions是技能内部的使用方法。本例没有用官方的“技能注册/加载”高级 API而是先把技能手动平铺到 agent 中。目的是让你理解技能的本质不是魔法而是“指令 工具 逻辑的组合”。输出结果时模型会根据 instructions 中的步骤顺序执行先拿代码再写注释。案例 2多工具组合技能单个工具太简单真实场景往往需要多个工具配合。以“项目周报生成”为例这个技能需要两个工具获取 Git 提交记录、获取需求列表。from langchain_core.tools import tool from datetime import datetime, timedelta tool def get_git_commits(repo_path: str) - str: 获取指定仓库最近一个工作日的 git 提交记录。 # 真实场景中会执行 git log 命令 return feat: 添加登录功能\nfix: 修复订单超时问题\nrefactor: 重构用户模块 tool def get_task_list(project_id: str) - str: 获取指定项目的任务完成情况。 return 已完成: 3个任务\n进行中: 2个任务\n待开始: 1个任务 week_report_skill { name: weekly_report, description: 根据 git 提交记录和项目任务列表生成周报。, instructions: 生成周报时 1. 先调用 get_git_commits 获取代码提交记录。 2. 再调用 get_task_list 获取任务完成情况。 3. 将两者组织成周报格式本周完成 / 存在问题 / 下周计划。 , tools: [get_git_commits, get_task_list], } agent create_agent( llm, tools[get_git_commits, get_task_list], system_promptweek_report_skill[instructions], ) response agent.invoke({input: 生成项目 PROJ-1001 的本周周报}) print(response[output])这个案例想说明的是技能内部可以有多个工具且工具之间通常有执行顺序。在这个设计里指令模板就是告诉模型“你先查代码再查需求最后汇总”。相比让模型自己摸索顺序这种显式规定成功率更高。案例 3带输入校验的 Skill实际生产中技能参数经常会被传错。比如用户让 Agent“查询上周的数据”但技能只支持“按日期查”。如果没有校验机制Agent 会拿一个模糊的时间范围去调工具然后返回一堆脏数据。我们可以在技能中加入参数校验逻辑from pydantic import BaseModel, Field class DateQueryInput(BaseModel): start_date: str Field(description开始日期格式 YYYY-MM-DD) end_date: str Field(description结束日期格式 YYYY-MM-DD) tool(args_schemaDateQueryInput) def query_sales(start_date: str, end_date: str) - str: 查询指定日期范围内的销售数据。 # 模拟查询结果 return f销售数据: {start_date} 至 {end_date}, 总销售额 100000 元 data_query_skill { name: sales_query, description: 查询销售数据只支持按日期范围查询。, instructions: 当用户查询销售数据时 1. 必须先确认开始日期和结束日期。 2. 如果用户没有提供日期询问用户。 3. 日期格式必须是 YYYY-MM-DD。 , tools: [query_sales], }这个案例的价值点是args_schema让工具具备结构化的参数约束。模型在调用工具之前会先按 Pydantic 模型校验参数。参数不对时Langchain 会要求模型重新生成符合要求的参数。实际开发中不要偷懒省掉参数校验。AI 生成的内容再聪明也可能出现错误格式。案例 4使用模板引擎生成结构化输出很多技能的输出需要固定格式比如 JSON、Markdown、HTML。只靠模型“自觉”遵守格式会不稳定比较可靠的做法是给它一个模板让它“填空式”输出。下面这个案例是“生成数据库表设计文档”table_doc_template ## 表名: {table_name} ### 字段说明 | 字段名 | 类型 | 是否必填 | 说明 | | --- | --- | --- | --- | {field_rows} ### 索引设计 {index_rows} ### 备注 {notes} tool def get_table_meta(table_name: str) - str: 获取数据库表结构元数据。 return [ {field: id, type: bigint, nullable: 否, comment: 主键}, {field: name, type: varchar(64), nullable: 否, comment: 用户名}, ] table_doc_skill { name: table_doc_generator, description: 根据表名生成数据库表结构说明文档。, instructions: 1. 使用 get_table_meta 工具获取表结构元数据。 2. 将元数据填充到 table_doc_template 模板中。 3. 最终输出完整的 Markdown 文档。 , tools: [get_table_meta], }模板方式的核心价值是减少生成式输出的不确定性。只要模板约束了结构模型输出的部分就只有内容格式是稳定可控的。如果你正在做报表、合同、代码生成、API 文档等场景建议都采用模板方案。案例 5带记忆的 SkillAgent 的上下文记忆问题一直是被问得最多的问题之一。Langchain 中记忆组件五花八门但在技能架构里记忆应该如何设计推荐的做法是把记忆设计成技能内部的一个工具而不是全局的一团状态。from langchain_core.tools import tool memory_store {} tool def save_note(key: str, content: str) - str: 保存一条笔记到长期记忆。 memory_store[key] content return 已保存 tool def get_note(key: str) - str: 读取指定键的笔记。 return memory_store.get(key, 未找到相关笔记) note_skill { name: meeting_memory, description: 记录会议中的关键结论和待办事项并在后续对话中调用。, instructions: 当用户提到会议、结论、待办事项时 1. 如果是第一次提到使用 save_note 保存。 2. 如果用户后续询问使用 get_note 查询。 3. 注意区分不同会议key 建议使用 会议名称_日期。 , tools: [save_note, get_note], }这里的关键是记忆不再是黑盒而是显式的“保存”和“读取”工具。这有 3 个好处Agent 知道自己在什么时候“记住了东西”什么时候该“调用记忆”。调试容易你可以直接查看 memory_store 里的内容。后续可以无缝替换成 Redis、向量数据库只需要改工具内部实现。案例 6数据分析类技能多步骤编排数据分析是 Agent 场景里最常见的需求之一。一个完整的数据分析技能至少包含以下步骤获取数据表结构。生成 SQL 并执行。对结果做聚合计算。输出分析结论。用一个简化示例展示from langchain_core.tools import tool tool def get_schema() - str: 获取数据库所有表的结构。 return table: orders columns: order_id, customer_id, amount, created_at table: customers columns: customer_id, name, city tool def run_sql(sql: str) - str: 执行 SQL 查询只允许 SELECT 语句。 # 生产环境需要严格校验 SQL防止注入 return 北京, 1500\n上海, 1200\n广州, 900 analysis_skill { name: sales_analysis, description: 分析销售数据输出结论和趋势。, instructions: 数据分析步骤 1. 先调用 get_schema 了解表结构。 2. 根据用户问题编写 SQL关键只允许 SELECT。 3. 调用 run_sql 执行查询。 4. 根据结果总结趋势、指出异常最后给出建议。 , tools: [get_schema, run_sql], }这个案例真正体现了 Agent 结合技能和执行能力的价值。模型负责拆解问题、编写 SQL、解读结果工具负责真实的数据访问。你自己看数据可能半天才能得出结论Agent 在几秒内就能输出一份包含结论的回复。实际项目中需要注意的地方是 run_sql 的实现必须要做安全过滤不能让模型拼接出DROP TABLE这类危险语句。案例 7RAG 检索问答技能Langchain 最经典的场景之一就是 RAG。把 RAG 做成技能好处是可以针对不同知识库配置不同的检索策略。from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings from langchain_core.tools import tool # 假设已有一个向量数据库 vectorstore FAISS.load_local(faiss_index, OpenAIEmbeddings(), allow_dangerous_deserializationTrue) retriever vectorstore.as_retriever(search_kwargs{k: 4}) tool def search_docs(query: str) - list: 在知识库中检索与问题相关的内容。 docs retriever.invoke(query) return [doc.page_content for doc in docs] rag_skill { name: internal_docs_qa, description: 基于内部知识库回答员工问题适用于制度、流程、产品文档。, instructions: 当用户询问内部制度或流程时 1. 调用 search_docs 检索相关文档片段。 2. 优先基于检索内容回答不要编造。 3. 如果检索内容不足以回答告诉用户“该问题暂未找到相关信息”。 , tools: [search_docs], }这个技能值得注意的地方是第 3 条指令。如果不加这条模型很容易在检索不到信息时强行编造答案。加上了就引导模型保守回答。做企业知识库问答时这几乎是必须的设计。案例 8代码生成 自动执行技能代码类 Agent 很受欢迎但实际使用中最怕代码生成错误、运行报错。可以把代码生成、执行、报错修复三个步骤封装在一个技能中。import subprocess tool def write_and_run_code(code: str) - str: 将生成的 Python 代码保存并运行返回执行结果或报错信息。 with open(generated_code.py, w, encodingutf-8) as f: f.write(code) result subprocess.run( [python, generated_code.py], capture_outputTrue, textTrue, timeout30, ) if result.returncode 0: return f运行成功:\n{result.stdout} return f运行失败:\n{result.stderr} coding_skill { name: python_coder, description: 编写并运行 Python 代码帮助用户解决编程问题。, instructions: 1. 根据用户需求编写完整 Python 代码。 2. 调用 write_and_run_code 执行代码。 3. 如果执行失败根据报错信息修改代码后再次运行。 4. 最终将运行结果反馈给用户。 , tools: [write_and_run_code], }这个技能模式下Agent 成为一个简单的“自动编程执行器”。测试环境可以这么玩但生产环境要非常谨慎因为让模型直接执行生成的代码有安全风险。只建议在沙箱环境、测试环境中开启。案例 9工作流路由技能一个复杂的 Agent往往内部有多个技能。技能之间不是相互独立的而是根据用户意图做路由分发。用“需求分析助手”举例它既能写 PRD也能面 SQL还能生成原型描述。路由怎样做tool def route_request(query: str) - str: 判断用户请求属于哪个技能。 if prd in query.lower() or 需求文档 in query: return write_prd elif sql in query.lower() or 数据库 in query: return write_sql else: return unknown router_skill { name: request_router, description: 将用户请求路由到合适的技能。, instructions: 当用户提出需求时 1. 先调用 route_request 判断属于哪个技能。 2. 如果路由结果是 write_prd调用 write_prd_skill。 3. 如果路由结果是 write_sql调用 write_sql_skill。 , tools: [route_request], }这个路由方案在实现上还可以升级为向量相似度匹配。把每个技能的描述向量化用户输入进来后用余弦相似度找最合适的技能。Langchain 里可以用VectorStoreToolkit做类似的事。案例 10组合式技能一个技能调用另一个技能高级场景下技能之间也需要协作。比如“生成数据分析报告”技能内部要调用“数据查询”技能和“图表生成”技能。tool def get_report_data(metric: str) - str: 获取某个指标的数据序列。 return f{metric}: 10, 15, 23, 42, 56 tool def generate_chart(data: str) - str: 将数据序列转换为图表 Markdown 代码。 images [] return images[0] composite_skill { name: data_report, description: 生成一份完整的数据分析报告。, instructions: 生成数据分析报告的步骤: 1. 使用 get_report_data 获取原始数据。 2. 使用 generate_chart 生成趋势图。 3. 综合数据和图表输出 Markdown 格式的报告。 , tools: [get_report_data, generate_chart], }这种设计把“查询数据”和“生成图表”拆成两个可复用的工具但组合逻辑依然由 Agent 完成。如果你有很多报表需求可以基于这个思路构建一个报表技能族。案例 11多 Agent 协同下的 Skills规模再大一点就需要 Langgraph 来编排多个 Agent每个 Agent 拥有不同的 Skills。比如一个“项目复盘助手”系统数据收集 Agent拥有git_log_skill、task_query_skill分析 Agent拥有metrics_calculation_skill报告生成 Agent拥有report_template_skillLanggraph 负责 Flow每个节点是 Agent每个 Agent 有自己的 Skills。下面是一个极简示意from langgraph.graph import StateGraph class AgentState(dict): messages: list def collect_node(state): # 调用数据收集 Agent内部使用 git_log_skill return state def analyze_node(state): # 调用分析 Agent内部使用 metrics_calculation_skill return state def report_node(state): # 调用报告 Agent内部使用 report_template_skill return state graph StateGraph(AgentState) graph.add_node(collect, collect_node) graph.add_node(analyze, analyze_node) graph.add_node(report, report_node) graph.add_edge(collect, analyze) graph.add_edge(analyze, report) graph.set_entry_point(collect) graph.set_finish_point(report) app graph.compile()这个案例说明了一个重要架构判断单 Agent 单技能的思路只能做 Demo生产中复杂任务要靠 Langgraph 编排多个 Agent每个 Agent 拥有专职技能。这样每个 Agent 的上下文更短、决策更准确调试也更容易。案例 12对外发布一个可复用的技能包最后一个案例是把自己开发的技能做成可复用的包分享给团队或社区。Langchain 支持自定义工具和技能封装。一个典型技能包目录如下my_agent_skills/ ├── pyproject.toml ├── my_agent_skills/ │ ├── __init__.py │ ├── analysis_skill.py │ ├── report_skill.py │ └── utils.py └── examples/ └── demo.py其中pyproject.toml声明依赖[project] name my-agent-skills version 0.1.0 dependencies [ langchain-core0.2, langchain-openai0.1 ]技能模块里把 Skill 定义导出# my_agent_skills/analysis_skill.py from langchain_core.tools import tool tool def analyze_text(text: str) - dict: 分析文本的情感倾向和关键词。 return { sentiment: positive, keywords: [高效, 稳定, 易用], } analysis_skill { name: text_analysis, description: 分析用户文本的关键词和情感。, instructions: 当用户请求分析文本时使用 analyze_text 工具。, tools: [analyze_text], }团队成员可以直接引用这个模块from my_agent_skills.analysis_skill import analysis_skill这个案例的核心价值是工程化。技能的封装和发布最终会决定团队协作效率。规范接口、版本管理、依赖声明都是实际落地中会让你少踩很多坑的细节。6. 运行结果与效果验证上面 12 个案例每个都可以独立运行。但运行只是第一步如何验证 Agent 真的“拥有”了技能才是关键。6.1 验证技能是否生效最简单的验证方式是直接输入一个覆盖技能场景的问题response agent.invoke({input: 请分析项目 PROJ-1001 的周报}) print(response[output])预期应该看到 Agent 按 Skill 中 instructions 规定的顺序执行工具先获取 git 记录再获取任务列表最后输出周报。6.2 调试手段如果 Agent 没有按预期执行技能建议做这几步检查查看模型原始调用链Langchain 支持回调回调机制通过LangSmithTracer或自定义BaseCallbackHandler来看每一步究竟调用了哪个工具。检查系统提示词确认system_prompt确实注入了技能的instructions。单测每个工具直接用 Python 调用工具函数看返回值是否符合预期。工具本身出错Agent 再聪明也没用。# 验证工具 print(get_git_commits.invoke({repo_path: /tmp/repo}))6.3 失败时的第一排查思路如果技能完全没有被调用优先检查技能的description是否清晰。description直接决定了模型是否会在正确场景触发该技能。比如查询销售数据只支持按日期范围查询这样的描述模型很容易理解。如果写成sales_data_query_function模型大概率不会触发。7. 常见问题与排查思路问题现象可能原因排查方式解决方案Agent 不调用技能description 不清晰或没有触发场景检查技能描述是否包含用户常见的说法重写 description加入同义词和典型问法工具参数传错args_schema 未定义或定义过于宽泛查看 Langchain 日志中的 tool call 参数用 Pydantic 定义严格的参数模型技能内部工具执行顺序混乱instructions 步骤不够明确在 instructions 中增加“先…再…最后…”显式规定工具调用顺序模型回答与工具返回结果不符system prompt 和工具输出之间缺少衔接指令检查 tool 结果是否被截断加长工具返回的上下文或让模型完整引用工具结果并发执行时内存溢出技能内部缓存/store 设计不当查看进程内存占用将存储迁移到 Redis 等独立中间件生产环境技能更新不生效技能代码被缓存检查 Agent 启动方式改为动态加载技能配置支持热更新工具执行报错Agent 无法恢复缺少错误恢复指令观察重试次数在 instructions 中加入“如果工具报错请尝试修复参数后重试或告知用户失败原因”数据泄露风险工具未做权限隔离审核工具对应的数据范围为不同场景配置独立的数据访问控制8. 最佳实践与工程建议8.1 技能拆分原则一个技能不应该太大也不应该太小。判断标准是技能是否具备完整的目标闭环技能是否可以被多个场景复用技能内部工具是否高度内聚比如“生成数据分析报告”可以作为一个技能但“查询数据库” “生成图表” “生成文字结论”如果拆成三个独立技能会让 Agent 面对不必要的路由压力如果硬放在一个技能里复用性又差。推荐的折中方案是把“查询数据库”做成底层能力把“生成图表”做成另一个底层能力然后再封装一个“数据分析报告”组合技能。8.2 指令模板设计建议写instructions时要避免模糊表述。看两个对比错误示范当用户查询数据时你应该分析数据并给出答案。正确示范当用户查询数据时 1. 使用 get_schema 获取表结构。 2. 编写 SQL校验 SQL 只包含 SELECT 关键字。 3. 调用 run_sql 执行查询。 4. 如果结果为空告知用户“暂无数据”不要凭空编造。 5. 输出结论时列出关键数据指标。Agent 对确定性步骤的执行成功率远高于模糊指示。把步骤拆细是成本最低也最有效的提升 Agent 性能的方法。8.3 安全与权限控制技能内部工具具有真实的执行能力必须遵循最小权限原则数据库工具只开放 SELECT 或指定表禁止 DDL、DML。文件操作工具限制在指定目录内防止路径穿越。外部 API 调用需要在网关层限制域名和频次。涉及隐私数据查询时需要接入权限校验不能让模型权限成为权限后门。安全边界是 Agent 应用落地中最严肃的部分不要因为“只是 Demo”而放松。8.4 监控与日志日志至少要覆盖用户问题原文Agent 选择了哪个技能技能内部调用了哪些工具工具执行结果摘要模型最终输出这些日志不仅是调试的依据也是你判断技能是否好用的数据来源。如果某个技能总是触发失败从日志里能很快看出来。8.5 多技能时的路由策略技能数量超过 5 个后一次把全部技能的描述都塞给模型会拉长上下文也会影响决策准确率。两种方案显式路由先用一个小的分类器或关键词规则判断意图再加载对应的技能包。向量检索路由将技能描述向量化用户请求进来后用相似度匹配 TopN 技能。Langchain 的create_retriever_tool可以辅助实现。在实战场景里显式路由通常比完全依赖模型做技能选择更稳定。8.6 版本管理与治理技能也是代码。团队协作时要纳入版本管理遵循以下规范一个技能一个目录目录内包含描述文件、工具代码、测试用例。技能变更走 MR 流程附带变更说明。对技能做版本标记Agent 端固定引用指定版本防止“昨天还能用今天不行了”。9. 对 Langchain 与 Langgraph 架构选型的建议很多读者纠结到底应该直接用 Langchain 的 Agent还是用 Langgraph 自己编排谈谈判断标准如果你的 Agent 只有 1 到 3 个技能任务链路短直接用 Langchain Agent Skills 完全够用。如果你的 Agent 需要处理多轮状态、条件分支、人工审核、超时重试使用 Langgraph 编排把每个环节做成一个节点技能放在各节点内部。还要提一下 Langchain 和 Langgraph 的关系。Langgraph 更底层的定位是“Agent 工作流引擎”Langchain 提供的是“构建 Agent 的组件库”。两者不是二选一而是可以并存Langgraph 做流程控制Langchain 提供工具、技能、模型接入能力。从当前 Langchain 的迭代趋势看Agent Skills 正在成为核心抽象层。它解决的是 Agent 开发中最痛的问题能力如何标准化如何复用如何治理这也是这篇文章最想让你理解的点Agent Skills 不是一个新功能而是一套关于 Agent 能力组织方式的架构设计。沿着这个思路做下去不只是使用一个框架的某个 API而是在建立你自己的 Agent 工程化方法论。10. 总结与后续学习方向这 12 个案例从最小技能定义、工具组合、参数校验、模板输出一直讲到多 Agent 协同和技能包发布。核心想传达的判断是Agent Skills 把“Agent 的能力”从一个抽象概念变成了一个可定义、可组合、可复用、可治理的工程对象。有了这套抽象开发 Agent 的方式会从“写死一切逻辑”变成“定义能力边界让模型在边界内自主决策”。建议你的下一步实践路径从案例 1 开始先定义一个属于自己业务场景的最简技能。跑通之后逐步增加工具、校验、指令模板。当你觉得技能变多了再引入 Langgraph 做流程编排。关注 Langchain 官方仓库中关于 Agent Skills 的更新架构还在快速迭代。如果想深入优先看这几个方向Langchain 官方文档中 Agent 与 Tool 的部分。Langgraph 教程里的多 Agent 协作例子。Pydantic 官方文档掌握参数校验工具。收藏这篇文章找个周末跑通前 5 个案例你对 Agent Skills 的理解会超过大部分人。