如何创建自定义插件

自定义插件包括个性化开发的插件、第三方平台的API以及从云市场导入的插件。创建自定义插件的流程如下：

创建与调用个性化开发的插件或第三方平台的API

步骤一：创建插件

1. 访问插件页面，单击新增自定义插件。

   

2. 填写插件信息。

   	插件名称：输入具有语义的名称，支持中英文。 示例：寝室公约查询工具test
   	插件描述：对插件功能和使用场景的简要说明。能帮助大模型判断当前任务是否需要调用当前插件，请使用自然语言进行描述。 示例：根据输入的数字索引查询特定条目的寝室公约内容。
   	插件URL：插件的访问地址。 示例：https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run 同一个HTTP请求下，不同的路径被拆分成了不同的API（即下方创建工具中的工具路径） 同一插件下的不同工具使用相同的域名，每个工具的工具路径对应一个独立的API 例如：xx插件下包含两个API： 查询：https://xxx.com/query 删除：https://xxx.com/delete 在这个示例中，https://xxx.com对应插件URL，/query和/delete对应下方创建工具中的工具路径。这表明该插件下包含两个工具。

如需要鉴权请打开鉴权开关，填写鉴权配置信息。

1. 填写完成后单击确认创建插件 > 创建工具或单击继续添加工具。

步骤二：创建工具

1. 填写工具信息、配置输入/输出参数以及高级配置。

   

   工具参数说明

   工具信息

   工具名称	输入具有语义的名称，支持中英文。
   工具描述	对工具功能和使用场景的简要说明。 帮助大模型判断当前任务是否需要调用该工具，请使用自然语言进行描述，尽量给出使用示例。 示例：“此工具用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。
   工具路径	指向插件URL的相对路径。 字段名必须以正斜杠（/）开头。 此路径将拼接到插件URL上，以构建完整的URL。
   请求方法	根据实际需求选择GET或POST请求方法来调用API接口。
   提交方式	请求或响应的编码类型。 application/json：主体内容是JSON格式的数据。 application/x-www-form-urlencoded：将表单数据编码为键值对。 这种编码方式用于 POST 请求，表单数据编码为键值对，并通过 URL 编码传输。多个键值对之间用 & 分隔，每个键和值之间用 = 分隔。URL 编码会将特殊字符转换为 % 后跟两位十六进制数的形式。例如，空格会被编码为 %20，& 会被编码为 %26，= 会被编码为 %3D 示例：name=John Doe&age=25 被编码为 name=John%20Doe&age=25

   配置输入参数与输出参数

   配置输入参数	单击增加入参，配置参数信息。
   	参数名称：尽可能带有含义，帮助大模型理解当前需要识别的参数信息是什么。例如city。
   	参数描述：对该入参的功能描述，要简练且准确，帮助大模型进一步理解取参的方式。例如，date，描述为日期的同时，可以再进一步描述date的形式，比如yyyy-MM-dd。
   	类型：指参数类型。 请求方法 参数传递方式 是否支持Object类型 GET 主要通过Query 不支持 POST 主要通过Body 支持。设置提交方式为application/json（首选） 重要 Object类型下的子属性不能为空。请单击该对象行末的图标新增子属性。
   	传参方式：要设置准确。 大模型识别：表示该参数的值需要大模型从用户输入中提取。 业务透传：表示该参数的值从外部主动透传，传递过程中不对数据进行处理或修改。 使用DashScope SDK或HTTP接口调用应用时，插件中的业务透传类型的输入参数信息通过 biz_params和user_defined_params传递给应用。具体请参见应用的参数传递。
   配置输出参数	单击增加出参，配置参数信息，所有参数均为必填项。 大模型会根据出参的定义，结合用户的问题，对API返回的结果进行筛选、重新组合，作为最终的答案返回给用户。 出参与入参一样，需要尽可能精简和准确描述，嵌套的层级也尽可能少。 重要 无论请求方式是GET还是POST，参数都支持Object类型。但Object类型下的子属性不能为空。请单击该对象行末的图标新增子属性。

   高级配置（可选）

   高级配置	为大模型增加调用示例，减少漏召回和误召回的情况。 通常用于入参比较复杂，模型构造容易出错的场景，通过提供一些样例，提升大模型调用插件的准确性。
   	Value：表示用户输入当前的Query时，期望大模型构造出的调用入参。示例：用户输入：“查询杭州明天的天气”，期望构造入参为：{"city": "杭州", "date": "2025-04-25"}。

2. 配置完成后单击保存草稿。

3. 在线调试工具API能否调通。

   单击测试工具，输入鉴权信息（开启鉴权时填写）及入参的值，单击开始运行。 如果运行失败，请根据运行结果中的报错信息对配置进行调整，并重新进行测试，直至成功运行。 入参的值可以手动输入，也可以通过代码输入。对于入参较为复杂的情况，建议采用代码模式编辑。您可以在代码编辑器中提交完整的JSON格式的入参及其相应的值。

4. 测试通过后单击发布。只有已发布的工具才能在应用中被调用。

步骤三：调用插件

从云市场导入插件

云市场提供了丰富的API，您可在云市场开通需要的API并将其导入至阿里云百炼插件列表中，以便应用进行调用。

步骤一：导入插件

1. 访问插件页面，单击从云市场导入。

