本文介绍在智能体应用的调用过程中如何使用自定义参数透传的功能。需要用户透传参数的地方,基本包含两个方面:1. 插件或者工作流自身的参数 2. 插件中用户级鉴权 token 。通过自定义参数透传功能,您可以在调用智能体应用的同时传入插件或工作流所需的参数。
工作流与智能体编排应用的参数透传
在工作流应用和智能体编排应用中,您可以自定义开始节点的参数。例如,在一个查询城市天气信息的工作流应用中,您可以定义String类型的参数city
和date
。系统还设置了一个默认参数query
,用于接收您输入的Prompt。
您可以使用prompt
传递query
参数,使用biz_params
传递自定义参数,具体示例如下:
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/1e06bb0495bb48c3a6a37444e8f1416b/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "你好",
"biz_params": {
"city": "Hangzhou"
"date": "2024-08-23"
}
},
"parameters": {},
"debug": {}
}' --verbose
自定义参数透传的使用
1. 创建支持自定义参数透传的插件
在应用中心 - 应用组件 - 插件管理页面中,创建自定义插件。
2. 指定需要透传的参数
以下是一个指定自定义透传参数的插件接口 YAML 配置文件的例子:
openapi: 3.0.1
info:
title: 寝室公约查询工具
description: 寝室公约查询工具,可以根据序号查询特定条目。
version: "v2"
servers:
- url: {domain}
paths:
/article/{username}:
post:
operationId: get_article
summary: 查询寝室公约第几条,用整数数字
parameters:
- in: path
name: username
schema:
type: string
required: true
description: 用户名
x-source: user # 透传参数标识
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [article_index]
properties:
article_index:
type: integer
description: 寝室公约第几条,用整数数字
x-source: user # 透传参数标识
responses:
"200":
description: 查询成功
content:
application/json:
schema:
type: object
required: [article]
properties:
article:
type: string
description: 寝室公约条款
该配置文件遵循 OpenAPI 3.0 协议,您可以参照文档 创建自定义插件 和 OpenAPI 官方文档 中的指引,了解各个对象和字段的含义,进一步自定义您的插件接口。
在上述配置文件的例子中,插件接口需要两个由应用用户提供的参数,分别为
路径参数
username
请求体参数
article_index
为此,需要在这些参数的属性中添加 schema extension x-source
,并赋值为user
,即可将这些参数标识为透传参数。
3. 在应用发布窗中测试透传参数
在 应用中心 - 我的应用 中,新建应用并引入您配置的自定义插件。
在插件变量窗口,您可以传入插件自定义的透传参数
4. 在应用 API 接口中传入透传参数
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{appId}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "你好",
"biz_params": {
"user_defined_params": {
"1999849738269549_plugin_param_test": {
"username": "my_name",
"article_index": 10
}
}
}
},
"parameters": {},
"debug": {}
}' --verbose
一级参数 | 二级参数 | 三级参数 | 四级参数 | 五级参数 | |
参数名 | input | biz_params | user_defined_params | ${plugin_id} | ${plugin_params} |
参数值 | JSON | JSON | JSON | JSON(mutiple) | String(mutiple) |
为了使用插件参数透传功能,您需要在调用应用的 API 的
input
对象中,使用biz_params
传递相关数据user_defined_params
是一个固定参数,表示这个对象中传入的是自定义插件参数信息接下来,以插件 ID 为键(例如
1999849738269549_plugin_param_test
),每一个值的对象即相关插件的待透传参数信息在对象最内侧,将包含多个键值对,每个键值对表示用户自定义的待透传参数名及其指定值。请注意,传入没有
x-source
属性修饰的参数将不会产生任何效果。
插件用户级鉴权的使用
1. 开启插件的用户级鉴权
如果您的插件接口需要用户自主输入鉴权 Token ,请根据下图所示开启插件用户级鉴权的功能。
2.测试窗透传用户级鉴权token
在 应用中心 - 我的应用 中,新建应用并引入您配置的自定义插件。
如果您配置了插件用户级鉴权的功能,您能够在插件鉴权窗口传入鉴权 Token
3.应用调用api中透传用户级鉴权Token
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/1e06bb0495bb48c3a6a37444e8f1416b/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "你好",
"biz_params": {
"user_defined_tokens": {
"1999849738269549_plugin_param_test": {
"user_token": "my_token1"
}
}
}
},
"parameters": {},
"debug": {}
}' --verbose
一级参数 | 二级参数 | 三级参数 | 四级参数 | 五级参数 | |
参数名 | input | biz_params | user_defined_tokens | ${plugin_id} | user_token |
参数值 | JSON | JSON | JSON | JSON(mutiple) | String |
为了使用插件参数透传功能,您需要在调用应用的 API 的
input
对象中,使用biz_params
传递相关数据user_defined_tokens
是一个固定参数,表示这个对象中传入的是用户级鉴权信息接下来,以插件 ID 为键(例如
1999849738269549_plugin_param_test
),每一个值的对象即相关插件的鉴权信息user_token
是一个固定参数,以该参数为键,其值为该插件需要的用户鉴权 Token