做 AI Agent 容易管 AI Agent 的技能难。我手上有三四个 Agent 在跑一个做销售线索清洗、一个做舆情监控、一个帮运营写周报中间还挂了一堆 function calling、Prompt 模板和外部 API 封装。最崩溃的一次是线上报错说“技能不存在”我查了半天发现同名的技能有四个版本散落在三个项目的不同文件夹里。从那之后我下定决心给每个 Agent 建一份“技能登记本”——也就是现在这个可视化技能管理器。这个管理器解决的核心问题很简单把散落在代码、Prompt、插件目录里的 Agent 技能统一收拢到一个可视化面板里谁能看到、谁能调用、调用了几次、成功率多少、当前是什么版本一眼就能看明白。它适合所有做 AI Agent 开发的人尤其是手里已经有两个以上 Agent、开始被技能版本混乱和调用问题反复折磨的开发者。不管你是刚准备从 0 到 1 搭建 AI Agent还是已经跑在生产环境里天天救火这篇实战记录都会给你一条完整的落地路径。下面我按自己做这个项目的顺序把思路、选型、踩坑过程全部摊开讲。1. AI Agent 的技能为什么管不住先搞清楚技能的本质1.1 技能不只是“一个函数”很多做 Agent 的人会把技能想得过于简单以为技能就是一段 function calling 的定义给它配上描述和参数就行。实际跑起来之后你会发现一个技能背后可能有完全不同的实现方式有些技能是内部函数比如解析日期、清洗电话号码有些技能是外部 API 封装比如查天气、调企业微信发消息有些技能其实是 Prompt 模板调用时要喂一段人写的指令有些技能背后挂着数据库查询比如查订单、查库存还有些技能是知识库检索需要在向量库里做召回。这几种东西的调用方式完全不同。以前我习惯在 Agent 的 system prompt 里写“你有以下工具可用”结果技能一多prompt 变得无比臃肿模型开始瞎选工具选错工具之后还经常编造参数。后来我意识到技能的代码实现只是最底层的东西真正需要管理的是技能的“元信息”它叫什么、能干什么、参数长什么样、归谁管、能不能被外部调用、当前是哪个版本。1.2 散落管理的三个硬伤没有统一管理器的时候我的项目里技能分布在这几个地方Agent 代码里的 tools 列表、独立的 skills 目录、共享的外部接口文档、甚至还有运营同学写死的 Prompt。于是必然出现三个问题。第一个是可发现性差。新来的同事想给 Agent 加一个“查物流”的能力不知道项目里已经有人写过一个物流查询接口于是又写了一份接口还调不通。技能成倍增长但大部分是重复的。第二个是可观测性差。Agent 报错说“调用工具失败”你连它调的是哪个工具都看不到。没有统一的日志和指标Agent 跑得像一个黑盒出问题只能靠猜。第三个是可治理性差。谁有权限新增技能哪些技能可以给外部系统调用技能上线之后能不能一键拉停这些问题在没有管理器的时候完全无法回答。尤其是国内做企业级 Agent 的朋友合规审计一来这些都要命。1.3 什么时候该上管理器我个人的判断标准很简单当你的 Agent 数量超过 3 个或者技能数量超过 10 个或者团队里不止一个人维护 Agent就应该上。别一上来就搞个特别重的平台轻量管理器就够。我最初就是先写了一个两百行的 FastAPI 服务把所有技能注册信息收到一个接口里配合一个简单前端页面跑了两周才逐步迭代成现在这个可视化版本。过早追求“中台化”反而会死在第一步。2. 整体架构与我踩过的选型坑2.1 先把能力拆清楚可视化技能管理器到底管什么我在动手前画过一张脑图最后收敛成六个核心模块少一个都不行模块职责关键问题优先级技能注册新增、编辑技能元信息谁可以注册参数怎么描述P0技能检索按名称、标签、描述搜索语义搜索还是关键词P0技能状态机草稿、上线、下线、废弃怎么保证不停服P0技能调用网关Agent 通过统一入口调用技能怎么避免 Agent 直接调裸函数P1调用日志记录每次调用的输入输出、耗时、错误数据量多大要不要采样P1可视化面板展示技能列表、调用统计、状态分布ECharts 还是自研P1这里想特别强调“技能调用网关”这个模块。很多人的技能管理器只做 CRUDAgent 还是直接调用代码里的函数这样管理器就变成了一个纯粹的信息登记系统价值大打折扣。正确的做法是让 Agent 的 function calling 统一指向网关由网关转发到真实实现。这样版本切换、灰度、限流、审计都只有一个入口。2.2 存储选型别一上来就上重型数据库我一开始图方便把所有技能信息存在一个 JSON 文件里配合 Redis 做缓存。跑了一周就发现不行技能的描述和参数经常要改JSON 文件并发写会丢更新。后来切成了 MySQL 存技能主数据Redis 只放热点数据和统计缓存。为什么这么选因为技能元信息这个场景本质上是一个低频写、高频读、偶尔做关联查询的模型。技能总数可能就几十到几百条MySQL 完全够用。Redis 在这里的定位是解决 Agent 调用时的高频读取——LLM 每次规划都要拉技能列表和描述全走 MySQL 慢而且没必要。2.3 可视化方案大屏焦虑是伪需求“可视化”这三个字很容易让人想到大屏、炫酷的图表、实时滚动的数据。但你要是去问一个真正在维护 Agent 的开发者他最想要的是“打开页面之后快速知道现在有哪些技能、哪些技能有异常”。所以我把可视化分成了两个层次第一层是操作面板就是技能列表、详情、状态切换用表格加卡片足够第二层是统计视图展示调用趋势、成功率、Token 消耗、Top 10 技能这里用 ECharts 做几个图表就够了。我不建议一上来就做拖拽式编排画布或者实时大屏。那些东西看起来很先进但它解决的不是“管理”问题而是“编排”问题属于第二步的进阶需求。先做好第一个层次让团队每天打开页面知道技能概况比什么都重要。2.4 后端的形态REST 接口加一个执行代理整体架构我最终定成这样FastAPI 提供 REST 接口给前端面板和 Agent 调用MySQL 存主数据Redis 缓存活跃技能列表和统计结果调用网关以 Python 包的形式嵌入到 Agent 进程里。之所以不用微服务是因为技能管理器这个场景现阶段根本不需要拆服务拆了反而增加运维负担。Agent 侧接管理器的方式有两种一种是把管理器当成 API 服务Agent 的 function calling 里只注册一个“调用技能”函数参数是技能名和参数 JSON由管理器转发另一种是管理器侧定时把技能清单推给 Agent。我选了第一种理由只有一条调用链路上所有东西都能被我记录和审计不会出现 Agent 绕开管理器直接调底层的情况。3. 落地实战从技能 Schema 到可视化面板的完整实现3.1 技能 Schema 设计把参数说清楚是第一步技能注册的第一件事是定义参数。如果你希望 LLM 能正确调用参数描述必须机器可读我直接沿用了 JSON Schema 的格式每个技能在数据库里存一个parameters字段内容是 JSON Schema。举个例子{ name: fetch_order, description: 根据订单号查询订单基本信息包括金额、状态、收货人, parameters: { type: object, properties: { order_id: { type: string, description: 订单号形如 SO20250101 } }, required: [order_id] } }这里有个细节不要只写type和properties一定要写description而且要把边界条件写进去。比如这个订单号如果允许空字符串要明确写“空字符串时返回参数错误”。LLM 是根据描述来生成参数值的描述越具体它生成出来越符合预期。选型时对比了 JSON Schema 标准和 protobuf最后选 JSON Schema 是因为它和 LLM 的工具描述天然同构OpenAI 的 functions 参数、Anthropic 的 tool input schema 都支持这套写法换模型不用重写。3.2 状态机与版本管理技能不是改完就能上线的技能的生命周期我设计了五个状态draft草稿、active上线、deprecated弃用、disabled停用、archived归档。状态流转用一张表记录每次变更都要带操作人和原因。版本管理是这里的大坑。同一技能可以存在多个发布版本但某一个时间点只能有一个active版本。调用网关在转发请求时会读取技能当前 active 版本的实现地址而不是硬编码在 Agent 里。这样升级技能时只需要发一个新版本并把状态置为 active正在跑的任务依然用旧版本直到完成新任务才切到新版本。我这里在技能表上加了一个deployed_version字段概念上和 Kubernetes 的 Deployment 类似。3.3 注册与调用接口用钱花在刀刃上的最小实现先看注册接口的核心代码FastAPI 实现from fastapi import FastAPI, HTTPException, Depends from pydantic import BaseModel, Field class SkillCreate(BaseModel): name: str Field(..., pattern^[a-z][a-z0-9_]*$) description: str Field(..., min_length10) parameters: dict version: str app.post(/api/skills) async def create_skill(req: SkillCreate, user: str Depends(get_current_user)): # 校验技能名唯一 if await skill_repo.get_by_name(req.name): raise HTTPException(status_code409, detail技能名已存在) skill Skill( namereq.name, descriptionreq.description, parametersreq.parameters, versionreq.version, statusdraft, owneruser, ) await skill_repo.insert(skill) await cache.invalidate_skill_list() return {id: skill.id, status: draft}调用网关的封装我放在一个agent_skill_executor包里Agent 里只需要注册一个工具async def invoke_skill(skill_name: str, arguments: dict) - str: 调用统一技能管理器中的技能参数必须符合该技能的 JSON Schema。 resp await http_client.post( http://skill-manager/api/skills/invoke, json{skill: skill_name, arguments: arguments}, ) if resp.status_code 200: return resp.json()[result] return resp.json().get(error, 调用失败)重点在于invoke_skill背后的服务端做了什么。服务端拿到请求后先查技能缓存Redis判断技能是否存在且为 active再拿 active 版本的参数 schema 做校验校验通过后才转发到真实实现。校验失败的情况下返回给 LLM 的错误信息要非常明确比如“参数 order_id 缺失”而不是“调用失败”。3.4 日志采集与统计可视化面板的数据从哪里来没有数据可视化就是空壳。每次技能调用在网关里同步记录一条日志到 MySQL 不太现实高并发下容易拖垮数据库。我的做法是先写到本地内存队列异步批量写 MySQL同时在 Redis 里累加调用计数和耗时统计口径按分钟粒度的 key 来做。ECharts 只需要从后端聚合接口拿数据不用直接查原始表。统计接口的返回结构类似{ trends: [ {date: 2025-04-01, calls: 1200, success_rate: 0.98}, {date: 2025-04-02, calls: 1500, success_rate: 0.97} ], top_skills: [ {name: fetch_order, calls: 4200, success_rate: 0.99} ] }前端就一个 Vue 页面加 ECharts趋势图画折线图Top 技能画横向柱状图状态分布画饼图。这里我想多说一句图表样式不是重点重要的是每个指标的口径要写清楚。比如成功率的分母是“所有进入网关的调用”还是“真实执行成功的调用”这就是个很容易吵架的口径问题我们后面踩坑部分会详细说。4. 踩坑实录技能管理器落地的四个翻车现场4.1 LLM 生成的参数永远不会老实按文档来这是技能管理器上线后我遇到的第一个严重问题。技能定义了required字段LLM 还是经常缺参数我明明在描述里写了“日期格式为 YYYY-MM-DD”它照样能生成“2025年4月1日”这种格式。那时候 Agent 调用技能的成功率只有七成排错排得头大。排查过程是这样的我先在网关里加了参数校验日志把每次校验失败的输入原样打出来发现 LLM 经常把多个参数塞进一个字段或者用中文逗号或者给字符串类型的参数传了一个数组。也就是说不是 LLM 笨而是模型的工具调用生成能力有限并且在中文语境下它特别容易沿用自然语言里的格式。修复方案我分了两步。第一步校验失败时返回给 Agent 的错误消息必须包含“你上次的参数是 X缺少 Y正确格式示例是 Z”让 LLM 有机会自行修正。实测下来允许 Agent 修正一次后成功率能提到九成以上。第二步在网关里加了一层参数解析的兜底逻辑比如对日期格式做归一化、对字符串参数做 trim。但这层兜底一定要慎重只做安全的转换不要尝试去猜用户的意图。现在很多团队用更严格的手段直接让 LLM 生成JSON Schema时校验一旦不通过就立即重试这个思路也是对的。4.2 技能版本热更新把正在跑的任务搞出了幽灵报错技能管理器做出来之后我很快学会了“热更新”——在人少的时候把新版本技能发布上线不用重启 Agent。结果第二天业务方反馈有一批晚上跑的订单处理任务全部失败日志里清一色的“AttributeError: SkillV2 object has no attribute parse_v1”。这个问题的根因是Agent 里已经拿旧版本技能注册表完成了任务规划中间技能被热更新成 V2而 V2 代码移除了 V1 的旧方法执行到一半就崩了。表面上看是技能管理器的问题实质上是版本一致性问题调用网关执行的时候没有锁定任务开始时的技能版本。修复方案是给每个调用会话加一个skill_snapshot也就是在 Agent 开始规划任务时把当时所有 active 技能的版本号快照存到上下文中。网关执行时优先按快照里的版本找实现如果快照版本已经废弃才走新版本。这样热更新不会影响正在跑的任务只会影响新任务。后来我又补了一个增强更新 active 版本前可以设置一个“冷却期”在冷却期内旧版本仍然服务已有调用冷却期之后才完全切到新版。4.3 可视化面板的数据对不上账指标口径不统一面板上线后第一次给团队演示运营同事当场指出一个问题你们面板显示技能成功率 98%但业务后台显示失败率有 4%到底哪个是对的我查了很久才发现是两个口径打架。业务后台算失败率分母是所有发起的调用包括 Agent 在规划阶段试错时发了两次无效调用一次因为参数缺失一次因为超时我的面板算成功率分母是“进入真实执行阶段的调用”把那些在校验阶段就被拦下的无效请求都排除了。所以在我的统计里成功率更高但实际上很多无效调用已经消耗了 LLM 的 token 和时间。这个坑非常隐蔽却非常影响可信度。解决方案是在面板上把几个公式写清楚并且在图表旁边直接标注口径说明。我最终定义了三组指标发起调用数含校验失败、执行成功数、业务成功数执行成功且返回结果被 Agent 使用成功三个数据分开展示然后在此基础上算两个不同维度的成功率。写清楚了之后运营和技术之间不再斗嘴因为大家看的是同一套口径。另外同步把原始日志做了 15 分钟延迟的校对任务每晚跑一次全量核对防止异步写批丢数据。4.4 Redis 缓存与 MySQL 状态不同步灰色五分钟技能管理器里 Redis 缓存了“活跃技能列表”Agent 每次规划前先读缓存减少 MySQL 压力。我最初直接在更新技能状态时删除缓存依赖下一次读时重建。理论上没问题但实际操作中我发现一个问题删除缓存后如果某个 Agent 实例因为网络故障或者 GC 停顿没有立即回源数据库就会继续读到旧缓存个别实例甚至长时间用旧列表。当时线上有一个技能已经停用了但部分 Agent 还在调它搞得我每次清理故障都要对比好几个时间点。这个问题的修复说穿了很简单给缓存加版本号。每次技能表有变更就把版本号加一读缓存时同时读版本号发现版本号低于 MySQL 侧的最新版本号就强制回源并更新缓存。如果你不想自己做版本号也可以用 Redis 的订阅发布在技能状态变更时广播刷新事件。我做的是前者因为实现代码最少。这件事也让我养成了一个习惯任何涉及缓存和数据库一致性的功能都要先画清楚“读路径”和“写路径”否则线上迟早给你上一课。5. 进阶思考从技能管理器走向 Agent 中台5.1 技能编排让 Agent 学会组合而不是单打独斗技能管理器做到第四周我开始觉得单纯的“登记 调用”不够用了。很多业务任务不是一个技能能完成的比如“生成营销周报”需要先查订单数据再算环比再调大模型总结最后通过企业微信发出去。如果每个技能都是独立原子技能Agent 需要靠大模型自己编排。模型如果编排乱了你很难在管理器里看明白到底哪里出的问题。所以第二阶段我加了两样东西技能标签体系和简单的编排模板。标签体系让 Agent 在语义上更容易找到技能编排模板把高频链路提前定义好比如“数据查询 → 计算 → 生成报告 → 对外发送”Agent 只需要填充每个环节的参数。管理器里用一张 DAG 图来表示这个模板虽然没做到拖拽式编辑那么炫酷但已经足够让团队一眼看懂任务是怎么被技能组合完成的。5.2 权限与审计一个不能省的模块企业里给 Agent 用技能管理器最敏感的不是技术而是权限。谁能上线技能谁能操作停用哪个部门用了哪些数据这些问题直接决定你的管理器能不能从个人项目变成团队基础设施。我的做法是在管理器里引入了角色管理员、开发者、调用者、审计员。管理员能操作所有状态开发者能注册编辑技能但不能上线调用者只能通过网关调技能审计员只能看日志。所有操作都记录下来谁、什么时间、对哪个技能做了什么变更、变更前后的值各自是什么。审计日志本身不设删除接口而且定期归档。如果你打算让 Agent 对外部系统操作比如发邮件、改订单审计日志尤其重要关键时刻它能救你一命。5.3 技能市场与团队协作管理器最终形态的开始当团队超过五个人一起维护几十个技能时“市场”的需求自然就出来了。我的技能管理器里加了一个简单的“技能服务市场”页面每个技能都有自己的详情页包含描述、参数示例、调用统计、最近变更记录、评分和负责人。有人想用某个技能先在详情页里点“申请使用”管理员通过后调用者才能在网关侧对该技能发起调用。这个流程比给每个人开一个超级权限安全得多。前阵子有同事问我是不是有一个“AI Agent 中台”的概念我当时心里想其实你从技能管理器一路做过来自然而然就会演化成一个轻量中台。统一目录、统一调用、统一日志、统一权限这些不就是中台的一半吗从这个角度看所谓“从 0 到 1 搭建 AI Agent”最关键的一步往往不是模型选型而是把技能这个底座做扎实。5.4 我下一步准备做的语义技能搜索和异常自愈目前这个管理器已经稳定跑了半年服务了团队里 8 个 Agent、约 40 个技能。下一步我打算做两件事一是把技能检索升级成语义搜索用 embedding 把技能描述向量化让 Agent 和人在找技能时不再依赖关键词而是依赖意图二是做异常检测当某个技能成功率陡然下跌或者延迟明显上升时自动在面板上标红并通知负责人。本质上技能管理器已经从一个“工具”变成了一个“系统”它能自己告诉你哪里不对劲而不是等你来查。最后分享一个我反复和团队强调的小技巧技能的 description 字段不要自己硬写直接把技能实现代码的 docstring 扔给大模型让它按固定模板生成描述和参数说明然后你再人工审核一遍。这样不仅能提升技能元数据的质量速度还快很多。我那次让 AI 帮我把 40 个技能全部重新生成了一遍描述整个面板的可读性直接上了一个台阶之后 Agent 调用技能的成功率也跟着涨了。技能管理这件事本质上是“让元数据更可用”而元数据质量越高Agent 的表现就越稳定。