2. 首次在阿里云百炼平台上导入云市场API作为插件，需要先进行服务关联角色授权。

   主账号

   RAM用户（子账号）

   如果您使用主账号登录百炼，请在SLR授权弹窗中，勾选同意上述条款，单击确认授权。

   

   如果您使用RAM用户（子账号）登录百炼，在SLR授权弹窗中，勾选同意上述条款，单击确认授权时，会有如下提示：

   

   这是因为该RAM用户（子账号）不具备创建服务关联角色的权限。请按照下述操作先授予RAM用户（子账号）创建服务关联角色的权限。获得授权后，RAM用户（子账号）即可自行从云市场导入插件至百炼或使用主账号已经导入的插件。

   1. 授权RAM用户（子账号）创建服务关联角色的权限。

      1. 使用主账号登录RAM控制台。

      2. 在左侧导航栏，选择权限管理 > 权限策略。

      3. 单击创建权限策略。

      4. 在脚本编辑的Effect、Action、Resource、Condition中分别输入以下脚本中的对应内容。

         {
             "Action": [
                 "ram:CreateServiceLinkedRole"
             ],
             "Resource": "*",
             "Effect": "Allow",
             "Condition": {
                 "StringEquals": {
                     "ram:ServiceName": "cloundapi-access.sfm.aliyuncs.com"
                 }
             }
         }

         

      5. 单击确定。

      6. 设置权限策略名称，单击确定。

         

      7. 在左侧导航栏，选择身份管理 > 用户。

      8. 找到待授权的RAM用户（子账号），单击RAM用户（子账号）操作列的添加权限。

      9. 在权限策略中选择刚才创建的权限策略，单击确认新增授权。

         至此，RAM用户（子账号）拥有了创建服务关联角色的权限。

         

   2. RAM用户（子账号）自行从云市场导入插件至阿里云百炼或使用主账号已经导入的插件。

      返回阿里云百炼控制台，单击从云市场导入，在SLR授权弹窗中，勾选同意上述条款，单击确认授权

3. 在导入云市场插件弹窗中，单击点击查看进入云市场开通需要的API。

   

4. 您可以刷新云市场 > 已购买的服务页面，等待商品状态为已开通。

   当前页面还提供了API的AppKey、AppSecret、AppCode，如果插件需要鉴权，您可以在此处获取鉴权信息。

   

5. 开通成功后，返回阿里云百炼控制台，单击从云市场导入，重新打开导入云市场插件弹窗。选择已开通的API，再单击确定，进入工具列表页面。

   

6. 从云市场导入的插件为草稿状态，需要测试、发布后再使用。

   1. 单击工具所在行的调试，进入工具测试页面。

      

   2. 输入参数后，单击开始运行。

      若运行成功，则说明接口正常。否则，请参考界面提示信息修改配置。

      

   3. 返回编辑工具页面，单击发布，发布工具。

      从云市场导入插件时，系统将自动填充出参和入参信息，但可能会存在信息缺失的情况。在发布工具时，您需要关注无法发布的错误信息，以便根据错误提示有效地解决问题。

      

   4. 已发布且启用状态的工具才能用于后续调用。

      

步骤二：调用插件

调用插件

• 方式一：在工具列表中，将已发布的工具添加到智能体应用中。

  工具只能与位于相同的业务空间里的智能体应用关联。

  1. 在工具所在行，单击添加至应用，按照界面提示将插件添加到智能体应用中。

     

  2. 在应用详情页面，您可以看到工具已经自动添加。

     您也可以单击选择插件，继续添加其他工具。最多支持添加20个工具。智能体应用会根据输入选择调用一个或多个工具。

     

  3. 测试插件的使用效果是否符合预期。

     • 无鉴权：您可以在输入框中与大模型进行对话，测试插件使用效果。

     • 用户级鉴权、服务级鉴权：您需要在开启对话前，单击配置需要传入的鉴权Token。如果不离开当前页面，可以只配置一次。

       从云市场导入的插件，不需要在当前页面输入鉴权Token。

       

     • 工具入参的传参方式选择了业务透传：您需要在开启对话前，单击配置需要传入的变量值。如果不离开当前页面，可以只输入一次。

       

  4. 测试完成后，发布应用。

• 方式二：在插件列表中，将插件下的工具添加到智能体应用中。

  1. 找到目标插件，单击添加到智能体，按照界面提示将插件添加到智能体应用中。

     工具只能与位于相同的业务空间里的智能体应用关联。

     默认仅添加已发布的工具，最多可选择20个已发布的工具添加至智能体应用中。

     

  2. 参考方式一的操作，在应用详情页面，测试插件使用效果，并发布应用。

• 方式三：在阿里云百炼应用中将工具添加至智能体应用或工作流应用，测试插件使用效果，并发布应用。具体操作请参见插件：接入图像视频、代码执行等更多效率工具、工作流应用。

• 方式四：通过应用调用API使用插件。当通过API调用应用时，如果应用中关联的插件存在业务透传参数或开启了用户级鉴权，则需要通过参数biz_params传递鉴权信息或透传参数信息。具体操作请参见应用调用。

• 方式五：通过Assistant API调用工具。请在Assistant API文档中搜索tools关键字，查看如何使用Assistant API调用工具。

获取工具ID

工具ID用于标识具体的工具。通过API调用工具时，需要正确传递工具ID，以确保请求能够被正确识别。

1. 在插件列表中，找到工具所属的插件，单击查看详情。

2. 将鼠标悬浮于工具名称旁边的图标上。

3. 单击图标，复制工具ID。

   

管理自定义插件与工具

错误码

发布工具时的常见错误信息如下表所示：