AI Agent 这东西最容易被低估的坑往往不是模型不够聪明而是“技能”管理一片混乱。这里的技能指的就是 Agent 可以调用的一切外部能力查天气、查订单、发邮件、调数据库、操作工单系统……模型本身再强没有一套靠谱的技能管理机制到了真实业务里照样抓瞎。我之前同时维护几个 Agent 应用客服、运营分析、工单处理各一个技能加起来不到二十个但已经乱得让人头大同一个“查订单”能力在 A 项目里是 GET /order在 B 项目里是 POST /query_order参数名还不一样。后来索性停下来搭了一个可视化技能管理器把所有技能统一注册、统一调试、统一观测。这篇就聊聊我是怎么拆解这个问题的以及你如果要复刻应该重点关注哪些地方。1. 为什么需要给 AI Agent 配一个“技能管理器”先别急着讨论技术选型先把痛点聊透。大部分人刚开始做 AI Agent 的时候技能就那么三五个直接写死在代码里完全没问题。但业务一复杂、Agent 一变多技能管理就变成了隐形的地雷。1.1 技能散落在代码里的失控日常我见过太多团队是这样的状态Agent 的 system prompt 里写“你可以调用查询订单接口”然后代码里随便放一个get_order_info的函数参数是order_id。过几天另一个业务方说也要查订单但他用的是另一个系统参数叫orderNo。两边接口不一样但都叫“查订单”。精力旺盛的时候还能靠文档维护可 Agent 技能的迭代速度远比你写文档快。新增一个参数、调整一个超时时间、切换一个上游系统这些变更散落在 N 个代码仓库里。最痛苦的是没有人能说清楚“当前线上所有 Agent 到底能调用哪些技能、每个技能是什么版本、调用成功率高不高”。我把这个阶段叫作“技能失管”技能存在但不可见、不可控、不可追溯。这时候就不是模型能力问题了是工程管理问题。1.2 只做“技能中心”还不够可视化才是关键很多人一听“统一管理”第一反应是搞个中央 API 网关或者技能注册表把所有技能接口配到一个配置中心里。这当然有用但对我来说还差一步没有可视化界面这个系统最终还是只有开发人员会用而且用起来很反人性。可视化不是给技能列表套个好看的 UI 那么简单。它的核心价值是“反馈回路”技能有多少、状态如何打开网页一眼就知道某个技能参数怎么填、填错了会怎样在线就能试Agent 调用某个技能之后发生了什么点开调用记录就能看到完整的入参、出参、耗时、报错。有了这层反馈技能的维护门槛就从“会改代码的工程师”降到了“看得懂业务的运营和产品”。我后来确实让客服主管自己开了一个新技能的分类标签整个过程我没写一行业务代码只是把技能注册、配置、测试这些动作做成了可视化操作。1.3 项目的定位我刻意不做大而全在动手之前我也犹豫过要不要把 Agent 编排、Prompt 管理、模型配置全塞进去。后来想明白了越界必乱。这个管理器的定位非常明确它只解决“Agent 的能力层”问题也就是技能的全生命周期管理注册、配置、测试、发布、观测、下架。Agent 的对话逻辑、记忆机制、Prompt 工程不归它管模型本身的调用也不归它管。守住这条边界才让整个系统保持轻量也更容易落地。2. 整体设计思路我把技能管理拆成了哪几层这个项目虽然叫“管理器”但内部我把它设计成了三层技能元数据层、运行时网关层、可视化交互层。每次别人问起这套东西怎么搭我都会先讲这三层。2.1 技能注册与描述标准化技能能不能被 Agent 正确调用关键不在实现而在描述。现在的 Agent 基本都是靠大模型根据“名称 描述 参数结构”来决定是否调用某个技能的所以这三样东西必须标准化。我从 OpenAI Function Calling 的规范里借鉴了一套结构每个技能至少包含name、description、parameters三部分。parameters用 JSON Schema 定义里面的每个字段都要写清楚类型、是否必填、含义、枚举值最好再补上示例值。这套标准化一旦建立后面所有环节都受益前端可以根据 JSON Schema 自动生成表单后端可以用同一份 Schema 做参数校验Agent 端可以直接把技能注册信息塞进模型接口的 tools 参数里。2.2 运行时网关与统一调用技能注册好了只是第一步真正跑起来的时候还要解决“谁来执行”的问题。我给管理器设计了一个轻量网关所有 Agent 技能调用都走统一入口POST /api/skills/{skill_name}/invoke。网关层统一处理四件事鉴权、限流、超时、重试。每次调用请求都会带上调用方标识比如哪个 Agent、哪个会话后端拿到之后先查这个技能的状态禁用中的技能直接返回“技能不可用”然后再校验参数、落日志、执行技能本体、记录结果。这么做的好处是技能执行器本身可以分布在不同的服务里但对外暴露的方式完全一致。团队里谁要加个技能只需要在管理器里注册一个 HTTP 接口或者一段可执行代码不用再操心自己的服务怎么和其他 Agent 对齐。2.3 可视化层要回答的三个问题可视化部分不是一上来就画一堆图表而是围绕三个问题设计有什么技能——对应技能列表页展示技能名称、描述、状态、分类、最近调用量。怎么用技能——对应技能详情页展示参数结构、示例输入、调用说明并且提供在线测试。用得怎么样——对应调用记录页展示每次调用的入参出参、耗时、错误信息、趋势统计。把这三个问题拆完前端页面结构基本就清晰了。我们不用刻意堆可视化大屏真正好用的是让每个技能卡片都能点出“最近 7 天成功率和平均耗时”这比炫酷的图表实在得多。3. 核心模块实现从细节里抠出来的体验说来惭愧这套管理器刚做出来第一个版本时功能都有但用起来就是别扭。后来我花了两周时间重点打磨几个核心模块才算真正能日常使用。3.1 技能列表与状态卡片让技能一眼可见第一个页面就是技能列表。我一开始用普通表格技能名、类型、更新时间密密麻麻。但用下来发现你根本分不清哪些技能是核心能力、哪些是刚注册还没验证的“半成品”。后来改成了卡片式布局每张技能卡片展示以下信息展示项说明技能名称计算机可读的唯一标识如order_query展示名称给人看的中文名称如“订单查询”状态徽标启用中 / 已禁用 / 草稿 / 待审核分类标签比如“电商”“数据分析”“消息通知”最近 7 天成功率简单进度条展示平均响应耗时小于 1s 显示绿色大于 3s 显示黄色负责人方便出问题找对人状态徽标这个细节特别重要。之前我经常忘了某个技能到底能不能用现在一眼就能看到灰色是草稿蓝色是测试通过待发布绿色是启用红色是禁用。团队里其他人也能看懂不用来问“这个接口是不是已经上线了”。3.2 动态表单配置用 JSON Schema 免去手写表单技能多了以后如果每个技能都要单独开发一套配置表单那这项目永远做不完。我的解法是让前端根据技能定义里的 JSON Schema 自动生成表单。比如某个“发送邮件”技能的参数定义大致如下{ type: object, properties: { to: { type: string, format: email, title: 收件人, description: 必填收件人邮箱地址 }, subject: { type: string, title: 邮件标题, maxLength: 200 }, content: { type: string, title: 邮件正文, ui:widget: textarea } }, required: [to, subject, content] }前端拿到这份 Schema 之后用类似vue-jsonschema-form这样的组件库就能渲染出完整表单。新增技能时后端同学只需要维护一份 Schema前端零改动。这里有个小坑Schema 里如果带了ui:widget这种前端专属字段后端校验时要忽略掉不能把它当成业务字段不然会校验失败。3.3 在线测试沙箱先验证再上线的关键环节在线测试是这个管理器最让我省心的模块。过去调试一个技能要么写单元测试要么让 Agent 真的跑一轮看效果链路长、反馈慢。现在直接在共建好的参数面板里填值点“运行”就能看到真实返回。不过这里有一个非常关键的经验测试沙箱必须支持“假动作”。有些技能是有副作用的比如“发送邮件”“创建工单”“转账”如果在线测试真的发出去一封邮件或真的创建了一个工单那测试一次就污染一次数据。我给技能定义里增加了side_effect字段值为readonly或write。readonly的技能可以直接真跑write技能在测试模式下默认走 mock 执行器只有在勾选“真实执行”并二次确认后才会落到真实系统。这个设计帮我避免了不少事故。有一次运营同事测试“批量发送营销短信”我这个开关直接挡住了否则几千条测试短信就出去了。3.4 调用链观测让每次调用都留痕技能管理器里还得有“日志”模块但我做得比普通日志更结构化。每次技能调用都会记录一个完整的调用记录对象核心字段如下调用方哪个 Agent、哪个会话、哪位用户技能版本当时执行的是技能的哪个版本入参快照实际传入的参数值出参快照返回给 Agent 的结果执行耗时端到端耗时含网络与重试时间错误信息如果失败告警码和原始错误堆栈追查 ID给 Agent 侧的调用入口方便跨系统串联链路。这个模块刚开始我觉得“反正有日志不就行了”后来发现没有结构化的调用记录排查问题非常痛苦。有了这张视图之后任何技能出问题我只需要找到对应时间段的调用记录点开就能看到参数和报错基本能定位是模型传参错、上游系统慢还是技能执行器本身 bug。4. 从 0 到 1 搭建实操技术选型、数据模型与运行时对接很多朋友问我要现成的代码我只能说架构思路比代码更重要。因为每个人手上的 Agent 框架不一样所以这里我把从 0 到 1 搭建这个可视化管理器时最重要的几个决策点讲清楚你照着调整就行。4.1 技术选型FastAPI Vue3 PostgreSQL 的理由后端我选了 FastAPI前端用了 Vue3数据库用的 PostgreSQL。这个组合不是无脑跟风而是有明确理由的。FastAPI 的 Pydantic 模型天然适合处理技能参数校验。它可以直接把 JSON Schema 转成 Pydantic 模型参数非法马上抛异常和我前面说的 Schema 标准化无缝衔接。而且它自带 OpenAPI 文档技能接口调试非常方便。Vue3 的前端我用的是 Element Plus 组件库配合 JSON Schema 表单渲染开发效率高。PostgreSQL 则是因为技能元数据里经常有 JSONB 类型的字段比如技能入参示例、调用上下文等直接用 JSONB 字段存比拆成多张表更灵活。如果只是个人练手完全可以把 PostgreSQL 换成 SQLite后端不变前端不变只改数据库连接串。但要注意SQLite 对 JSON 字段的索引能力弱一些技能多了以后查询效率不如 PostgreSQL。4.2 技能注册表的数据模型怎么建技能注册表是整个系统的核心表我简化后的 SQLAlchemy 模型大致是这样class Skill(Base): __tablename__ skills id Column(Integer, primary_keyTrue) name Column(String(120), uniqueTrue, nullableFalse) display_name Column(String(120), nullableFalse) description Column(Text, nullableFalse) status Column(String(20), defaultdraft) # draft/active/disabled/archived category Column(String(50), indexTrue) version Column(String(20), default0.1.0) parameters_schema Column(JSONB, nullableFalse) side_effect Column(String(10), defaultreadonly) # readonly/write endpoint Column(String(500), nullableTrue) # 外部HTTP接口地址 timeout_ms Column(Integer, default5000) rate_limit Column(Integer, default100) # 每分钟调用上限 owner Column(String(50)) created_at Column(DateTime, defaultdatetime.utcnow) updated_at Column(DateTime, onupdatedatetime.utcnow)有几个细节我要特别提醒name必须全局唯一且一旦被 Agent 引用尽量不要改名。否则大模型可能从全局工具列表里找不到这个技能。parameters_schema直接存 JSONB不要拆成字段表。技能参数五花八门拆成关系表之后维护成本极高。status的取值建议固定枚举不要随意新增。我在早期就是状态名不统一有的地方写enabled有的地方写active写乱了之后处理逻辑到处都是坑。version字段一定要有因为后续你要做灰度发布和回滚没有版本号没办法区分是哪一次更新导致的问题。4.3 对接 OpenAI Function Calling 与 MCP 兼容层技能管理器本身不直接参与模型对话它需要把技能信息“翻译”成 Agent 能理解的格式。目前最主流的对接方式有两类OpenAI 风格 Function Calling 和 MCPModel Context Protocol。如果是 OpenAI 风格管理器只需要为每个启用的技能生成一个 tool 对象{ type: function, function: { name: order_query, description: 根据订单号查询订单状态、金额、物流信息, parameters: { type: object, properties: { order_id: { type: string, description: 订单号通常以ORD开头 } }, required: [order_id] } } }Agent 端收到模型返回的tool_calls之后把请求转到管理器的统一调用网关即可。MCP 的话管理器可以作为一个 MCP server 暴露技能列表或者反向对接其他 MCP server。我的实现是先做了一版兼容层管理器内部定义“技能实现”有两种类型一种是http类型指向外部 REST 接口另一种是mcp类型内部保存 MCP 工具的 URI。这样管理员在可视化界面里注册的每一个技能底层不管是普通 HTTP 还是 MCP都能被 Agent 统一使用。4.4 前端可视化布局要点前端页面不需要特别复杂但布局要顺着人的操作习惯走。我最终定的结构是左侧是技能列表可搜索、可筛选分类点击某个技能后右侧分为三个页签概览技能描述、状态、字段说明、最近调用趋势配置动态表单展示参数支持填测试值、执行测试调用记录该技能最近 20 次调用详情列表点击任意一条展开入参、出参和时间线。这里最需要注意的是测试功能和配置功能不要离得太远。最初我把测试放在独立页面用户配置完参数还要跳一下页面非常打断思路。后来把它合并成一个左右分栏左边是参数表单右边是结果输出测试效率提升明显。5. 开发中踩过的坑与排查实录这套系统开发过程中我踩了不少坑有些是设计层面的有些是细节问题。挑四个最典型的、也是别人大概率会碰到的记录一下。5.1 JSON Schema 默认值陷阱我第一次给技能配置动态表单时在 JSON Schema 里写了一个default字段比如“发送邮件”的正文默认是“您好”。前端表单确实显示了默认值用户没改动直接提交后端收到的参数里带着这个默认值。当时我后端校验用的是 Pydantic并且开启了extraforbid理论上多余字段会被拦截。结果发现前端提交的字段名是我在 Schema 里写的属性名但 Pydantic 模型里我定义成了别的名导致校验失败。后来我把规则统一成前后端共享同一份parameters_schema字段名严格保持一致。所有默认值只存在于 UI 展示后端在执行时如果没传对应字段就使用 Schema 里的default做兜底而不是信任前端一定提交了默认值。5.2 长耗时技能把 HTTP 请求拖死我的技能列表里有一个“竞品价格分析”技能它要调外部爬虫和多个平台接口完整跑一次可能要 30 秒以上。第一次上线时我直接用同步 HTTP 请求实现前端在线测试秒表转了几十秒浏览器直接报请求超时后端日志里一大堆 pending 连接。后来我把技能执行改成了异步任务模式调用网关收到请求后立即返回一个task_id前端拿到后轮询任务状态。真正耗时的技能执行器后台跑跑完再更新结果。这样在线测试和 Agent 调用都不会被长任务卡死。Agent 侧对接时也要注意OpenAI Function Calling 是有超时预期的如果技能可能要跑几十秒最好做成“提交工具调用任务 后续查询结果”两段式而不是让模型一直等到结果出来。5.3 多个 Agent 实例共享技能状态的并发问题有些技能看起来很简单比如“统计今日新增用户数”它需要调用应用内计数器。如果只有单个进程跑没问题但一旦你部署了多个 Agent 实例每个实例都可能并发触发同一个技能计数器就会出现明显的覆写错乱。这个问题让我意识到技能执行器必须尽量保持无状态。所有跨请求的状态都应该持久化到数据库或者 Redis而不是保存在执行器进程里。对于需要保证唯一性的操作我会加一个由调用方生成的request_id做幂等键同一个request_id只允许执行一次这样重复提交、重试、并发打过来也不会重复扣减或者重复发消息。5.4 可视化面板数据延迟与“假实时”刚开始我想做“实时调用面板”于是给前端上了 WebSocket每来一条调用记录就往页面推一条。效果很炫但实际开发中发现高频技能多的时候WebSocket 推送会把前端渲染卡住而且很多调用你还没看就滚过去了。后来我调整了策略列表页用 5 秒一次的轮询只刷新最近 20 条点进调用详情才拉取完整数据。技能成功率、平均耗时这些统计直接在后端做 1 分钟聚合缓存前端展示每分钟更新的数据。这样既保证基本实时性又避免把简单页面搞成数据分析系统那么重。6. 这个管理器实际用下来我的几条经验最后聊几个非技术层面的心得这是我用了大半年之后最想说的。6.1 技能治理要先做分级不是所有技能都应该被所有 Agent 调用。我把技能分成了三个级别只读查询类、业务操作类、高危变更类。只读查询类技能查天气、查库存、查订单可以直接开放给所有 Agent业务操作类技能创建工单、发送站内信需要指定 Agent 白名单高危变更类技能删除数据、批量修改、转账默认禁用需要人工审核并且每次调用都留痕。分级不仅是为了安全也是为了让 Agent 的决策更干净。如果大模型面对几十个技能其中混杂着一堆高风险动作它的“调用准确率”会明显下降。技能变少、边界清楚模型反而不容易误选。6.2 测试沙箱要能“假动作”前面已经提过一遍但我还是要单独拎出来说给技能做在线测试时一定要区分“假动作”和“真动作”。我见过不少团队测试技能时直接调了真实上游接口结果测试数据污染了报表最后又要花一两天清理。我的做法是给每个技能定义测试模式如果技能是readonly可以直接真执行如果是write但本身有测试环境地址就优先切到测试环境如果既没有测试环境又是高危操作就直接返回 mock 结果并在结果里明确标注“这是模拟数据”。这个规则看着简单但能挡住绝大多数因为手误造成的线上事故。6.3 后续扩展从管理器走向技能运营平台这套系统现在已经稳定运行但我还在持续往里加东西。我最想做的两个扩展方向一个是“技能健康度评分”把成功率、耗时、调用次数、最近变更频率综合成一个分用来判断哪些技能需要重构另一个是“技能调用成本看板”让每个 Agent 消耗了多少 token、调用了多少次技能、每次调用多少钱变得透明。坦白说技能管理这个东西不性感甚至有些枯燥。但如果你真的认真做了你会发现它带来的回报是持续的不用再为了一个技能参数变更到处改代码不用再深夜排查到底是哪个 Agent 调错了接口也不用怕业务同事说“帮我加个技能”然后你只能回一句“等我排期”。我个人在实际折腾中的体会是AI Agent 的能力上限其实不取决于模型参数而取决于技能层有没有被好好管理。可视化不是锦上添花而是在技能越来越多时唯一能让人保持理性和清醒的手段。如果你也在做 Agent我建议先从技能清单和测试沙箱入手哪怕没有复杂的数据看板只要能把“注册、测试、留痕”这三年做扎实后面的路会好走很多。