Agent技能体系实战：从Function Calling到工程化编排

1. 为什么我要做一套 Agent 技能体系从一次失败的项目复盘说起1.1 现象模型会聊天但不会干活的尴尬期去年我在做一个企业内部的知识库问答 Agent最开始方案很朴素把文档切好片、做向量召回、塞给大模型生成回答。跑通 demo 只花了两周效果看着还不错领导挺满意。但一到真实业务场景就露馅了——用户问帮我查一下上个月的支出报表Agent 确实能从知识库找到报表模板但它不会真的去财务系统拉数据也不会按模板生成 PDF更不会通过邮件发给指定人。换句话说Agent 只会说不会做。这个阶段我踩过一个大坑尝试把所有工具调用逻辑全部写进 system prompt让模型自己判断什么时候调什么工具。结果就是 prompt 越写越长模型越来越选择困难经常在前三步就晕头转向。后来我意识到问题压根不在 prompt 工程而在于整个 Agent 的架构设计里缺少一个技能层——模型需要的不只是工具清单而是一套能被理解、能被调度、能被稳定执行的技能体系。1.2 本质技能不是模型自带的是需要工程化的什么是 Agent 的技能我当时的理解比较浅以为就是注册几个函数、定义好参数让模型调用就行了。但真正做过之后才发现技能应该是一个完整的能力单元它至少包含四件事可被模型正确理解的调用意图即这个技能是干什么的、什么时候该用规范化的输入输出接口模型得知道要传什么参数、能得到什么结果可执行的业务逻辑这层可以是代码、脚本、API 调用链甚至人工审批环节异常处理机制技能执行失败了怎么办怎么回退、怎么告诉模型。所以 agent-skills 这个项目本质上不是某个炫酷的大模型应用而是一套解决模型如何稳定调用外部能力的工程方法论。我一开始用 OpenAI Function Calling 做基础后来切换到本地开源模型Qwen、GLM 这些发现不同模型对工具调用的理解差异很大这就倒逼我把技能定义做得更通用、更严谨。这个项目的目标读者是完全不满足于做个聊天机器人的开发者。如果你正准备让 Agent 干点实际工作比如自动处理工单、操作内部系统、跑数据分析流程那这套技能体系的思路应该能帮到你。2. 技能体系的三个核心设计定义、注册、编排2.1 技能描述模型能否正确触发全看这一步先说技能描述的作用。用过 Function Calling 的朋友都知道每个函数要写一个 description模型的触发准确率很大程度上就压在这段描述上。但在我实际测试中单一函数描述远远不够特别是技能数量超过 20 个之后模型经常把相似技能搞混。我的做法是把技能描述拆成五个独立字段name技能唯一标识全局不可重复description一句话说明技能功能注意这句话要站在模型视角写是描述这个技能能帮模型完成什么目标而不是给人类看的文档when_to_use显式告诉模型什么场景下应该调用甚至可以明确写不要在 XX 场景使用input_schema输入参数定义每个参数都要写明类型、是否必填、含义、枚举值output_format输出结构定义让模型知道拿到结果后怎么接。举个例子一个创建知识库文档的技能描述我一开始写得特别简短Create a document in knowledge base。结果模型在用户问帮我把这段内容存进资料库时死活不触发这个技能反而去调搜索知识库。改成更完整的描述后触发率从 67% 涨到了 94%。提示when_to_use 这个字段是我的经验优化效果非常明显。大模型看长文本时会做注意力分配明确的正反面示例能让它更快锁定技能。2.2 技能注册中心告别一把梭引入可管理性有了技能定义接下来要考虑的是技能从哪来、怎么加载、怎么更新。我第一次做的时候把所有技能写在一个 Python 文件里函数直接注册。技能少没问题一旦技能多起来每次修改都要发版重部署代价太高。我参考微服务注册中心的想法做了一个轻量的技能注册表。所有技能通过 JSON 描述文件注册每个技能对应一个目录里面包含 skill.yaml元信息、main.py执行逻辑、schema.json参数定义、tests.py自测脚本。技能引擎启动时扫描全部技能目录加载到内存里形成一个可查询的技能索引。技能注册中心的作用不只是管理文件它还为 Agent 提供两个关键能力通过语义检索筛选候选技能模型不需要看到全部技能只加载与当前任务最相关的 5 到 10 个大幅节省上下文空间支持技能版本管理灰度发布时可以先让一小部分流量走新版本技能稳定后再全量切换。技能注册中心的实现并不复杂但要做好约定。我的约定是技能目录名必须等于技能 name不允许嵌套所有路径都用相对路径。这些约定看着死板在实际协作中却省了很多沟通成本。2.3 技能编排单技能是零件多技能组合才是产品单一的技能只能完成原子操作真正让 Agent 变得有用的是把多个技能按一定的逻辑编排起来。这里我不建议用传统的工作流引擎去做太重了Agent 场景天然需要动态决策你没法提前把所有流程固化下来。我采用的编排方式是基于模型的计划-执行-反思循环Plan模型读取用户请求结合候选技能列表生成一个执行计划Execute依次执行计划中的技能每一步执行前先让模型确认参数Observe将技能执行结果返回给模型由模型判断结果是否符合预期Reflect如果结果不对模型要决定是重试、换技能还是回退到让用户澄清。这个循环里最关键的是执行计划的表达方式。我用自然语言加参数列表描述计划而不是强 JSON 格式原因是模型生成自然语言更稳定JSON 经常出现格式错误。用户提问帮我把库存低于 10 件的商品列出来并生成告警邮件Agent 生成的执行计划是调用query_inventory技能参数为 threshold10调用generate_alert_email技能参数为商品列表调用send_email技能参数为收件人和邮件内容。每个步骤执行完模型都会拿到真实结果并决定下一步。这套编排机制看起来很朴素但它的优势在于每个技能只需关注自己那部分逻辑复杂度被隔离在技能内部模型反而更容易做出正确的调度决策。3. 实操从零手写一套轻量 agent-skills 技能加载与执行框架3.1 环境与架构选型我知道很多朋友喜欢用现成的 Agent 框架比如 LangChain、AutoGen。但如果你要深度定制技能体系我建议至少自己写一层原因后面会讲。这里我选择的是 Python 3.10 FastAPI主要考虑是生态成熟、写起来快而且和现有业务系统集成方便。先看项目的目录结构agent-skills/ ├── skills/ # 技能目录 │ ├── query_inventory/ │ │ ├── skill.yaml │ │ ├── schema.json │ │ ├── main.py │ │ └── tests.py │ ├── send_email/ │ │ ├── skill.yaml │ │ ├── schema.json │ │ ├── main.py │ │ └── tests.py │ └── ... ├── registry.py # 技能注册与加载 ├── executor.py # 技能执行器 ├── scheduler.py # 技能编排计划-执行-反思 └── api.py # Agent 服务入口关键依赖只有两个PyYAML解析技能元信息和 FastAPI提供 HTTP 接口。没有引入重量级框架保持核心逻辑可控这是我吃过 LangChain 版本升级的亏之后的教训——框架封得太死底层一升级你的代码就要跟着改。3.2 定义好第一个技能query_inventory技能元信息用 YAML 写简单清晰。我先写 skill.yamlname: query_inventory description: 查询商品库存数量支持按商品 ID 或按库存阈值筛选 when_to_use: 当用户需要了解商品库存情况、库存不足告警、补货决策时使用 when_not_to_use: 当用户询问订单物流状态时不要使用 version: 1.2.0再看 schema.json定义输入参数{ type: object, properties: { product_id: { type: string, description: 商品唯一ID支持批量多值用逗号分隔 }, threshold: { type: integer, description: 库存阈值只返回库存低于该数值的商品 } }, oneOf: [ {required: [product_id]}, {required: [threshold]} ] }这里注意一个细节我没有把 product_id 设置成必填因为阈值查询场景根本不传它。但如果不做 oneOf 约束模型可能会两个参数都传产生歧义。所以在 schema 里写清楚逻辑约束比依赖模型自己理解要可靠得多。main.py 是技能的执行逻辑。以伪代码演示import json from .db import get_inventory def run(ctx, params): 执行库存查询。 ctx 中携带了必要的上下文信息如当前用户、租户ID、日志句柄等。 params 是经过 schema 校验后的输入参数。 threshold params.get(threshold) product_id params.get(product_id) if product_id: data get_inventory(product_idsproduct_id.split(,)) elif threshold is not None: data get_inventory(thresholdthreshold, low_stockTrue) else: raise ValueError(product_id 与 threshold 不能同时为空) # 返回结构化结果方便模型读取 return { status: success, items: data, summary: f共查询到 {len(data)} 条库存记录 }技能执行器的逻辑是先校验 schema再执行业务代码。我先调用 jsonschema 校验参数校验不通过直接返回语义化的错误给模型提供修正参数的机会而不是抛出 Python 堆栈。这一步相当关键因为模型生成的参数本来就容易出错如果错误信息人类都读不懂模型更读不懂。3.3 写好注册中心让技能即插即用registry.py 的任务是启动时扫描所有技能目录把元信息和执行函数加载到内存。核心逻辑如下import yaml import json import importlib.util from pathlib import Path SKILLS_ROOT Path(__file__).parent / skills class SkillRegistry: def __init__(self): self._skills {} def load_all(self): for skill_dir in SKILLS_ROOT.iterdir(): if not skill_dir.is_dir(): continue self._load_skill(skill_dir) print(f已加载 {len(self._skills)} 个技能) def _load_skill(self, skill_dir: Path): # 读取元信息和 schema meta yaml.safe_load( (skill_dir / skill.yaml).read_text(encodingutf-8) ) schema json.loads( (skill_dir / schema.json).read_text(encodingutf-8) ) # 动态加载 main.py 中的 run 函数 spec importlib.util.spec_from_file_location( fskills.{meta[name]}.main, skill_dir / main.py, ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) self._skills[meta[name]] { meta: meta, schema: schema, run: module.run, } def list_skills(self, query: str None, top_k: int 10): 这里可以用 embedding 检索候选技能也可以简化为关键词匹配。 我的实现是接了一个本地 embedding 模型对 query 与技能描述做余弦相似度排序。 # 省略 embedding 细节 return ranked_skill_names这个注册中心的重点不是加载本身而是它承担了技能候选筛选的职能。原始系统把所有技能描述都硬塞给模型上下文炸裂现在系统只在每个 Agent 请求进来时从注册中心召回 5 到 10 个候选技能再把这些技能的描述拼接给模型。这一步改动让模型的工具选择准确率提高了近 20 个百分点。关于动态加载用的 importlib 方案在开发期方便改代码不用重启服务但生产环境建议改成更稳妥的加载方式因为 importlib 一旦加载同一个模块名容易产生缓存污染我在 4.2 小节会讲这个坑。3.4 执行器与编排循环让模型按计划干活executor.py 的核心是一个 execute 函数负责安全地运行技能并捕获异常import inspect import traceback class SkillExecutor: def __init__(self, registry: SkillRegistry): self.registry registry def execute(self, skill_name: str, params: dict, context: dict): skill self.registry.get_skill(skill_name) if not skill: return { status: error, error_type: skill_not_found, message: f技能 {skill_name} 不存在请检查技能名称 } # 参数校验 import jsonschema try: jsonschema.validate(params, skill[schema]) except jsonschema.ValidationError as e: return { status: error, error_type: invalid_params, message: f参数校验失败: {e.message}请修正参数后重试 } # 执行技能 try: result skill[run](context, params) return {status: success, result: result} except Exception as e: traceback.print_exc() return { status: error, error_type: execution_failed, message: f技能执行出错: {str(e)} }然后到 scheduler.py这是整个 agent 的大脑。它把计划-执行-反思循环落地。下面是一段关键流程伪代码def run_agent_task(user_request: str, context: dict): # 1. 技能候选筛选 candidate_skills registry.list_skills(user_request, top_k8) system_prompt build_system_prompt(candidate_skills) # 2. 让模型生成执行计划 plan llm.chat( system_prompt, f请根据用户请求生成执行计划。\n用户请求: {user_request} ) # 3. 循环执行计划中的每个步骤 for step in parse_plan(plan): skill_name step[skill] params step[params] result executor.execute(skill_name, params, context) if result[status] error: # 4. 反思把错误信息反馈给模型让它决定下一步 correction llm.chat( system_prompt, f步骤 {skill_name} 执行失败错误信息: {result[message]}。 f请给出修正后的参数或选择其他技能或要求用户补充信息。 ) if correction[action] retry: params correction[params] result executor.execute(skill_name, params, context) elif correction[action] ask_user: return {need_user_input: correction[question]} else: return {status: failed, reason: result[message]} context[last_result] result[result] return {status: success, final_result: context[last_result]}表面看这只是一个 while 循环加两次模型调用但真正的难点在于步骤解析。模型生成的执行计划是自然语言你需要把它转成结构化的步骤对象。我踩过的坑是直接要求模型输出 JSON结果 10 次里有 2 次 JSON 格式错误。后来换成先输出自然语言计划再单独用一次模型调用把计划转成 JSON准确率稳定在 99% 以上。多一次调用换来的是稳定很划算。3.5 把 Agent 服务暴露出去并在真实业务里跑通最后写 api.py把整个流程封成一个 HTTP 接口。这里我只暴露一个简单的 POST 接口接收用户消息和上下文返回 Agent 的处理结果from fastapi import FastAPI from pydantic import BaseModel app FastAPI(titleAgent Skills Service) class AgentRequest(BaseModel): message: str user_id: str department: str general class AgentResponse(BaseModel): status: str data: dict None error: str None app.post(/agent/run, response_modelAgentResponse) async def run_agent(req: AgentRequest): try: context { user_id: req.user_id, department: req.department, } result run_agent_task(req.message, context) return AgentResponse(statussuccess, dataresult) except Exception as e: return AgentResponse(statuserror, errorstr(e))到这里一个最小可用的 agent-skills 框架就落地了。你可以把技能目录新增一个 skill重启服务开发环境甚至可以热加载然后在接口层测试整个链路。我在真实业务里接入了两个技能query_inventory 和 generate_alert_email。用户发一句看看哪些商品库存低于 20 件发封告警邮件给采购组Agent 会经历这样的完整链路召回技能、生成计划、执行查询、生成邮件内容、调用邮件技能发送、向用户确认。整个链路耗时 8 到 15 秒其中主要时间花在两次模型推理上技能本身执行不超过 200 毫秒。4. 技能开发中的典型坑与排查技巧4.1 技能触发率低先检查描述里的场景信号我见过很多开发者写完技能描述后发现模型死活不调用第一反应是模型不行或者 prompt 不够长。实际上问题往往出在描述本身。技能描述里的关键词会直接影响模型对该技能何时使用的判断。比如 query_inventory 的描述若只写查询库存用户在说帮我看看哪些商品快断货了时模型可能就联想不到这个技能。我的排查方法是让大模型自己生成 20 个可能的用户提问再用这些提问去验证技能触发准确率低于 90% 就返回去改描述。改描述时注意加场景化关键词比如库存不足、缺货、补货、断货、库存告警、安全库存这些词都能帮助模型建立关联。触发率低的原因排查方向解决方案描述太短缺少场景词统计模型未触发时的用户提问补充 when_to_use 与典型场景词多个技能描述语义重叠两两计算描述相似度明确边界词一个技能负责一个领域技能数量过多导致选择困难查看模型实际接收到的完整技能描述引入注册中心按语义召回候选技能4.2 技能参数总是传错用 schema 约束代替 prompt 说教模型生成参数出错是高发现象。一个典型的场景是用户说查一下商品 ABC 的库存模型可能会自作聪明地补一个 threshold0或者把商品 ID 写成商品名称。如果我靠 prompt 写请严格按照参数定义传参效果几乎为零。正确做法是在 schema 里尽可能把约束写死参数类型严格指定能用 enum 就用 enum参数格式写明正则、长度、取值范围比如商品 ID 统一 8 位字符必要的时候在执行器里做参数值映射把模型输出的商品名称映射成系统内部的商品 ID这个映射逻辑可以做成一个独立技能叫entity_resolution。另外我在编码过程中发现 importlib 动态加载的技能模块在多次 reload 时会保留旧的全局变量导致状态脏读。解决方式是在注册中心里维护一个模块名到文件路径的映射每次加载前先清理 sys.modules 里对应的旧模块。这些细节不处理线上会出现各种灵异事件。4.3 技能执行链路太长上下文塞爆了怎么办技能一多每次执行的数据都是动态的几次迭代下来上下文很容易膨胀。我有一次跑一个五步的编排任务到了第四步模型就开始忘记最初的目标生成的内容开始答非所问。排查后发现上下文里塞满了前三步返回的 JSON 数据。解决办法是上下文压缩也叫状态摘要。每执行完一个技能我会让模型用一句话总结这步完成后的关键信息然后把完整的返回结果移出上下文只保留摘要。比如 query_inventory 返回了 50 条商品记录摘要就是共查询到 50 条记录其中 15 条低于安全库存阈值最低库存为 A001 商品仅剩 3 件。后续步骤只需要这个摘要就足以继续决策。这一招让我的会话上下文消耗减少了约 70%模型在长链路任务中的稳定性也明显改善。如果你用的模型上下文窗口偏小这个方法几乎是必选项。4.4 技能失败后的自我修复能力怎么给技能执行不可能永远成功网络抖动、权限不足、业务数据异常都会导致失败。最初我的做法是失败就直接返回错误让用户重新描述。后来我发现给模型一个反思重试的机会能把很多临时性问题自动化解决。具体做法是在 executor 返回错误时把错误类型和错误信息喂给模型让它做三类决策若是参数错误提供修正后的参数重试若是技能内部业务规则错误换一个技能尝试若是权限或数据问题立刻转向向用户说明原因而不是无限重试。这里的难点是防死循环。我加了一个最大重试次数限制默认 2 次超过次数就终止并向用户道歉并要求补充信息。有一次我测试发送邮件技能模拟 SMTP 服务不可用模型第一次重试仍失败第二次就正确地转向了请稍后再试的应答这个表现已经足够好。5. 进阶扩展从单 Agent 到多技能协作体系5.1 技能之间的依赖关系与共享上下文当技能体系超过 30 个之后技能之间会产生隐式依赖。比如生成销售日报技能内部依赖查询订单数据技能的输出。如果每个技能都独立接收参数、返回结果那 Agent 在执行日报任务时就得先手动调查询再把结果作为参数传给生成日报编排逻辑会越写越复杂。我的解法是引入一个轻量的 context store技能之间通过共享上下文交换数据。技能执行完后可以把结果里的关键数据写入 context比如context.set(inventory_alert_list, data)。后面无论哪个技能要这份数据都通过context.get(inventory_alert_list)读取。这样 Agent 编排时的参数传递就大幅简化不再需要把上一轮的完整结果复制到下一轮。共享上下文也有风险。数据过期是最常见的比如用户先查了库存5 分钟后又查销售数据前者的库存结果已经不新鲜了。所以我给每个 context 变量加了时间戳和来源技能标识使用方可以判断数据是否过期。如果模型拿到的数据太旧它会主动重新调用源头技能刷新。5.2 技能评估不回归测试你永远不知道改坏了什么技能体系做大了以后最怕的就是改了一个技能别的技能触发率掉下去了。每个技能的定义、描述、schema 都像参数一样在影响模型的行为必须有一套回归评估机制。我做了一个简单的评估集收集了 200 条真实用户提问为每条标注了最佳技能调用序列和期望输出。每次对技能定义做任何改动就跑一遍评估集统计三个指标技能触发准确率正确的技能有没有被选中参数传递正确率选中技能后参数生成是否正确最终任务成功率Agent 是否在 N 步内完成用户请求。这套回归机制救过我一次。有一次我给 send_email 技能加了一个紧急邮件参数结果评估集显示 trigger accuracy 从 92% 掉到了 85%一查发现是一个技能描述里的关键词跟另一个技能冲突了。如果不做回归这个问题上线后用户会大面积反馈发邮件功能咋不灵了。5.3 接入更多模型和本地化部署时的注意点agent-skills 的方法论不绑定任何特定模型。我在 OpenAI 上验证过后也切换到了 Qwen、GLM、DeepSeek 等模型。不同模型对 Function Calling 的支持能力差别很大我总结了几条经验强模型GPT-4、Claude可以直接用原生 function calling技能描述可以写得简洁一些中等模型GPT-3.5、部分开源 7B 模型对函数调用的遵从度不够稳定需要把技能调度改成模型生成自然语言计划 解析器转结构化的方式不要依赖模型直接输出结构化 JSON本地部署模型时技能描述越短越好因为小模型的注意力机制对超长上下文的处理能力有限冗长的技能清单会直接拖低准确性。如果你有可复用且已调优的开源模型这套技能体系也支持内置技能 外部 llm 网关的混合架构。模型的差异在技能调度层被抽象隔离了主要影响的是调度准确率和延迟不影响技能本身的业务逻辑。写在最后我跑完整个项目的真实体会agent-skills 这套体系做到今天最大的收获不是代码量而是想明白了一件事Agent 的真正瓶颈往往不是模型智商而是工程能力。给模型一个定义清晰、边界明确、容错可靠的技能层比单纯换一个更大的模型更有效。我见过太多项目卡在demo 惊艳、上线翻车本质都是把复杂的真实世界逻辑一股脑塞给模型而没有做工程化拆解。如果你正在折腾 Agent 方向的实践我的建议是不要一上来就追新框架先把手上的一个真实业务场景拆成 3 到 5 个技能用本文这套思路实现一遍你会比看十篇论文收获更大。最后分享一个小技巧技能描述别急着一次写完美跑完一轮真实数据之后再迭代。你会发现用户的实际问法和你想的完全不一样这些真实样本才是优化技能定义的黄金素材。