1. 为什么要在扣子平台上自己创建插件1.1 商店里现成插件和自定义插件的边界扣子Coze智能体平台的插件商店里其实已经有大量现成能力搜索一下就能找到新闻资讯、天气查询、图片生成、数据表格处理之类的插件。很多人第一反应是既然商店有这么多为什么还要自己创建我自己测试下来最大的体会是——商店里的通用插件解决的是大多数场景下的通用需求一旦你手里有内部系统、私有接口、特定格式的数据源通用插件就完全指望不上了。举个例子。你做了一个面向电商客服的智能体需要查询内部订单系统的物流状态。这个接口是你们公司自己的外部插件不可能提前对接。这时候你就得自己写一个插件把订单查询接口封装成扣子平台能理解的形态让智能体在大模型理解用户问题之后能够准确调用这个查询能力。还有一类常见场景是数据格式转换你的接口返回的是加密或压缩后的数据商店插件根本不认识这种格式也需要通过在插件里做解码逻辑后再开放给大模型使用。所以自己创建插件解决的是三件事第一接入私有数据源和能力第二对现有第三方 API 做定制化封装比如只想暴露特定字段、加入鉴权逻辑第三把原本需要多步骤调用的业务流程封装成一个插件动作让智能体一句话就能触发。这篇内容就是围绕如何完成这三件事来展开的整个过程基于我在扣子平台上实际创建插件的经验不光是点按钮还会把容易出错的地方全部交代清楚。1.2 插件到底在智能体里扮演什么角色要理解插件创建先得理解插件的定位。扣子平台上智能体的核心是大模型 工具大模型负责理解意图、拆解任务、组织语言但它没有能力去实时查询外部信息、操作第三方系统。插件就是连接两者之间的那层翻译官它把外部 API 的能力描述成大模型能理解的操作列表把用户请求转换成 HTTP 调用参数再把 API 返回结果转回给大模型生成最终回答。这个过程看起来复杂但有一个很关键的简化思路插件不需要把所有功能暴露给大模型只需要暴露必要的能力。很多人在设计插件时犯的最大错误就是试图把接口字段全量搬进去结果大模型面对一大堆可选参数反而不知道该怎么选。好的插件设计一定是对大模型友好、对开发者省心的——参数数量适中、每个参数的描述清晰、返回结果结构稳定。这点后面我会专门展开讲。1.3 这篇文章适合谁看如果你正准备在扣子平台上创建一个自己的插件或者已经建过但使用效果不理想比如智能体经常调用失败、参数传错、结果解析不了这篇文章应该能帮到你。内容覆盖从插件形态选型、OpenAPI 规范准备、创建配置、调试发布到代码插件的进阶玩法整体偏实操有条件的话建议打开平台跟着做一遍效果会好很多。2. 动手前先做两件事能力盘点与插件形态选型2.1 先盘清楚你的目标能力是通过什么方式提供的在扣子上新建插件之前第一件要做的不是打开控制台而是先回答一个问题你要封装的能力本质上是HTTP API 调用还是一段代码逻辑这两种情况对应了扣子平台上两条不同的插件路径选错后面会非常别扭。如果你要对接的是某个现成的 HTTP 接口——不管是你自己公司的服务、第三方开放平台还是云函数最合适的方式是创建API 插件也就是用 OpenAPISwagger规范来描述这个接口然后让平台直接生成插件。平台会解析 OpenAPI 里的请求地址、请求方法、参数定义、响应结构自动生成插件的工具描述。这种方式的优点是大模型对每个参数做什么非常清楚因为 OpenAPI 里本来就有每个字段的说明。如果你的能力不是现成 HTTP 接口而是一段需要针对格式做转换、或需要聚合多个接口结果之后再返回的逻辑那就更适合在插件里嵌入代码。扣子平台允许在插件步骤中编写 Python 或 JavaScript 代码代码可以接收输入参数、做处理后返回结果。这个后面章节会详细讲。另外一个很实用的点即使是 HTTP API 插件也可以在请求之后加一个代码步骤对返回做后处理等于把调接口和加工数据组合成一条链路。2.2 三种插件形态怎么选API插件、代码插件、工作流插件这里有个容易混淆的地方需要先梳理清楚——扣子平台上插件这个概念的边界其实比较宽常见的形态有三种形态适用场景优点局限API 插件直接封装外部 HTTP 接口配置简单、大模型可理解性强依赖接口稳定性不能做复杂逻辑代码插件需要数据加工、格式转换、二次封装灵活度最高能处理任意逻辑代码量需要自己维护调试要反复测试工作流插件多个工具按固定流程编排后再封装流程可视化、可复用创建和调试步骤多适合复杂业务实际项目中大多数人会优先用 API 插件因为它的心智成本最低、见效最快。但我的建议是如果接口返回的数据结构特别复杂或者下游业务方只期望拿到几个固定字段不要直接在 API 插件里把原始返回一股脑暴露给大模型而是加上一个代码步骤做精简。这个接口 加工的组合是插件开发里最常用的模式。2.3 鉴权方式选型无鉴权、API Key、OAuth创建插件时必然会碰到鉴权配置我见过不少人在这一步卡住。扣子平台支持的主要鉴权方式有三种无鉴权接口本身完全开放。适合公开数据源但基本只在测试阶段用生产不建议。API Key / Bearer Token在 HTTP 请求中携带一个固定密钥通常是放在 Header 里。这是大多数内部接口的选择密钥由你自己在扣子后台配置好用户调用插件时不用关心。OAuth 2.0需要引导用户完成授权换取 Token通常用于对接第三方开放平台比如钉钉、飞书、Google 服务。这种鉴权配置起来最麻烦因为涉及授权回调地址、刷新 Token 等。选型逻辑很简单单机/内部服务用 API Key外部用户账号体系用 OAuth测试阶段可以先无鉴权跑通再补上。有一点建议密钥信息不要硬编码到参数默认值里而是使用平台提供的密钥管理能力来维护这样插件发布之后别人使用也不会泄露你的敏感信息。3. 核心实操从API能力到可运行插件的完整流程3.1 准备OpenAPI描述或选择手动定义确认了能力形态、选型了插件类型后就可以正式开始创建了。扣子平台创建插件的第一步是选择创建方式从 OpenAPI 导入或者手动逐一新建接口。从 OpenAPISwagger导入是最省事的方式。你只要准备一份描述目标接口的 JSON 或 YAML 文件平台就能解析出所有请求路径、方法、参数和响应结构自动生成对应的插件动作。这个文件从哪来如果你的后端用的是 Spring Boot那通常是 springdoc 自动生成的 API 文档页面导出的。如果用的是其他框架也可以直接用 Apifox、Postman 之类的工具把集合导出成 OpenAPI 格式。以一份简单的订单查询接口为例OpenAPI 里关键的描述片段大致是这样的{ openapi: 3.0.0, info: { title: 订单服务, version: 1.0.0 }, paths: { /order/{orderId}: { get: { summary: 根据订单号查询订单详情, parameters: [ { name: orderId, in: path, required: true, schema: { type: string }, description: 订单编号例如 ORD20240101001 } ], responses: { 200: { description: 查询成功 } } } } } }注意看那个summary和description这两个字段虽然不影响接口调用逻辑但直接影响大模型能不能正确使用这个插件。大模型拿到插件工具列表后是靠这些描述来决定什么时候该调用、参数该填什么的。如果你的summary写的是queryOrder,描述里没有任何业务上下文智能体很可能在用户明确问订单时也想不到去调它。所以哪怕接口文档是现成的创建插件前也一定要把 summary 和 description 改成人话比如根据订单号查询订单详情输入格式为 ORD 开头的字符串。3.2 创建插件并配置工具动作的逐步操作创建插件的入口通常在插件管理页面选择一个团队空间新建插件后填写插件名称、插件描述、图标等信息。这里有个细节插件名称和描述要尽量体现能力范围比如订单查询工具而不是用内部代号。因为插件推给其他团队成员使用的时候大家是先在列表里看到名字和描述来决定是否引入的取一个业务可读的名字能省去很多沟通成本。新建之后你可以选择导入之前准备好的 OpenAPI 文件也可以手动添加工具也就是插件动作。手动添加时需要填的信息包括接口名称、接口描述、请求地址、请求方法、请求参数、返回结果说明等。如果是比较简单的接口手动也没问题但参数一多就容易漏字段我还是推荐用 OpenAPI 导入打底再在界面上微调。接下来需要确认请求参数的数据结构。扣子上支持普通参数和嵌套对象比如一个订单查询接口除了订单号本身可能还需要一个可选的traceId用于链路追踪。这时候在参数配置里把traceId标记为非必填再给一个示例值就好。大模型在调用时会根据用户消息自动判断要不要带这个参数。参数说明同样要写得清楚要让模型明白这个参数对应业务里的什么概念越具体越好。3.3 入参出参定义与智能体识别的关键细节入参和出参的定义是整个插件创建过程里最值得花心思的地方。我踩过很多次坑之后总结出三条经验第一参数数量宁少勿多。很多接口文档动不动就十几个参数其中可能一半是appId、sign、timestamp这种签名参数。这些签名参数在 API 插件里其实不需要暴露给大模型因为平台本身配置鉴权后签名逻辑多半已经在网关层处理。把所有参数一股脑放上去模型选择困难不说还可能把参数值传错。正确做法是只暴露必要的业务参数其余在代码步骤里自动填充。第二出参结构要可预期。如果接口的返回结构是多层嵌套、字段命名碎片化比如data.items[0].orderInfo.status这种大模型依然能解析但解析错误的概率会上升。比较稳妥的做法是在插件里加一个代码步骤把返回结果压平成简化结构。比如只保留订单号、订单状态、下单时间、金额四个字段其他全部丢弃。这样模型回答用户问题时信息够用也不容易被无关字段干扰。第三常见错误信息要做映射。API 返回错误码时通常只有一串数字或英文短语比如{ code: 5002, message: Invalid signature }。如果让模型直接看到这个原始返回它给用户的回答就会非常技术化。建议在代码步骤里把错误码翻译成用户能看懂的提示比如查询失败订单号格式不正确请检查后重试。一个细节可能就决定了插件好不好用。3.4 鉴权与密钥管理对 API 插件来说鉴权配置一般在插件设置的服务鉴权区域完成。比如你的接口要求调用方在 Header 里带Authorization: Bearer token就在鉴权类型里选Bearer Token并填入对应的 Token 值。创建插件时填好一次后续该团队下所有智能体在调用这个插件请求时都会自动带上凭证使用方完全感知不到。这里有个比较隐蔽的问题值得注意有些内部接口不认标准 Authorization 头而是要求自定义 Header比如X-Api-Key: key。在配置鉴权时如果选 Bearer 类型生成的请求头名称可能对不上导致 401。所以配置鉴权后一定不要急着发布先用平台自带的试运行功能发一个真实请求用curl或浏览器的开发者工具看一下实际发出的请求头是否符合预期。这一步能省去后面很多排查时间。4. 测试、调试和发布上架中的真实踩坑记录4.1 本地调试连接不上先查这四个方面插件创建完成后第一步测试通常是在平台的试运行里直接发起调用看看能否拿到正确返回。但你大概率会碰到连不上服务的情况我自己的排查顺序是固定的从容易到困难URL 是否拼接正确。检查工具配置里的请求地址是否为完整的可公网访问的 URL。内网地址比如http://localhost:8080或http://192.168.x.x在扣子云端根本无法访问必须换成已部署在外网的网关地址。即使你只是本地开发也需要用内网穿透工具把服务映射成一个公网临时域名。请求方式和 Content-Type 是否匹配。GET 请求不要把参数写在 Body 里POST 要确认格式是 JSON 还是表单不一致会直接报错。Header 是否正确。特别注意自己配置的鉴权头名称、大小写有些网关服务对 Header 大小写敏感。回调请求时所用的协议是否一致。如果服务是 HTTP而配置里填成了 HTTPS同样连不通。这套排查思路适用于绝大多数调用失败、连接被拒类问题先不要急着改代码把请求链路摊开看是哪一环断了。4.2 返回结果答非所问多半是字段描述问题调试里最让人头疼的还不是调用失败而是接口明明通了、返回也正常但智能体回答用户问题时总是胡说。比如查询订单成功返回里明明有金额amount: 199.00模型回答却说订单金额是 0。这种情况十有八九是字段描述缺失导致的——大模型并不认识后端返回的字段名amount这个词对它有参考但如果返回结构里还有price、total等相似概念模型就会猜错。解决方式是在返回结构的字段说明里把每个字段是什么、什么单位、什么格式写清楚比如amount: 订单总金额单位元。如果返回结果能精简成固定结构我建议直接在代码步骤里返回一个已经格式化好的 JSON字段名全都用业务语义命名比如orderAmount、orderStatusName这种模型照着字段名就能给出准确回答。还有一类情况是返回里混入了大量调试日志或嵌套对象导致模型上下文被无关信息污染。这种就更是要做结果精简了——只留用户真正关心的字段。我在对接一个物流查询接口时曾经把轨迹数组全量返回给模型结果它在总结时经常把中间节点当终点后来我把轨迹只提取最新一条状态 预计到达时间两个字段准确率立刻上来了。4.3 发布到插件商店的注意事项插件调通了之后如果你想给整个团队或者更多用户使用就需要走发布流程。发布前有几件事必做补全使用说明。说明里要写清楚这个插件适用什么场景、数据来源是哪里、有没有调用频率限制。说明对用户选插件很重要对审核人也同样重要。测试用例覆盖边界。包括正常请求、空参数请求、非法参数请求三类至少保证异常场景不会让整个智能体报错。密钥安全确认。确认鉴权密钥没有以明文形式出现在插件描述或测试用例里发布到商店的插件会经过安全审查。如果你只是自己用不发布到公共插件商店其实没必要反复申请审核直接在智能体配置里引用这个插件就行。但即便不公开发布我也建议在团队空间里把权限管理做好避免误删。5. 进阶玩法代码插件和本地服务型插件的实用性建议5.1 代码插件到底能干什么最后聊聊进阶部分。API 插件解决的是把已有接口暴露给智能体的问题但有些能力不能简单靠一次 HTTP 请求实现需要编排或计算这时候代码插件就派上用场了。我在实际项目里用过代码插件做这几类事情给你参考多接口聚合用户问一个综合信息问题时插件内部按顺序调用多个接口比如先查用户信息再查用户订单把结果合并成一个 JSON 返回给模型。如果不做聚合模型可能只调一个接口就匆忙回答。数据格式标准化把不同来源的日期格式统一成YYYY-MM-DD把单位从分转成元把状态码翻译成中文描述。数据加解密有些内部接口的数据是加密传输的直接暴露给大模型没意义代码里先解密再返回大模型拿到的就是可读内容。条件判断与容错当一个接口失败时自动降级调用备用接口这类逻辑放在插件代码里比让模型拿着多个工具自行判断稳定得多。代码插件的开发方式是在插件动作里选择代码类型的步骤然后编写函数。平台支持 Python 和 JavaScript函数接收定义好的输入参数返回值会作为后续步骤的输入或最终返回结果。一般来说语法就是普通函数写法需要注意的地方有两点一是外部网络请求在代码里能否直接发起不同平台规则可能不一样稳妥起见尽量把网络请求交给 API 步骤代码步骤做纯逻辑加工二是代码执行有自己的超时控制不要在代码里做过重的循环或同步阻塞操作。5.2 代码插件的调试技巧代码插件调试起来比 API 插件麻烦一些因为没法直接在浏览器里看请求。我的习惯是先在本地把函数逻辑跑通再粘到平台里。平台提供的试运行支持填测试参数、查看模拟返回调试信息里也会把函数的输入输出打出来。养成一个习惯在代码里不打印日志而是把关键中间态都放进返回结果里比如返回一个调试用的debugInfo字段测试通过后再把它去掉。这样每次试运行你都能看到代码实际走了哪个分支定位效率会高很多。5.3 插件维护与版本管理插件创建完不是一劳永逸的接口升级、字段变更都可能导致智能体行为异常。我给自己定了几条规矩版本日志每次修改插件后在描述里简要记录改动内容。扣子平台对插件的变更通常有版本概念正式使用前先在智能体调试里跑一轮回归。接口兼容性如果外部接口的返回字段改名了需要同步更新插件里的字段描述否则模型可能拿不到新字段值。基准用例把一组必须答对的测试问题存下来每次改完插件都拿这组问题跑一遍智能体对话观察有没有回归。这个方法成本不高但能避免很多改完更糟的翻车。另外一个建议是创建插件时命名和描述保持一致不要出现订单查询的插件描述里写可以根据用户问题查询天气这种明显不匹配的内容。插件描述与实际能力不一致是智能体调用错乱的高发原因之一。6. 关于权限边界与调用频率的一些补充扣子平台对插件的调用频率是有限制的一次性大批量请求可能触发限流。如果你在插件里接的是公共接口或免费层级的第三方服务尤其要注意这一点。可以在插件描述里写明接口限流 50 次/分钟让后续使用你插件的人在构建智能体时对触发频率有心理预期。对内部接口也一样最好在网关层做限流保护避免智能体被高频调用时把后端打垮。权限方面还要注意数据最小化原则。插件能拿到什么数据就意味着智能体在回答中可能透出什么数据。如果你的接口里包含敏感字段手机号、身份证等建议在代码步骤里直接过滤掉不要暴露给大模型。我见过有人把数据库查询接口整个暴露给插件结果用户在对话里诱导智能体返回了不该返回的记录这是一个真实存在的风险。所以在设计插件时就明确哪些字段永远不带出比事后补救要安全得多。不管你是第一次在扣子上建插件还是已经建过几个总觉得不够顺手建议都按这个思路重新梳理一遍自己的插件参数精简了吗描述够不够人话返回结果是不是扁平化鉴权信息有没有安全存放把这几个问题答完你的插件基本就是可复用、可维护的状态了。