Agent技能编排实战：从工具调用到稳定落地的完整指南

做Agent落地有一阵子了我最大的体会是真正让一个Agent从“能聊”变成“能干活”的关键往往不是模型本身多聪明而是你给它配的那套技能编排。项目标题里的“agent-skills”说白了就是这一整套东西——给大模型配技能、管技能、让它按正确顺序调技能的方法论。我基于自己实际做过的几个模拟项目把这套东西从头捋了一遍包括技能到底怎么定义、怎么组织、怎么执行、怎么保证它不会乱来以及那些你只在真实业务里才会踩到的坑。这篇文章不是教科书是我踩过坑之后的复盘。1. 先想清楚agent-skills到底要解决什么问题1.1 从“工具调用”到“技能封装”痛点在哪先说一个很直接的感受最早我做Agent的时候给模型塞了一大堆function calling——查天气的函数、查订单的函数、算价格的函数、发邮件的函数每个都定义清楚参数和返回结构。模型确实能调但问题马上就来了。首先是数量问题。一个稍微复杂的业务场景工具数量很快就超过三五十个模型的输入上下文被工具定义占掉一大块而且数量多了之后模型开始“选择困难”同一个意图可能同时匹配三四个相近工具经常调错。其次是质量问题。函数调用只描述“能做什么”但不描述“应该怎么做”比如一个稽查函数光说参数根本不行你还得告诉模型什么情况下要提前校验权限、什么结果算异常、要不要记录审计日志。这些约束写成函数注释也行但要么塞不进上下文要么模型根本不会认真读。这就是“技能”和“函数”本质上的区别。函数是一个可执行单元技能是一套包含执行逻辑、约束规则、失败处理和调用经验的完整能力封装。agent-skills要解决的核心问题就是让Agent在面对复杂任务时像人一样“知道有什么能力、什么时候用、用之前注意什么、出错了怎么收场”。一个朴素但重要的类比函数像是只给你一把锤子技能则告诉你锤子怎么握、什么材料不能砸、砸歪了怎么纠正以及砸完后怎么验收。1.2 技能的本质能力、规则、经验的三合一我在实操中把技能拆成三层结构这个框架建议你直接抄走第一层是能力定义就是这个技能具体执行什么动作包括输入参数、输出结构、执行的命令或API调用。第二层是规则约束包括前置条件、权限要求、可执行的环境范围、敏感操作标记、最大超时等。第三层是调用经验这是function calling里完全没有的比如“什么情况下优先用这个技能”、“哪些典型输入容易出错”、“返回结果怎么解读”。为什么要加第三层因为模型决策的时候需要“可类比的先例”。你告诉它“order_status查询接口在订单号缺失时会默认取最近一笔”它在决策时就有据可依不会拿一个空参数去撞运气。我见过很多失败的Agent项目根本问题不是模型不行而是你只给了它“工具”没给它“使用工具的经验”。1.3 典型场景哪些业务最适合先上agent-skills根据我做过的几个模拟项目最适配agent-skills的通常是这几类场景内部运营工单处理Agent需要查库存、查物流、改订单状态、发通知技能数量多且流程固定。数据分析辅助Agent需要查表、写SQL、跑脚本、渲染图表每个步骤依赖上一步结果。客服与售后Agent需要查知识库、调用退换货接口、计算赔偿金额、生成回执文案。内容生产流水线Agent需要抓素材、生成初稿、查重、排版、发布。这些场景的共性是动作多、流程长、状态依赖强、出错代价高。只靠模型“自由发挥”完全不行必须用技能把动作边界圈住同时保留模型在路径选择上的灵活性。2. 核心设计原则怎样的技能才算“好用”2.1 描述质量比代码质量更影响效果这点我排在最前面。你在写技能描述的时候不是在给程序员看是在给模型看。模型没有“常识”它只能根据你写的文本去匹配意图。描述要是写得模糊调用效果一定打折。举个真实对比。一个查询库存的技能两种描述方式差获取商品库存数量。参数sku_id, warehouse_id好根据商品SKU和仓库编码查询实时可售库存。适用于用户询问还有货吗库存多少什么时候补货等场景。注意本技能只返回当前可售库存不包含在途库存若仓库编码为空默认查询所有仓库并返回汇总值当返回结果中stock_level字段为LOW时建议结合补货计划技能判断是否要提示用户等待。同一个技能第二种描述让模型的命中率和参数填充完整度提升非常明显。核心原因是你给了模型“什么时候用”和“返回值怎么解读”的决策上下文相当于把资深运营的判断经验直接压缩进了技能描述里。2.2 输入输出Schema要“松进严出”这是我在设计技能Schema时最核心的一条原则。所谓“松进”是指输入参数要容忍自然语言的模糊性尽量给模型留出归一化的空间所谓“严出”是指输出结构必须严格稳定字段含义、类型、枚举值都要明确。比如一个时间参数松进的接收方式可以是一个自然语言日期字符串技能内部做解析而不是强逼模型传一个精确的ISO格式。原因很简单模型从对话中抽取用户说“后天下午”再转成ISO格式中间的转换失误率比你想象的高。与其让模型做这种它不擅长的转换不如在技能执行器里做规则归一化。输出的严则是另一回事。所有技能返回给模型的结果必须是一个固定结构的JSON至少包含status、data、message三个字段。为什么必须这样因为Agent的后续决策完全依赖这个返回结果来做判断。如果返回结构飘忽不定模型就很难决定下一步是重试、换技能还是直接答复用户。我在项目中遇到过最离谱的情况是某个查询接口把成功和失败的返回结构写成了两套模型直接把错误结构当成正常数据解析导致连锁误判。2.3 可观测性与回退机制要提前设计技能不能是个黑盒。每一次调用无论是成功还是失败都要有日志、有轨迹、有可解释性。我在工程里要求每个技能至少要记录以下几类信息触发原因模型是看到了哪句用户输入、哪个上文状态才决定调用这个技能的。参数快照模型实际填入的参数包括被默认值补全后的完整参数。执行耗时分网络请求时间、内部处理时间分别统计。结果摘要返回给模型的最终结果以及结果中的关键状态字段。失败归因如果失败是参数错误、权限不足、依赖服务异常还是业务规则拦截。回退机制也同样重要。我在每个技能执行器外面包了一层统一的重试与回退策略对瞬时错误超时、限流最多重试两次指数退避对业务规则错误不重试直接返回给模型并附上可读的失败原因对连续性失败要给模型一个“替代路径”提示比如库存查询失败时提示可以改用缓存查询技能。2.4 目录化组织与命名规范技能数量一旦过30命名和目录组织就成了一件正经事。我使用的命名规范是“领域.动作.对象”三段式例如order.query.status、inventory.query.stock、logistics.track.package。这样做有三个好处一是Registry里搜索可以做到前缀匹配二是模型在歧义场景下能通过命名空间感知大方向三是后续做权限控制时能按前缀批量授权。目录层面我分成三层core核心通用技能如参数清洗、日期解析、domain业务域技能如订单、库存、物流、specialized特定场景专用技能如大促库存盘点、售后赔付计算。这个分法不是为了好看是方便配权限和灰度发布。新技能先放到specialized跑一阵子指标稳定了再提升到domain这是个非常划算的发布策略。3. 从零实现一套agent-skills完整实操流程3.1 定义技能注册表与Schema模板我这个Skill模块的核心是一个注册表所有技能统一上报统一校验统一分发。先给出我用的Schema模板JSON格式这份东西基本可以直接复用{ name: inventory.query.stock, version: 1.2.0, description: 根据商品SKU和仓库编码查询实时可售库存..., category: domain.inventory, tags: [库存, 补货, 销售], permission: inventory:query, timeout_ms: 3000, max_retries: 2, input_schema: { type: object, properties: { sku_id: { type: string, description: 商品SKU编码必填, required: true }, warehouse_id: { type: string, description: 仓库编码可选默认查全部, required: false }, date: { type: string, description: 查询日期支持自然语言由执行器统一解析, required: false } } }, output_schema: { type: object, properties: { status: { type: string, enum: [success, fail, denied] }, data: { type: array, items: { type: object, properties: { sku_id: { type: string }, warehouse_id: { type: string }, available_qty: { type: integer }, on_transit_qty: { type: integer }, stock_level: { type: string, enum: [HIGH, MEDIUM, LOW, EMPTY] } } } }, message: { type: string } } }, rules: [ 仓库编码为空时默认查全部仓库并返回汇总行, stock_level为LOW时返回数据中同时给出最近补货ETA, 本技能不返回在途库存查询在途需调用logistics.transit.query ], examples: [ { user_input: 这款手机还有货吗, filled_params: { sku_id: SPU00123, warehouse_id: }, result_summary: 返回全国可售库存汇总stock_level为MEDIUM }, { user_input: 杭州仓的小米手环还有多少, filled_params: { sku_id: SKU99887, warehouse_id: HZ-01 }, result_summary: 返回杭州仓可售库存共235件 } ] }这套Schema里面有几个字段值得单独说明。permission字段看似简单实际是后续接权限系统的基础如果一个技能没有对应的权限码执行器在入口就要直接拒绝。examples是我后加的效果出奇好——模型在few-shot场景下参考样例来填参数正确率提升了一截。rules不是给人看的是每次调用时拼进模型上下文里去约束行为用的。3.2 实现技能执行器与调用链注册表只是目录真正干活的是执行器。我写了一个统一分发器核心逻辑是先校验权限再做参数归一化然后执行具体技能函数最后包装输出。# skill_router.py import time import threading from typing import Any, Dict class SkillContext: 一次技能调用的上下文贯穿整个生命周期 def __init__(self, skill_name: str, params: Dict[str, Any], user_id: str): self.skill_name skill_name self.params params or {} self.user_id user_id self.trace_id f{skill_name}-{int(time.time()*1000)} self.start_ts time.time() self.steps: list[dict] [] def log_step(self, action: str, detail: dict): self.steps.append({action: action, detail: detail, ts: time.time()}) class SkillRegistry: 技能注册表所有技能在这里上报与校验 def __init__(self): self._skills: dict[str, dict] {} self._executors: dict[str, callable] {} def register(self, schema: dict, executor: callable): name schema[name] if name in self._skills: raise ValueError(fduplicated skill: {name}) self._skills[name] schema self._executors[name] executor def get_system_prompt_block(self, category: str None) - str: 生成给模型看到的技能说明块按目录过滤避免一次性塞太多 lines [] for name, schema in self._skills.items(): if category and not name.startswith(category): continue lines.append(f- {name}: {schema[description]}) if schema.get(rules): for r in schema[rules]: lines.append(f 规则: {r}) return \n.join(lines) def dispatch(self, skill_name: str, params: dict, user_id: str): ctx SkillContext(skill_name, params, user_id) schema self._skills.get(skill_name) if not schema: return {status: fail, data: None, message: funknown skill: {skill_name}} # 1. 权限校验 perm schema.get(permission) if not check_permission(user_id, perm): return {status: denied, data: None, message: fpermission denied for {perm}} ctx.log_step(permission_check, {perm: perm, pass: True}) # 2. 参数归一化 normalized normalize_params(schema.get(input_schema, {}), ctx.params) ctx.log_step(params_normalize, {raw: ctx.params, normalized: normalized}) # 3. 执行技能 try: executor self._executors[skill_name] result executor(normalized, ctx) return result except SkillTimeoutError: return {status: fail, data: None, message: skill execution timeout} except Exception as e: return {status: fail, data: None, message: fskill error: {str(e)}}有几个实现细节值得展开。第一get_system_prompt_block不是把所有技能一股脑全塞给模型而是按任务场景动态组装。任务一开始只给最相关的领域技能等Agent进入了某个子路径再补充特定技能。这个动态注入的做法对上下文窗口的利用效率提升非常明显。第二参数归一化统一放在执行前并且把原始参数和归一化后的参数都记录到日志里这样后面定位问题的时候能一眼看出模型到底填了什么。第三权限检查不是等到执行器内部再做而是在分发阶段就拦掉避免无关代码被调用、无关日志被打出来。3.3 三种技能类型的封装模板根据实际业务我把技能分成三类分别给出封装模板。API调用类比较简单你只需要把外部接口封装进来重点是超时控制和错误码翻译。# api_skill_template.py import requests def http_get_json(url, paramsNone, headersNone, timeout3): 通用GET请求封装带超时与状态码检查 try: resp requests.get(url, paramsparams, headersheaders, timeouttimeout) resp.raise_for_status() data resp.json() return {status: success, data: data, message: ok} except requests.Timeout: return {status: fail, data: None, message: 请求超时请稍后重试} except requests.HTTPError as e: code e.response.status_code if code 403: return {status: denied, data: None, message: 接口权限不足} if code 429: return {status: fail, data: None, message: 接口限流建议稍后重试} return {status: fail, data: None, message: f接口错误:{code}}脚本执行类适合数据分析、文件处理等场景核心是必须做超时保护和输出捕获。# script_skill_template.py import subprocess import os def run_python_script(script_path: str, args: list, timeout_sec: int 10): 执行一个受控的Python脚本并捕获stdout/stderr proc subprocess.run( [python3, script_path] args, capture_outputTrue, textTrue, timeouttimeout_sec, cwdos.getcwd() ) if proc.returncode ! 0: return {status: fail, data: None, message: proc.stderr[-500:]} return {status: success, data: proc.stdout, message: ok}用subprocess执行脚本的时候有个容易踩的坑如果不指定cwd脚本默认在Agent服务的当前目录下执行如果服务目录下有权限问题会直接报错。另外输出捕获一定要加长度限制否则脚本可能一次性刷出几MB日志直接把模型的输入上下文挤爆。交互引导类这是Agent特有的技能它不是去调外部系统而是引导用户走流程。比如“售后材料收集技能”它自身不完成业务只是按照预设顺序向用户索取订单号、凭证照片、问题描述校验完整性后转交给后端工单系统。这种技能的Schema要设计成“阶段性交互”不能一次性把问题全问完。3.4 技能编排与规划让Agent自己选技能单个技能授好了接下来就是决定让Agent怎么选、怎么排的问题。我做过两种路线各有适用场景。第一种是纯Prompt路线把技能目录和规则都塞给模型让它自由规划调用顺序。优点是灵活适合探索型任务缺点是没有约束模型规划的路径可能时好时坏。第二种是“计划-执行-验证”循环Agent先根据任务目标生成一个调用计划然后逐个执行技能每个技能执行完根据返回结果决定是继续执行下一个还是调整计划。我用的比较多的是第二种具体流程是这样Agent收到任务后先从技能注册表拉取当前可用的技能目录然后生成一个初步的调用计划。每执行完一个技能把返回结果拼回上下文再让模型判断计划是否需要调整。遇到失败或异常结果时模型必须尝试一次替代路径替代路径也失败才向用户求助。这个流程有个关键控制点计划生成的“颗粒度”要适中不能细到每一步都说清楚——这样太耗token也失去了Agent的灵活性也不能粗到一句话交代完——那样跟没规划没区别。经验值是把一个计划控制在3到5步每步只说明要调用的技能名和期望目标即可。4. 权限边界与安全设计技能越权是最大的坑4.1 最小权限原则怎么落地Agent的技能比普通API接口危险得多因为模型可能根据用户的一句话就触发一连串调用。这意味着技能必须做到最小权限每个技能只保留完成自身职责所需的权限绝不贪多。我在权限设计上借鉴了云平台的IAM思路技能与权限码一一对应技能执行前通过统一权限校验。用户的权限集是动态的不同用户看到的技能目录不同。权限码缺失时技能对模型不可见而不是显示之后调用失败。这个细节很重要因为模型看到一个技能存在但调用被拒它会反复尝试白白浪费上下文。敏感操作转账、改订单、删除数据除了权限校验还需要二次审批。我实现了一个“待确认执行”模式Agent识别到敏感技能时不是直接执行而是生成一个执行预案让用户确认用户确认后技能才会真正被调用。注意权限校验不只要在技能分发层校验一次在执行器内部也要再校验一次。原因是有时候技能A被授权调用但技能A内部的某个分支逻辑会间接触发超出A权限范围的动作。双校验是防止此类越权的兜底。4.2 沙箱隔离与危险操作熔断脚本类技能是最容易出安全事故的地方。我的处理方式是统一放进沙箱执行创建独立的执行用户权限只包含脚本目录的读写其余一律拒绝。限制CPU、内存、文件大小、网络访问。默认禁止脚本访问外网需要外网时在技能Schema中显式声明。禁止脚本删除任何文件只能写入特定输出目录。同一时间还要配置熔断策略。如果一个技能在短时间内触发连续三次业务规则错误直接对该技能做熔断自动切换到备用技能路径同时把这个事件记录到告警系统。熔断是为了防止模型在某个错误状态下反复触发同一个问题技能把下游系统打挂。我在实测中就遇到过让Agent处理批量库存同步任务时某个技能的鉴权参数在会话中丢失模型连着调了十几次全部返回401虽然不致命但在真实生产中这个频率足以触发下游的限流报警。5. 常见问题与排查技巧实录5.1 为什么Agent总是不调用技能这是最让人崩溃的问题之一明明技能都注册好了模型就是不用。我排查下来最常见的原因有三个。第一技能描述里缺少“触发信号”。模型不知道什么情况下该用这个技能。解决办法是在描述中加入明确的触发条件给出典型用户语句的示例。第二技能名和用户意图之间的“语义距离”太远。比如用户说“这单能不能明天送到”模型需要从这句话理解到要调物流查询和时效预估两个技能如果你的日志显示模型完全没往这个方向规划就得检查技能目录的语义覆盖度。第三技能描述与系统提示词之间存在矛盾。我踩过的一个真实坑是系统提示词里写着“先用文本回答客服问题”而技能描述里又说“当用户询问时效时直接调用时效预估技能”两者互相冲突模型的行为就难以预测。解决方案是检查系统提示词与技能描述的一致性不要让规则打架。5.2 技能调用时参数总填不对参数错误是仅次于“不调用”的高频问题主要是类型错误和语义偏差。类型错误比如要求传整数但模型传了字符串。我一般把类型约束放到执行器里做强制转换而不是依赖模型自觉。语义偏差则复杂些比如技能要求“数量”参数传订单总行数模型却理解成传商品件数。这种问题的根源通常是字段名和描述信息不明确要把字段的语义边界写清楚最好给正反两个例子。最关键的一个技巧是不管模型传什么参数执行器里都要有一层默认值兜底绝不能因为缺少某个非必填参数就全盘失败。缺失的参数如果能从上下文中推断出来就自动补全推断不出来给默认值并记录日志。这样既提高了调用成功率也为后续优化参数模板积累了数据。5.3 技能执行超时怎么办Agent技能的超时比普通API超时更讲究。普通API超时后用户只会觉得慢Agent技能超时可能引发连锁反应——Agent会在超时结果上继续做推理从而给出一个基于错误状态的结论。我设置超时的策略是分层短超时加快速回退内部执行超时设定在2到3秒超过就迅速返回失败并附带可读的失败原因让模型可以当场决定是重试、换技能还是向用户解释。必要的时候开一个异步技能通道让耗时任务先返回“任务已受理结果请稍后查询”而不是干等。超时重试必须用指数退避不能立刻重试。我曾见过一个技能超时后模型立刻重试接着又超时又在重试最后硬生生把下游接口拖到熔断。指数退避至少能缓解这种情况。5.4 技能爆炸工具太多模型反而不会用了技能数量超过50个以后上下文塞满技能描述模型的理解准确率肉眼可见地往下掉这个现象我称之为“技能爆炸”。解决办法是用模块化目录加动态加载不同任务只加载对应的技能子集控制单轮可见技能数量在15个以内。相关的技能目录做前缀聚合把多个技能打包成一个“技能组”让模型先选组再选具体技能。5.5 常见问题速查表现象可能原因排查动作模型不调用技能触发信号不清 / 系统提示词冲突检查技能描述是否有典型触发语句检查系统提示词与技能规则是否矛盾参数填错字段语义不明 / 类型未约束对照调用日志看模型传参原始值补充字段边界说明和正反例技能反复失败权限缺失 / 下游接口限流看返回的status字段是denied还是fail熔断策略是否生效技能响应慢下游接口无超时 / 串行调用太多检查技能执行器是否设置了短超时是否可改为异步技能上下文被技能描述占满单次注入技能过多按任务动态加载技能子集控制可见技能数量模型做出超权限动作权限模型缺失或校验不全检查技能分发层和执行器是否双校验敏感技能是否配置二次确认6. 扩展思考从“会调用”到“会规划”还有多远做到这里agent-skills已经能让Agent稳定地“调用技能”。但要是再往下走一层你会发现真正的分水岭不是“会调用”而是“会规划”——理解目标、拆解任务、选择路径、预判风险。我在尝试的一个进阶方向是给技能增加“依赖声明”让技能注册表本身变成一张有向依赖图。这样Agent规划任务时不是凭空想象流程而是在这张图里找可行路径。比如用户问“我要退一个质量问题商品顺便把运费也退了”系统可以先在依赖图里定位到退款技能依赖退款资格核验技能核验又依赖订单状态查询技能然后自动生成一条校验过的调用链。这一步做到了技能就从一个静态工具集合升级成了半自动的流程编排器。另外我也在把技能的调用日志持续回流到描述生成中。每次失败后把失败类型归因写回技能的规则字段里比如“注意当订单已处于已发货状态时本技能返回failure请先调用logistics.cancel拦截快递”。这样技能会越用越聪明形成数据飞轮。虽然现在这部分自动化程度还不高但方向值得持续投入。我实际运营这套agent-skills体系到现在最常见的感受就是模型能力拉不开差距的时候技能系统的工程质量就是那个拉开差距的东西。你精心设计的每一个技能描述、每一次权限校验、每一条回退规则最后都会体现在用户可感知的稳定性和可用性上。如果你也开始做Agent别急着把几十个接口堆给模型先沉下心把技能层做好回报率远比调Prompt要高得多。