自定义插件和工具

一、核心概念

• 插件（Plugin）：工具的集合，用于统一描述能力与授权方式，便于在智能体中复用。
• 工具（Tool）：插件内的具体能力单元，对应一个 API 调用。定义请求方法、URL、输入参数、输出参数等。

适用人群

产品、研发、运营同学均可使用；推荐由具备接口基础的成员完成工具配置与联调。

二、创建插件

1. 进入 HelpKnow → 插件→ 自定义插件，点击右侧 新建插件。
2. 在弹窗中填写：
   • 插件名称：以规范命名区分用途，如“helpknow平台相关插件”。
   • 插件描述：说明插件包含哪些工具、用于什么场景，便于后续识别与复用。
   • 授权方式：根据接口是否有统一鉴权进行选择，在插件级配置统一鉴权后，底下所有工具皆使用同一鉴权。
3. 点击 创建，进入插件详情页。

建议：将与同一平台相关的工具归到一个插件下，统一管理鉴权与公共 Header。

三、在插件内新建工具

1. 在插件详情页点击 新建工具，填写基础信息：
   • 工具名称：用“动词 + 名词”描述，如“获取智能体列表”。
   • 工具 ID：唯一标识，支持字母、数字、下划线，如 GET_BOT_LIST。
   • 工具描述：说明使用场景与作用，帮助大模型理解何时调用。
2. 配置 请求地址及方法：
   • 方法：GET / POST / PUT / DELETE。
   • URL：可填完整地址或基于插件 Base URL 的相对路径。示例：https://api.helpbots.ai/api/chats/agent-list

四、输入参数配置

输入参数用于约束大模型在调用工具时必须提供的内容，分四类：Header / Path / Query / Body。每类下可添加多个参数。

通用字段说明

字段	说明	示例
参数名	与实际 API 字段一致，大小写敏感	Authorization、keyword
类型	string / number / boolean / array / object	string
默认值	调用工具时默认使用该值	1
是否必填	决定模型是否必须提取该字段	勾选后模型会主动追问获取对应参数的值
描述	用自然语言解释含义，便于模型理解	“查询关键词，支持品牌名或SKU”

1）Header

放置鉴权与通用请求头，如 Authorization: Bearer <token>、Content-Type: application/json。

2）Path

用于 RESTful 路径占位，如 /orders/{order_id} 中的 order_id。因此配置了该参数，需要使用的话需要在路径中拼上，格式参考示例使用{}

3）Query

URL 查询串参数，如 ?page=1&page_size=20。常见：分页、排序、过滤条件、时间窗等。该类型参数无需在路径中填写

4）Body

请求体参数（POST/PUT 常用）。支持 对象 与 数组 的嵌套结构。添加子项可定义层级字段。

命名建议：面向业务与模型可读性，避免过度缩写；必要时在描述中补充枚举值与格式要求（如时间戳/ISO8601）。

五、输出参数配置

从原始响应中提取出来对模型有意义的字段，无意义的ID和报错代码可以不用保留。

常见配置方式

• 顶层对象：如 data。
• 列表字段：如 list（类型：Array）。
• 子项字段：在 ArrayItem 中继续添加，如 add_time（创建时间，string）、model（问答模型，string）。

示例：输出结构定义

{
  "data": {
    "list": [
      {
        "add_time": "2024-12-01 10:00:00",
        "model": "gpt-4o-mini"
      }
    ]
  }
}

以上仅为结构示例。请根据实际接口返回字段设置，尽量保留能直接回答用户问题的关键字段，减少模型二次理解成本。

六、调试（添加到智能体前的自测）

1. 点击工具页面右上角 调试。
2. 在 输入 页签补齐各类入参的值（Header / Path / Query / Body）。
3. 点击 运行，在 输出 页签查看响应与映射是否符合预期：

• 若 原始响应 正常但 输出 为空，检查输出参数的层级与字段名是否与响应一致。
• 若返回错误响应，请再次检查配置是否与接口要求一致，或是否接口提供方问题

七、发布与上线

1. 工具调试通过后点击 保存，保存实时生效。

   

2. 在智能体的工具模块添加您配置好的工具
3. （可选）在智能体设定中描写工具的使用条件，例如“当用户信息包含“我买的东西到哪了““什么时候发货“等内容时可以判断用户意图为查询订单，当用户提供了订单号，可以使用Get_order工具查询用户订单”；这样能够让AI更加灵活的使用工具满足业务需要
4. 

工具配置准则

• 一个工具只做一件事：与单一 API 对应，便于调试与追踪。
• 入参与描述可读：面向模型与业务同学书写，避免缩写尽量使用自然语言。
• 输出精简：保留关键字段；列表字段建议限制必要子项。
• 统一鉴权：尽量放在插件层；工具层仅补充个别差异化 Header。
• 容错与提示：为常见错误码设置清晰的错误信息，便于一线定位问题。

参考示例：获取智能体列表（GET）

方法与地址： GET https://api.helpbots.ai/api/chats/agent-list

输入参数

位置	参数名	类型	是否必填	说明
Header	x-api-key	string	是	用于鉴权以及对应项目的token
Query	page	number	否	智能体列表页码，默认 1
Query	page_size	number	否	每页条数，默认 20

输出参数

字段	类型	说明
data	object	数据容器
list	array<object>	智能体列表
add_time	string	创建时间
model	string	问答模型

{
  "data": {
    "list": [
      { 
"add_time": "2024-12-01 10:00:00", 
"model": "gpt-4o-mini"
 }
    ]
  }
}