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 技能列表与状态卡片：让技能一眼可见

第一个页面就是技能列表。我一开始用普通表格：技能名、类型、更新时间，密密麻麻。但用下来发现，你根本分不清哪些技能是核心能力、哪些是刚注册还没验证的“半成品”。

后来改成了卡片式布局，每张技能卡片展示以下信息：

状态徽标这个细节特别重要。之前我经常忘了某个技能到底能不能用，现在一眼就能看到：灰色是草稿，蓝色是测试通过待发布，绿色是启用，红色是禁用。团队里其他人也能看懂，不用来问“这个接口是不是已经上线了”。

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_key=True) name = Column(String(120), unique=True, nullable=False) display_name = Column(String(120), nullable=False) description = Column(Text, nullable=False) status = Column(String(20), default="draft") # draft/active/disabled/archived category = Column(String(50), index=True) version = Column(String(20), default="0.1.0") parameters_schema = Column(JSONB, nullable=False) side_effect = Column(String(10), default="readonly") # readonly/write endpoint = Column(String(500), nullable=True) # 外部HTTP接口地址 timeout_ms = Column(Integer, default=5000) rate_limit = Column(Integer, default=100) # 每分钟调用上限 owner = Column(String(50)) created_at = Column(DateTime, default=datetime.utcnow) updated_at = Column(DateTime, onupdate=datetime.utcnow)

有几个细节我要特别提醒：

• name必须全局唯一，且一旦被 Agent 引用，尽量不要改名。否则大模型可能从全局工具列表里找不到这个技能。
• parameters_schema直接存 JSONB，不要拆成字段表。技能参数五花八门，拆成关系表之后维护成本极高。
• status的取值建议固定枚举，不要随意新增。我在早期就是状态名不统一，有的地方写enabled，有的地方写active，写乱了之后处理逻辑到处都是坑。
• version字段一定要有，因为后续你要做灰度发布和回滚，没有版本号没办法区分是哪一次更新导致的问题。

4.3 对接 OpenAI Function Calling 与 MCP 兼容层

技能管理器本身不直接参与模型对话，它需要把技能信息“翻译”成 Agent 能理解的格式。目前最主流的对接方式有两类：OpenAI 风格 Function Calling 和 MCP（Model 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，并且开启了extra="forbid"，理论上多余字段会被拦截。结果发现前端提交的字段名是我在 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，我建议先从技能清单和测试沙箱入手，哪怕没有复杂的数据看板，只要能把“注册、测试、留痕”这三年做扎实，后面的路会好走很多。