通过 API 传递插件参数

自定义插件参数传递

本文以寝室公约内容查询工具作为示例，向您展示 API 如何调用应用的自定义插件参数传递功能。

自定义插件的参数通过关联的智能体应用传递，或通过工作流应用中的插件节点传递。

下方示例展示在智能体应用中如何传递自定义插件参数。

如何使用

步骤一：创建自定义插件工具

如果已创建插件工具或已导入了插件，请跳过此步骤。

创建自定义插件

访问百炼控制台的插件页面，单击添加自定义插件，填写插件信息，如需要鉴权请打开是否鉴权开关，填写鉴权配置信息。

示例插件描述：寝室公约查询工具，可以根据输入的数字索引查询特定条目。

示例插件 URL：https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run

示例鉴权配置：鉴权类型选择用户级鉴权，位置选择Header，Type 选择 basic。请注意： 插件描述是对插件用途的简要说明，能帮助大模型判断当前任务是否需要调用当前插件，请使用自然语言进行描述。

创建工具

填写工具信息，配置输入参数和输出参数。请注意：

工具描述能帮助大模型更好的理解工具功能和使用场景。请使用自然语言进行描述，尽量给出使用示例。
参数名称尽可能带有含义，可以帮助大模型理解当前需要识别的参数信息是什么。
参数描述是对该入参的功能描述，要简练且准确，帮助大模型进一步理解取参的方式。
输入参数的参数传入方式 务必选择业务透传。

此处示例将寝室公约内容索引 article_index 设置为业务透传参数。填写工具名称为 寝室公约查询工具，请求方法选择 POST，提交方式选择 application/json。输入参数 article_index 的类型设为 Number，传入方法选择 Body，设置为必填。输出参数名称填写 article，参数描述填写"寝室公约内容"，类型设为 String。

测试并发布

单击测试工具，运行通过后，发布插件。

步骤二：智能体应用关联指定插件

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

可在已发布的插件卡片上单击添加到智能体，选择需要关联的智能体应用；
也可在应用内单击**+插件**，关联指定的自定义插件；
然后直接发布应用。

步骤三：API 调用

无需鉴权时：通过 API 调用自定义插件，使用 biz_params 的 user_defined_params 传递自定义插件信息，your_plugin_code 替换为实际的插件 ID，并传递插件中配置的输入参数键值对。

插件 ID 可在插件卡片上获取。

本示例中传入寝室公约索引 article_index 参数值为 2，查询第二条寝室公约内容，并返回正确结果。

import os
from http import HTTPStatus
# 建议dashscope SDK 的版本 >= 1.14.0
from dashscope import Application

biz_params = {
    # 智能体应用的自定义插件输入参数传递，自定义的插件ID替换your_plugin_code
    "user_defined_params": {
        "your_plugin_code": {
            "article_index": 2}}}

response = Application.call(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='YOUR_APP_ID',
        prompt='寝室公约内容',
        biz_params=biz_params)

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
    print(f'请参考文档：https://help.aliyun.com/zh/model-studio/developer-reference/error-code')
else:
    print('%s\n' % (response.output.text))

响应示例

寝室公约的第二条规定如下：
"寝室成员应当互帮互助、互相关心、互相学习、共同提高；宽容谦让、相互尊重、以诚相待。"

需要鉴权时：在 biz_params 中额外增加 user_defined_tokens 字段传递鉴权令牌。将 your_plugin_code 替换为实际的插件 ID，传入鉴权信息。

biz_params = {
    "user_defined_params": {
        "your_plugin_code": {
            "article_index": 2
        }
    },
    "user_defined_tokens": {
        "your_plugin_code": {
            "user_token": "your_token_value"
        }
    }
}

​自定义插件参数传递

​如何使用

​步骤一：创建自定义插件工具

​步骤二：智能体应用关联指定插件

​步骤三：API 调用

​相关文档

自定义插件参数传递

如何使用

步骤一：创建自定义插件工具

步骤二：智能体应用关联指定插件

步骤三：API 调用

相关文档