最近AI圈子里冒出一个挺有意思的命题Agent到底怎么从能聊天变成能干活的我翻了大量社区讨论和开源项目之后发现一个高频出现的答案是——把能力沉淀成可复用的技能库Skill Library。我手头正好在做几个Agent项目从最早的提示词堆砌到现在的技能化组织中间踩了无数坑今天就把agent-skills这个方向从头到尾拆一遍聊聊技能库怎么设计、怎么落地、怎么排查问题。如果你是刚接触Agent开发或者已经在做但被提示词工程折磨得头疼这篇应该能给你一套可以直接上手的方案。1. 项目思路拆解Agent技能库到底在解决什么问题先说清楚一个核心认知Agent和聊天机器人的本质区别在于它能不能自主完成一个任务闭环。聊天机器人是你说一句我回一句Agent则要能自己规划步骤、调用工具、检查结果、处理异常。但你真去做的时候会发现任务一复杂代码和提示词就乱成一锅粥。1.1 为什么需要技能库而不是继续堆提示词我最早做Agent的时候思路很朴素把System Prompt写长一点把所有能力和限制都塞进去让模型自己看着办。结果就是——提示词超过3000字之后大模型的表现明显不稳定经常顾此失彼每加一个功能都要去改那段几乎没人敢动的巨型Prompt改一处崩三处不同项目之间想复用能力拷贝粘贴之后改参数改着改着就和原版失去同步后来我意识到一个问题大模型本身其实不需要记住所有能力细节它只需要知道有哪些能力可以用以及每个能力是干什么的然后把具体执行逻辑交给代码。这就是技能库的核心思路——不要教模型怎么做而是给模型一套工具箱并定义清楚每个工具的使用方式。技能库的本质就是把模型需要完成的子任务和执行子任务的具体代码逻辑解耦。模型通过自然语言理解任务、选择技能、传入参数真正干活的是技能背后的函数。这样做的好处非常明显提示词大幅缩短模型只需要理解技能列表和选择规则各个技能独立维护改一个功能不影响其他功能技能天然支持跨项目复用同一种能力在不同Agent里直接用1.2 技能库的整体架构与设计定位那agent-skills这个方向的架构应该怎么搭我实操下来觉得至少需要三个层面第一层是技能注册层。这一层负责把散落的函数变成Agent可以识别的结构化描述。包含技能的名字、功能说明、参数Schema、返回值说明、适用场景和限制条件。这一层做得好不好直接决定模型能不能正确选对技能。第二层是技能编排层。这个层面负责处理Agent的一次完整任务调用链。Agent先接收用户请求理解意图然后从技能库里挑选合适的技能序列依次调用中间根据返回值决定下一步动作。编排层要处理参数传递、状态管理、异常回退这些逻辑。第三层是技能存储层。这个层面负责技能库的持久化和版本管理。技能多了以后就需要像管代码库一样管技能——谁新增的、改了什么、有没有破坏旧调用方这些问题都要有答案。这三层架构看起来不复杂但实际落地时遇到的细节问题非常多。下一步我逐个拆解。2. 核心细节解析技能定义的标准与规范技能定义是整个体系里最关键的一环。我见过很多人技能库写了不少但模型选不准技能、参数传错、调用失败率居高不下问题基本都出在定义不规范上。2.1 技能的结构化定义一份合格的技能说明书长什么样一份合格的技能定义至少包含六个要素我来逐一讲清楚技能名称要短、要能表意。我踩过的坑是用了那种非常抽象的命名比如process_data结果模型根本不知道什么时候该用。后来统一改成动宾短语比如parse_resume_file、calculate_project_cost、send_meeting_invite这种识别率一下子上来了。功能描述是给模型看的说明书这段文字的核心目标是让模型知道什么时候该用我。描述里要写清楚三件事这个技能解决什么问题、什么场景下触发、有什么边界限制。我习惯用当用户需要……时使用此技能开头后面补充限制条件比如仅处理文本文件不支持PDF格式。参数Schema用JSON Schema格式定义。这是最容易偷懒也最容易出问题的地方。有些框架支持直接传Python类型标注但为了让模型更好理解我建议每个关键参数都要有description字段说明参数含义和格式要求。比如文件路径参数一定要写清楚是绝对路径还是相对路径是否允许目录路径。返回值说明同样重要。模型拿到返回值之后要决定下一步动作如果返回值结构不清晰模型很容易迷路。我习惯把返回结构定义成一个标准的JSON至少包含status、data、message三个字段。适用场景和限制条件很多人会忽略但这两个字段在模型选技能时非常关键。如果两个技能功能上有重叠模型往往不知道怎么选这时适用场景描述就能起到决策依据的作用。最后是依赖关系。有些技能必须依赖其他技能先执行比如生成周报依赖获取本周日志先执行。把依赖关系写在定义里编排层就能自动完成顺序调度。这六要素组合起来一份技能定义大概长这样。我用Python示范一下skill_schema { name: parse_resume_file, description: 当用户需要解析简历文件内容时使用此技能。支持TXT和PDF格式返回结构化简历信息。, input_schema: { type: object, properties: { file_path: { type: string, description: 简历文件的绝对路径支持.pdf和.txt后缀 } }, required: [file_path] }, output_schema: { type: object, properties: { candidate_name: {type: string}, skills: {type: array, items: {type: string}}, experience_years: {type: number} } }, constraints: 单个文件大小不超过10MB仅支持简体中文简历, dependencies: [check_file_exists] }2.2 输入输出契约把变量传错的概率降到最低技能之间、技能与模型之间传递数据时最怕的就是格式不统一。我见过一个项目里有的技能返回字符串有的返回字典还有的直接打印日志不返回Agent拿到结果一脸懵。解决这个问题的办法就是定义统一的数据契约。我强烈建议所有技能内部处理时统一用JSON格式对外暴露的接口也要保持一致的结构。错误情况怎么办返回错误码加错误信息而不是抛异常——因为异常信息大模型读起来费劲结构化的错误码它才能正确处理。我举个实际例子某个技能依赖前面的技能拿结果参数传错了返回的是这样的错误{ status: error, code: DEPENDENCY_FAILED, message: 前置技能 fetch_calendar_events 未成功执行无法获取会议列表, suggestion: 请先调用 fetch_calendar_events 获取会议数据 }注意我加了suggestion字段。这是我在实际使用中摸索出来的技巧——直接告诉模型下一步该怎么补救比让模型自己瞎猜强太多。模型根据这个提示可以自动发起补偿流程整个任务的完成率有明显提升。2.3 技能注册与发现机制让Agent知道有什么技能可用技能库建立之后还要解决一个核心问题模型怎么知道有哪些技能主流做法有三种。第一种是全量注册。把所有的技能定义全部塞给模型场景最简单但技能多了以后Token消耗特别大。实测技能数量超过20个之后模型选技能的准确率就开始下降超过50个基本没法用了。第二种是语义检索。预先给每个技能做向量索引根据用户请求动态检索出最相关的Top K个技能再把这个子集塞给模型。这种方式适合技能数量特别多的场景。我试过技能库超过100个之后语义检索是唯一可行的方案需要额外搭一个向量检索服务。第三种是分级注册。把高频使用的核心技能常驻在系统提示词里低频长尾技能走动态检索。这算一个折中方案兼顾了选技能准确率和Token开销。我现在的主力项目就是这么做的。我踩过一个大坑刚做技能库时把所有技能一股脑塞给模型结果模型频繁选错技能把发送邮件的技能用来发消息把小规模批量处理的技能用来跑几千条数据。后来加了语义检索和场景描述错误率才降下来。3. 实操全流程从零搭建一套可用的技能库理论知识讲完了接下来进入动手环节。我不讲那种概念演示版的东西直接按我实际项目里的方式带大家过一遍完整流程。3.1 环境准备需要哪些基础组件先列一下我用到的技术栈这个组合是目前验证过比较好用的Python 3.10这是基础大模型API接入层OpenAI的接口格式目前是事实标准其他家的模型也都兼容这个格式JSON Schema校验库可以用Pydantic或jsonschema用于参数校验一个轻量级的运行时框架我目前用FastAPI做技能调度层技能库的目录结构我习惯这么组织agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册表 │ ├── calendar.py # 日历相关技能组 │ ├── mail.py # 邮件相关技能组 │ └── file_ops.py # 文件操作技能组 ├── orchestrator/ │ ├── planner.py # 任务规划模块 │ ├── executor.py # 技能执行模块 │ └── context.py # 上下文管理模块 ├── schemas/ │ └── validators.py # 参数校验器 └── skills_index.json # 技能检索索引3.2 编写第一个技能从需求到代码的完整过程我拿一个实际场景来演示——获取今日会议安排这个技能。需求很明确根据当前日期获取用户当天的会议列表。先定义这个技能的结构# skills/calendar.py skill_definition { name: get_today_meetings, description: 当用户需要查询今日会议、日程安排时使用此技能。返回当天所有会议的时间、主题、参与人。, input_schema: { type: object, properties: { date: { type: string, format: date, description: 查询日期格式为YYYY-MM-DD不传则默认当天 } } }, output_schema: { type: object, properties: { meetings: { type: array, items: { type: object, properties: { title: {type: string}, start_time: {type: string}, end_time: {type: string}, participants: {type: array, items: {type: string}} } } } } }, constraints: 仅能查询授权日历账户的数据不支持查询他人日历 }注意这里对日期的定义用了format: date同时description里写了格式要求。为什么要写这么细因为模型在生成参数的时候如果不知道日期格式可能给你传个明天或者2024年1月1日这样的自然语言值你的校验器必须有能力识别并拒绝或转换这些值。实际的执行函数长这样import json from datetime import date def execute_get_today_meetings(params): query_date params.get(date, date.today().isoformat()) try: # 这里调用日历服务的API获取会议数据 meeting_data calendar_service.fetch_meetings(query_date) return { status: success, data: {meetings: meeting_data} } except CalendarAuthError as e: return { status: error, code: CALENDAR_AUTH_FAILED, message: 日历服务授权失效请重新授权, suggestion: 需要用户重新完成OAuth授权流程 }有两点值得提醒。第一技能函数内部不要直接抛异常所有错误都转换为标准的JSON返回结构理由前面说过。第二每个技能函数都要做防御式处理哪怕你明知道某个参数是必填的也要处理缺失的情况——因为模型生成的参数有时会不合预期。技能写好之后要注册到技能注册表里# skills/registry.py class SkillRegistry: def __init__(self): self._skills {} self._index [] def register(self, definition, handler): name definition[name] self._skills[name] { definition: definition, handler: handler } # 这里可以对接向量数据库为技能描述建立索引 self._index.append(name) def search(self, query, top_k5): # 实际实现建议用向量检索 # 这里简化为关键词匹配 matched [] for name, skill in self._skills.items(): desc skill[definition][description] if any(word in desc for word in query.split()): matched.append(name) return matched[:top_k] registry SkillRegistry() registry.register(skill_definition, execute_get_today_meetings)注册的过程本质上是把技能的元数据和执行函数绑定起来。这里我留了一个search方法目前简化为关键词匹配但实际项目中我建议接到向量检索服务上后面会详细讲。3.3 技能编排层让Agent学会先规划后执行单独的技能好写难的是让多个技能协作完成复杂任务。先看一个场景用户说帮我看看明天上午有没有空档有的话约和XX的会议。这个任务至少涉及三个技能get_today_meetings获取现有日程check_availability判断是否空闲create_meeting创建新会议整条执行链路的关键在于编排逻辑。我把编排层分成三个模块来设计规划模块负责任务拆解。模型拿到用户意图后根据技能列表判断需要调用哪些技能以及先后顺序。这里我遇到一个常见问题——模型给出的调用计划不稳定同样的输入有时候一个技能够有时候会拆成三个。解决方案是在系统提示词里给出一些任务拆解范例让模型模仿范例的粒度来拆解。执行模块负责实际的技能调度。它接收规划模块的输出依次调用技能把上一个技能的输出传给下一个技能的输入。这里要注意参数映射——上一个技能返回的字段名可能和下一个技能期望的字段名不一致需要做一层映射转换。上下文管理模块负责维护整个任务的状态。比如当前执行到哪一步、已经拿到了哪些结果、还需要什么信息。这个模块很重要因为技能之间并非完全独立的后面的技能常常需要前面的技能产出的中间结果。我实现的一个简化版编排循环大致如下def run_task(user_request): # 1. 规划模型拆解任务生成技能调用计划 plan planner.create_plan(user_request, available_skills) # 2. 初始化上下文 context TaskContext(user_requestuser_request) # 3. 按计划依次执行技能 for step in plan.steps: skill registry.get(step.skill_name) # 参数映射从上下文中提取上一步的结果 params map_params(step.input_mapping, context) # 校验参数 validate(skill.definition[input_schema], params) # 执行技能 result skill[handler](params) # 更新上下文 context.update(step.skill_name, result) # 4. 根据执行结果决定是否继续 if result[status] error: recovery_action planner.handle_error(result, context) if recovery_action abort: return result elif recovery_action retry: # 重试逻辑 continue elif recovery_action ask_user: return {status: need_user_input, message: result[message]} # 5. 汇总所有结果生成最终回复 return finalize_response(context)这个循环看起来简单但实际跑起来你会发现最常出问题的就是第三步里的参数映射和第四步里的错误处理。参数映射坑在哪个位置呢比如上一个技能返回的是{meetings: [{title: 晨会, start_time: 10:00}]}下一个技能check_availability期望的参数是{occupied_slots: [10:00-11:00]}字段名和结构都对不上。这个时候就要写一个转换函数我一般会在步骤定义里加一个transform字段指定一个转换函数来处理这种格式差异。错误处理这里我还想多说一句。规划模块要根据错误类型决定下一步动作除了重试和放弃还可以选择换一个技能实现同样目标。我遇到过一种情况某个技能因为第三方服务不可用而失败但另一个技能走的是不同的API通道照样能完成目标。这种技能替代逻辑一旦实现整体任务成功率能提升好几个点。3.4 技能测试与评估怎么判断你的技能库靠不靠谱技能库写完光跑通一遍Hello World不算完要做系统性的评估。我做了一套自己的评估方案分成三个维度单技能准确率。对每个技能准备一批标准测试用例覆盖正常输入、边界输入、非法输入三类看技能是否正确执行并返回预期结果。这个指标主要暴露参数解析和业务逻辑的问题。任务完成率。把多个技能组合成端到端的任务比如根据邮件内容生成待办并创建日历提醒看整条链路完成的成功率。这个指标暴露编排层和参数映射的问题。模型选技能准确率。这个容易被忽略——提交一个用户请求看模型是否选择了正确的技能并传了正确的参数。这是Agent系统最前端的环节一旦这一步错了后面全白搭。我的测试方法是准备一个prompt测试集里面包含各种意图的用户消息然后逐条检查模型选择的技能是否合理。我强烈建议做评估的时候引入一个简单的打分逻辑def evaluate_skill_selection(user_messages, expected_skills): correct 0 total len(user_messages) for msg, expected in zip(user_messages, expected_skills): selected agent.select_skill(msg) if selected expected: correct 1 else: print(fFAIL: {msg} - 期望{expected}, 实际{selected}) return correct / total这里有个重要细节expected_skills必须是人工标注的。不要拿模型生成的标注来测试另一个模型的选技能准确率那是在自嗨。人工标注费时间但值得。一个技能库的选技能准确率如果低于85%上线后你等着的就是无穷无尽的用户投诉。4. 常见问题与排查技巧实录这个环节是全网最缺的踩坑经验基本都是拿真金白银烧出来的。我把实际项目中遇到的问题分类整理成速查表再挑几个典型案例详细展开。4.1 大模型调用环节的五个高频坑问题现象根因分析解决方案模型频繁选择错误的技能技能描述模糊或重叠模型无法区分重写description明确适用与不适用场景参数频繁传错格式参数Schema描述不够具体在description中补充格式示例和取值说明技能执行报错后任务中止错误返回结构不标准模型无法理解下一步统一错误格式并添加suggestion字段长任务执行一半丢失上下文上下文管理只保存在内存中引入持久化上下文存储技能越来越多后效果反而变差全量注册导致模型选择困难切换为语义检索或分级注册排第一位的选技能错误值得展开讲。我遇到过一个很典型的例子技能库里同时有search_web和browse_webpage两个技能前者用于搜索引擎检索关键词后者用于抓取指定网页的正文内容。用户说帮我查一下最近AI行业的大新闻模型直接选了browse_webpage结果因为没有指定网页地址直接报错。问题出在哪search_web的description写的是当用户需要搜索信息时使用模型很难区分搜索信息和浏览网页的边界。后来我把描述改成了search_web当用户提出开放式查询、需要从互联网获取信息时使用执行搜索引擎检索返回相关结果列表browse_webpage当用户指定了具体的URL地址、需要获取网页正文内容时使用输入必须包含完整URL改完之后模型几乎不会再选错了。核心经验就一条技能之间的边界越清晰模型的选技能准确率越高。宁可把描述写得啰嗦一点也要把边界条件和限制条件讲清楚。4.2 技能升级与版本管理改了旧技能影响面有多大技能库里的技能不是写一次就完事的随着业务需求变化要频繁改。我踩过的坑是一开始没有版本管理结果某个技能改了输出结构旧的调用方全崩了。举例get_today_meetings原来的返回值是{meetings: [...]}后来需求变化需要返回当天是否有空闲时段于是加了{has_free_slots: true}字段。按理论这不破坏兼容性但有一个调用方是从data.meetings里取第一条记录来默认定论会议时长的新版本多加了一个字段之后那个调用方依然正常工作问题不大。但如果我哪天把meetings改成了meeting_list那所有依赖meetings字段的技能全部GG。解决方案我给两套第一套是技能版本号。每个技能的definition加一个version字段调用方声明自己使用的版本范围。编排层发现调用方要求的版本和当前注册版本不兼容时跑兼容层转换。第二套是兼容测试。技能变更时必须跑一遍前面说的三个维度的评估尤其关注旧用例是否还能通过。如果新版本改变了输出结构旧调用方必须同步更新否则宁可保留一个旧版本技能别删。4.3 生产环境下的调试技巧技能库在本地跑没问题一到生产环境就各种异常这种经历估计大家都有。我把调试相关的经验总结成几个可操作的点日志必须结构化。技能执行链路上每个关键步骤都打结构化日志至少包含技能名称、入参、出参、耗时、错误码。这样出问题时能快速定位是哪一步出的问题而不是在茫茫文本日志里搜关键字。做一个中间的输入输出检验站。每个技能执行之前和执行之后都加一道JSON Schema校验把不符合契约的情况提前拦下来。这个校验不仅能防模型传错参数还能在技能返回异常数据时及时发现。复现问题用录播重放。线上出了偶发问题最难的是复现。我给Agent加了一个调用链录制功能把每个技能的实际调用过程和参数都记录下来。出问题时直接重放这条链路看哪一步异常比靠猜效率高太多了。我最后再分享一个调试的小技巧给模型的选择加一个置信度打分。有些Agent框架支持让模型在返回技能选择时附带一个置信度比如我90%确定应该用search_web。当置信度低于某个阈值时系统自动要求模型给出备选方案。这招在高风险场景下特别有用——宁可直接问用户你是想搜索信息还是打开某个网页也别让模型自己乱猜。5. 写在最后的个人体会Agent技能库这条路我从最开始的提示词堆砌一路走到现在最大的体会是这个问题本质上是一个工程问题。它的难点不在于让模型学会工具调用这种听起来很炫酷的概念而在于如何把一个个细节做到位——技能的边界描述够不够清晰参数的校验够不够严格编排层的错误处理够不够健壮。我见过不少团队在Agent开发上投入了大量精力模型效果一直不理想最后排查下来问题出在技能的Description写得含糊、参数校验缺失、错误处理不规范这些看起来不高级的地方。所以如果你现在也在做Agent不要急着优化大模型、换更聪明的Prompt先检查一下你的技能库基建过关没有。基建扎实了模型效果会自然上去。还要提醒一句这个领域变化很快我写的这套方法基于目前的模型能力和开源生态几个月后可能就有更好的实践出现。但有一点是确定的把能力模块化、把接口标准化、把流程可观测化这些原则不管工具怎么变都是成立的。
Agent技能库：从提示词堆砌到可复用技能体系的工程实践
最近AI圈子里冒出一个挺有意思的命题Agent到底怎么从能聊天变成能干活的我翻了大量社区讨论和开源项目之后发现一个高频出现的答案是——把能力沉淀成可复用的技能库Skill Library。我手头正好在做几个Agent项目从最早的提示词堆砌到现在的技能化组织中间踩了无数坑今天就把agent-skills这个方向从头到尾拆一遍聊聊技能库怎么设计、怎么落地、怎么排查问题。如果你是刚接触Agent开发或者已经在做但被提示词工程折磨得头疼这篇应该能给你一套可以直接上手的方案。1. 项目思路拆解Agent技能库到底在解决什么问题先说清楚一个核心认知Agent和聊天机器人的本质区别在于它能不能自主完成一个任务闭环。聊天机器人是你说一句我回一句Agent则要能自己规划步骤、调用工具、检查结果、处理异常。但你真去做的时候会发现任务一复杂代码和提示词就乱成一锅粥。1.1 为什么需要技能库而不是继续堆提示词我最早做Agent的时候思路很朴素把System Prompt写长一点把所有能力和限制都塞进去让模型自己看着办。结果就是——提示词超过3000字之后大模型的表现明显不稳定经常顾此失彼每加一个功能都要去改那段几乎没人敢动的巨型Prompt改一处崩三处不同项目之间想复用能力拷贝粘贴之后改参数改着改着就和原版失去同步后来我意识到一个问题大模型本身其实不需要记住所有能力细节它只需要知道有哪些能力可以用以及每个能力是干什么的然后把具体执行逻辑交给代码。这就是技能库的核心思路——不要教模型怎么做而是给模型一套工具箱并定义清楚每个工具的使用方式。技能库的本质就是把模型需要完成的子任务和执行子任务的具体代码逻辑解耦。模型通过自然语言理解任务、选择技能、传入参数真正干活的是技能背后的函数。这样做的好处非常明显提示词大幅缩短模型只需要理解技能列表和选择规则各个技能独立维护改一个功能不影响其他功能技能天然支持跨项目复用同一种能力在不同Agent里直接用1.2 技能库的整体架构与设计定位那agent-skills这个方向的架构应该怎么搭我实操下来觉得至少需要三个层面第一层是技能注册层。这一层负责把散落的函数变成Agent可以识别的结构化描述。包含技能的名字、功能说明、参数Schema、返回值说明、适用场景和限制条件。这一层做得好不好直接决定模型能不能正确选对技能。第二层是技能编排层。这个层面负责处理Agent的一次完整任务调用链。Agent先接收用户请求理解意图然后从技能库里挑选合适的技能序列依次调用中间根据返回值决定下一步动作。编排层要处理参数传递、状态管理、异常回退这些逻辑。第三层是技能存储层。这个层面负责技能库的持久化和版本管理。技能多了以后就需要像管代码库一样管技能——谁新增的、改了什么、有没有破坏旧调用方这些问题都要有答案。这三层架构看起来不复杂但实际落地时遇到的细节问题非常多。下一步我逐个拆解。2. 核心细节解析技能定义的标准与规范技能定义是整个体系里最关键的一环。我见过很多人技能库写了不少但模型选不准技能、参数传错、调用失败率居高不下问题基本都出在定义不规范上。2.1 技能的结构化定义一份合格的技能说明书长什么样一份合格的技能定义至少包含六个要素我来逐一讲清楚技能名称要短、要能表意。我踩过的坑是用了那种非常抽象的命名比如process_data结果模型根本不知道什么时候该用。后来统一改成动宾短语比如parse_resume_file、calculate_project_cost、send_meeting_invite这种识别率一下子上来了。功能描述是给模型看的说明书这段文字的核心目标是让模型知道什么时候该用我。描述里要写清楚三件事这个技能解决什么问题、什么场景下触发、有什么边界限制。我习惯用当用户需要……时使用此技能开头后面补充限制条件比如仅处理文本文件不支持PDF格式。参数Schema用JSON Schema格式定义。这是最容易偷懒也最容易出问题的地方。有些框架支持直接传Python类型标注但为了让模型更好理解我建议每个关键参数都要有description字段说明参数含义和格式要求。比如文件路径参数一定要写清楚是绝对路径还是相对路径是否允许目录路径。返回值说明同样重要。模型拿到返回值之后要决定下一步动作如果返回值结构不清晰模型很容易迷路。我习惯把返回结构定义成一个标准的JSON至少包含status、data、message三个字段。适用场景和限制条件很多人会忽略但这两个字段在模型选技能时非常关键。如果两个技能功能上有重叠模型往往不知道怎么选这时适用场景描述就能起到决策依据的作用。最后是依赖关系。有些技能必须依赖其他技能先执行比如生成周报依赖获取本周日志先执行。把依赖关系写在定义里编排层就能自动完成顺序调度。这六要素组合起来一份技能定义大概长这样。我用Python示范一下skill_schema { name: parse_resume_file, description: 当用户需要解析简历文件内容时使用此技能。支持TXT和PDF格式返回结构化简历信息。, input_schema: { type: object, properties: { file_path: { type: string, description: 简历文件的绝对路径支持.pdf和.txt后缀 } }, required: [file_path] }, output_schema: { type: object, properties: { candidate_name: {type: string}, skills: {type: array, items: {type: string}}, experience_years: {type: number} } }, constraints: 单个文件大小不超过10MB仅支持简体中文简历, dependencies: [check_file_exists] }2.2 输入输出契约把变量传错的概率降到最低技能之间、技能与模型之间传递数据时最怕的就是格式不统一。我见过一个项目里有的技能返回字符串有的返回字典还有的直接打印日志不返回Agent拿到结果一脸懵。解决这个问题的办法就是定义统一的数据契约。我强烈建议所有技能内部处理时统一用JSON格式对外暴露的接口也要保持一致的结构。错误情况怎么办返回错误码加错误信息而不是抛异常——因为异常信息大模型读起来费劲结构化的错误码它才能正确处理。我举个实际例子某个技能依赖前面的技能拿结果参数传错了返回的是这样的错误{ status: error, code: DEPENDENCY_FAILED, message: 前置技能 fetch_calendar_events 未成功执行无法获取会议列表, suggestion: 请先调用 fetch_calendar_events 获取会议数据 }注意我加了suggestion字段。这是我在实际使用中摸索出来的技巧——直接告诉模型下一步该怎么补救比让模型自己瞎猜强太多。模型根据这个提示可以自动发起补偿流程整个任务的完成率有明显提升。2.3 技能注册与发现机制让Agent知道有什么技能可用技能库建立之后还要解决一个核心问题模型怎么知道有哪些技能主流做法有三种。第一种是全量注册。把所有的技能定义全部塞给模型场景最简单但技能多了以后Token消耗特别大。实测技能数量超过20个之后模型选技能的准确率就开始下降超过50个基本没法用了。第二种是语义检索。预先给每个技能做向量索引根据用户请求动态检索出最相关的Top K个技能再把这个子集塞给模型。这种方式适合技能数量特别多的场景。我试过技能库超过100个之后语义检索是唯一可行的方案需要额外搭一个向量检索服务。第三种是分级注册。把高频使用的核心技能常驻在系统提示词里低频长尾技能走动态检索。这算一个折中方案兼顾了选技能准确率和Token开销。我现在的主力项目就是这么做的。我踩过一个大坑刚做技能库时把所有技能一股脑塞给模型结果模型频繁选错技能把发送邮件的技能用来发消息把小规模批量处理的技能用来跑几千条数据。后来加了语义检索和场景描述错误率才降下来。3. 实操全流程从零搭建一套可用的技能库理论知识讲完了接下来进入动手环节。我不讲那种概念演示版的东西直接按我实际项目里的方式带大家过一遍完整流程。3.1 环境准备需要哪些基础组件先列一下我用到的技术栈这个组合是目前验证过比较好用的Python 3.10这是基础大模型API接入层OpenAI的接口格式目前是事实标准其他家的模型也都兼容这个格式JSON Schema校验库可以用Pydantic或jsonschema用于参数校验一个轻量级的运行时框架我目前用FastAPI做技能调度层技能库的目录结构我习惯这么组织agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册表 │ ├── calendar.py # 日历相关技能组 │ ├── mail.py # 邮件相关技能组 │ └── file_ops.py # 文件操作技能组 ├── orchestrator/ │ ├── planner.py # 任务规划模块 │ ├── executor.py # 技能执行模块 │ └── context.py # 上下文管理模块 ├── schemas/ │ └── validators.py # 参数校验器 └── skills_index.json # 技能检索索引3.2 编写第一个技能从需求到代码的完整过程我拿一个实际场景来演示——获取今日会议安排这个技能。需求很明确根据当前日期获取用户当天的会议列表。先定义这个技能的结构# skills/calendar.py skill_definition { name: get_today_meetings, description: 当用户需要查询今日会议、日程安排时使用此技能。返回当天所有会议的时间、主题、参与人。, input_schema: { type: object, properties: { date: { type: string, format: date, description: 查询日期格式为YYYY-MM-DD不传则默认当天 } } }, output_schema: { type: object, properties: { meetings: { type: array, items: { type: object, properties: { title: {type: string}, start_time: {type: string}, end_time: {type: string}, participants: {type: array, items: {type: string}} } } } } }, constraints: 仅能查询授权日历账户的数据不支持查询他人日历 }注意这里对日期的定义用了format: date同时description里写了格式要求。为什么要写这么细因为模型在生成参数的时候如果不知道日期格式可能给你传个明天或者2024年1月1日这样的自然语言值你的校验器必须有能力识别并拒绝或转换这些值。实际的执行函数长这样import json from datetime import date def execute_get_today_meetings(params): query_date params.get(date, date.today().isoformat()) try: # 这里调用日历服务的API获取会议数据 meeting_data calendar_service.fetch_meetings(query_date) return { status: success, data: {meetings: meeting_data} } except CalendarAuthError as e: return { status: error, code: CALENDAR_AUTH_FAILED, message: 日历服务授权失效请重新授权, suggestion: 需要用户重新完成OAuth授权流程 }有两点值得提醒。第一技能函数内部不要直接抛异常所有错误都转换为标准的JSON返回结构理由前面说过。第二每个技能函数都要做防御式处理哪怕你明知道某个参数是必填的也要处理缺失的情况——因为模型生成的参数有时会不合预期。技能写好之后要注册到技能注册表里# skills/registry.py class SkillRegistry: def __init__(self): self._skills {} self._index [] def register(self, definition, handler): name definition[name] self._skills[name] { definition: definition, handler: handler } # 这里可以对接向量数据库为技能描述建立索引 self._index.append(name) def search(self, query, top_k5): # 实际实现建议用向量检索 # 这里简化为关键词匹配 matched [] for name, skill in self._skills.items(): desc skill[definition][description] if any(word in desc for word in query.split()): matched.append(name) return matched[:top_k] registry SkillRegistry() registry.register(skill_definition, execute_get_today_meetings)注册的过程本质上是把技能的元数据和执行函数绑定起来。这里我留了一个search方法目前简化为关键词匹配但实际项目中我建议接到向量检索服务上后面会详细讲。3.3 技能编排层让Agent学会先规划后执行单独的技能好写难的是让多个技能协作完成复杂任务。先看一个场景用户说帮我看看明天上午有没有空档有的话约和XX的会议。这个任务至少涉及三个技能get_today_meetings获取现有日程check_availability判断是否空闲create_meeting创建新会议整条执行链路的关键在于编排逻辑。我把编排层分成三个模块来设计规划模块负责任务拆解。模型拿到用户意图后根据技能列表判断需要调用哪些技能以及先后顺序。这里我遇到一个常见问题——模型给出的调用计划不稳定同样的输入有时候一个技能够有时候会拆成三个。解决方案是在系统提示词里给出一些任务拆解范例让模型模仿范例的粒度来拆解。执行模块负责实际的技能调度。它接收规划模块的输出依次调用技能把上一个技能的输出传给下一个技能的输入。这里要注意参数映射——上一个技能返回的字段名可能和下一个技能期望的字段名不一致需要做一层映射转换。上下文管理模块负责维护整个任务的状态。比如当前执行到哪一步、已经拿到了哪些结果、还需要什么信息。这个模块很重要因为技能之间并非完全独立的后面的技能常常需要前面的技能产出的中间结果。我实现的一个简化版编排循环大致如下def run_task(user_request): # 1. 规划模型拆解任务生成技能调用计划 plan planner.create_plan(user_request, available_skills) # 2. 初始化上下文 context TaskContext(user_requestuser_request) # 3. 按计划依次执行技能 for step in plan.steps: skill registry.get(step.skill_name) # 参数映射从上下文中提取上一步的结果 params map_params(step.input_mapping, context) # 校验参数 validate(skill.definition[input_schema], params) # 执行技能 result skill[handler](params) # 更新上下文 context.update(step.skill_name, result) # 4. 根据执行结果决定是否继续 if result[status] error: recovery_action planner.handle_error(result, context) if recovery_action abort: return result elif recovery_action retry: # 重试逻辑 continue elif recovery_action ask_user: return {status: need_user_input, message: result[message]} # 5. 汇总所有结果生成最终回复 return finalize_response(context)这个循环看起来简单但实际跑起来你会发现最常出问题的就是第三步里的参数映射和第四步里的错误处理。参数映射坑在哪个位置呢比如上一个技能返回的是{meetings: [{title: 晨会, start_time: 10:00}]}下一个技能check_availability期望的参数是{occupied_slots: [10:00-11:00]}字段名和结构都对不上。这个时候就要写一个转换函数我一般会在步骤定义里加一个transform字段指定一个转换函数来处理这种格式差异。错误处理这里我还想多说一句。规划模块要根据错误类型决定下一步动作除了重试和放弃还可以选择换一个技能实现同样目标。我遇到过一种情况某个技能因为第三方服务不可用而失败但另一个技能走的是不同的API通道照样能完成目标。这种技能替代逻辑一旦实现整体任务成功率能提升好几个点。3.4 技能测试与评估怎么判断你的技能库靠不靠谱技能库写完光跑通一遍Hello World不算完要做系统性的评估。我做了一套自己的评估方案分成三个维度单技能准确率。对每个技能准备一批标准测试用例覆盖正常输入、边界输入、非法输入三类看技能是否正确执行并返回预期结果。这个指标主要暴露参数解析和业务逻辑的问题。任务完成率。把多个技能组合成端到端的任务比如根据邮件内容生成待办并创建日历提醒看整条链路完成的成功率。这个指标暴露编排层和参数映射的问题。模型选技能准确率。这个容易被忽略——提交一个用户请求看模型是否选择了正确的技能并传了正确的参数。这是Agent系统最前端的环节一旦这一步错了后面全白搭。我的测试方法是准备一个prompt测试集里面包含各种意图的用户消息然后逐条检查模型选择的技能是否合理。我强烈建议做评估的时候引入一个简单的打分逻辑def evaluate_skill_selection(user_messages, expected_skills): correct 0 total len(user_messages) for msg, expected in zip(user_messages, expected_skills): selected agent.select_skill(msg) if selected expected: correct 1 else: print(fFAIL: {msg} - 期望{expected}, 实际{selected}) return correct / total这里有个重要细节expected_skills必须是人工标注的。不要拿模型生成的标注来测试另一个模型的选技能准确率那是在自嗨。人工标注费时间但值得。一个技能库的选技能准确率如果低于85%上线后你等着的就是无穷无尽的用户投诉。4. 常见问题与排查技巧实录这个环节是全网最缺的踩坑经验基本都是拿真金白银烧出来的。我把实际项目中遇到的问题分类整理成速查表再挑几个典型案例详细展开。4.1 大模型调用环节的五个高频坑问题现象根因分析解决方案模型频繁选择错误的技能技能描述模糊或重叠模型无法区分重写description明确适用与不适用场景参数频繁传错格式参数Schema描述不够具体在description中补充格式示例和取值说明技能执行报错后任务中止错误返回结构不标准模型无法理解下一步统一错误格式并添加suggestion字段长任务执行一半丢失上下文上下文管理只保存在内存中引入持久化上下文存储技能越来越多后效果反而变差全量注册导致模型选择困难切换为语义检索或分级注册排第一位的选技能错误值得展开讲。我遇到过一个很典型的例子技能库里同时有search_web和browse_webpage两个技能前者用于搜索引擎检索关键词后者用于抓取指定网页的正文内容。用户说帮我查一下最近AI行业的大新闻模型直接选了browse_webpage结果因为没有指定网页地址直接报错。问题出在哪search_web的description写的是当用户需要搜索信息时使用模型很难区分搜索信息和浏览网页的边界。后来我把描述改成了search_web当用户提出开放式查询、需要从互联网获取信息时使用执行搜索引擎检索返回相关结果列表browse_webpage当用户指定了具体的URL地址、需要获取网页正文内容时使用输入必须包含完整URL改完之后模型几乎不会再选错了。核心经验就一条技能之间的边界越清晰模型的选技能准确率越高。宁可把描述写得啰嗦一点也要把边界条件和限制条件讲清楚。4.2 技能升级与版本管理改了旧技能影响面有多大技能库里的技能不是写一次就完事的随着业务需求变化要频繁改。我踩过的坑是一开始没有版本管理结果某个技能改了输出结构旧的调用方全崩了。举例get_today_meetings原来的返回值是{meetings: [...]}后来需求变化需要返回当天是否有空闲时段于是加了{has_free_slots: true}字段。按理论这不破坏兼容性但有一个调用方是从data.meetings里取第一条记录来默认定论会议时长的新版本多加了一个字段之后那个调用方依然正常工作问题不大。但如果我哪天把meetings改成了meeting_list那所有依赖meetings字段的技能全部GG。解决方案我给两套第一套是技能版本号。每个技能的definition加一个version字段调用方声明自己使用的版本范围。编排层发现调用方要求的版本和当前注册版本不兼容时跑兼容层转换。第二套是兼容测试。技能变更时必须跑一遍前面说的三个维度的评估尤其关注旧用例是否还能通过。如果新版本改变了输出结构旧调用方必须同步更新否则宁可保留一个旧版本技能别删。4.3 生产环境下的调试技巧技能库在本地跑没问题一到生产环境就各种异常这种经历估计大家都有。我把调试相关的经验总结成几个可操作的点日志必须结构化。技能执行链路上每个关键步骤都打结构化日志至少包含技能名称、入参、出参、耗时、错误码。这样出问题时能快速定位是哪一步出的问题而不是在茫茫文本日志里搜关键字。做一个中间的输入输出检验站。每个技能执行之前和执行之后都加一道JSON Schema校验把不符合契约的情况提前拦下来。这个校验不仅能防模型传错参数还能在技能返回异常数据时及时发现。复现问题用录播重放。线上出了偶发问题最难的是复现。我给Agent加了一个调用链录制功能把每个技能的实际调用过程和参数都记录下来。出问题时直接重放这条链路看哪一步异常比靠猜效率高太多了。我最后再分享一个调试的小技巧给模型的选择加一个置信度打分。有些Agent框架支持让模型在返回技能选择时附带一个置信度比如我90%确定应该用search_web。当置信度低于某个阈值时系统自动要求模型给出备选方案。这招在高风险场景下特别有用——宁可直接问用户你是想搜索信息还是打开某个网页也别让模型自己乱猜。5. 写在最后的个人体会Agent技能库这条路我从最开始的提示词堆砌一路走到现在最大的体会是这个问题本质上是一个工程问题。它的难点不在于让模型学会工具调用这种听起来很炫酷的概念而在于如何把一个个细节做到位——技能的边界描述够不够清晰参数的校验够不够严格编排层的错误处理够不够健壮。我见过不少团队在Agent开发上投入了大量精力模型效果一直不理想最后排查下来问题出在技能的Description写得含糊、参数校验缺失、错误处理不规范这些看起来不高级的地方。所以如果你现在也在做Agent不要急着优化大模型、换更聪明的Prompt先检查一下你的技能库基建过关没有。基建扎实了模型效果会自然上去。还要提醒一句这个领域变化很快我写的这套方法基于目前的模型能力和开源生态几个月后可能就有更好的实践出现。但有一点是确定的把能力模块化、把接口标准化、把流程可观测化这些原则不管工具怎么变都是成立的。