# 创建工具 工具是一组相关的API集合，一个工具通常包含多个执行动作，每个执行动作用于实现特定功能。例如，一个天气查询工具可能包含查询当前天气、未来天气预报等执行动作，每个动作通过调用相应的API来实现。 平台在资产中心预置了部分工具，同时也支持用户根据需求自定义创建工具。在Agent中添加工具，可以对Agent进行能力扩展。 #### 前提条件 - 需要具备AI原生应用引擎管理员或开发者权限，权限申请操作请参考[AppStage组织成员申请权限](https://support.huaweicloud.com/usermanual-appstage/appstage_04_0009.html)。 - 已获取API服务的连接信息以及调用API所需的访问权限和密钥。 #### 创建工具 将选定的API服务注册为一个工具。 1. [进入AI原生应用引擎](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0638.html#appstage_04_0638__section439520293419)。 2. 在AI原生应用引擎的左侧导航栏选择"Agent编排中心 \> 我的工具"，单击"创建工具"。 3. 在"创建工具"页面，配置如[表1]所示参数。 表1工具参数配置说明 | 参数名称 | 参数说明 | |:---|:---| | 名称 | 自定义工具名称。名称长度不能超过32个字符，可包含中文、大小写字母、数字、下划线、中划线、英文小括号，不能以下划线、中划线、英文小括号开头。 | | 描述 | 填写工具功能或作用等描述。 | | 图标 | 支持选择系统图标。 | | 协议 | API服务接口通信协议。 - **https** - **http** | | 主机地址 | 提供API服务的服务器地址。以https://aiae.appstage.myhuaweicloud.com/v1/chat/completions为例，主机地址为aiae.appstage.myhuaweicloud.com。 | | 基准URL | 基准URL（Base URL）指的是域名的根路径，默认为/。必须以/开头，且不能有连续多个/，不包含除/._-以外的特殊字符和空格。 以https://aiae.appstage.myhuaweicloud.com/v1/chat/completions为例，基准URL可以填写为/、/v1、/v1/chat或/v1/chat/completions。原则上基准URL+执行动作中填写的接口路径拼接起来为完整的/v1/chat/completions即可。 | | 验证方式 | API的验证方式。 - **基本认证：**用户在创建连接时提供有效的用户名（Username）和密码（Password）即可，此处无需定义。 - **API key：**用户在使用连接器前需提供API密钥所需的字段，以及该验证所必须的字段值。 - **OAuth 2.0：**使用Oauth 2.0身份验证框架对服务进行身份验证。 在使用此身份验证类型之前，需要向服务注册应用程序，以便它可以接收用户的访问Token。 - **IAM：** 该认证用于通过用户名/密码的方式来获取IAM用户的Token。华为IAM认证的使用方式参考[获取IAM用户Token](https://support.huaweicloud.com/api-iam/iam_30_0001.html)。 - **AK/SK：** 使用访问密钥ID（AK，Access Key ID）和密钥（SK，Secret Access Key）对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份验证。用户在创建连接时输入值即可，此处无需定义。 APIG的App认证则需提供AppKey以及AppSecret。 - **自定义：**自定义用户在创建连接时的身份验证方式。 - **无验证：**用户不需要任何身份验证即可创建与连接器的连接。无验证时，任何用户都可以使用您的连接器。 | 4. 配置完单击"创建"。 工具创建成功后，进入工具详情页面，请参考[创建执行动作]添加执行动作。 #### 创建执行动作 添加API服务下的具体接口作为工具的执行动作。 1. 在工具详情页面，单击"创建执行动作"，配置执行动作基础信息，参数如[表2]所示。 表2执行动作基本信息参数说明 | 参数 | 说明 | |:---|:---| | 名称 | 执行动作指需要完成的特定任务。 自定义执行动作的名称，比如：发送电子邮件、更新行。名称长度不能超过64个字符，可包含中文、大小写字母、数字及下划线、中划线、英文小括号，不能以下划线、中划线、英文小括号开头。 | | 英文名称 | 执行动作的英文名称。由1\~64个字符组成，包含大小写字母、数字、下划线、中划线。 部分模型在调用工具时，只能识别工具的英文名。 | | 类型 | 默认为API，表示通过调用API的方式创建执行动作。 | | 可见性 | - **可见** - **隐藏** 设置为隐藏的执行动作，在流编排中将不可见。 | | 描述 | 执行动作的描述信息。 | 2. 单击"下一步"，配置输入，参数如[表2]所示。 表3输入参数说明 | 参数 | 说明 | |:---|:---| | 接口路径 | API的请求路径。必须以/开头，且不能有连续多个/，不包含除/_-:@%+.\~#?\&={}\[\]()、$以外的特殊字符和空格。 以https://aiae.appstage.myhuaweicloud.com/v1/chat/completions为例，接口路径可以填写为v1/chat/completions、/chat/completions、/completions或不填。原则上基准URL+执行动作中填写的接口路径拼接起来为完整的/v1/chat/completions即可。 | | 输入参数 | API的请求参数，如果被调用API没有请求参数可不填。 - **请求头（Header）：** HTTP请求消息的组成部分之一，请求头负责通知服务器有关于客户端请求的信息。 单击参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002121984040.png)可以新增参数，参数配置说明请参见[表4]。 - **请求体（Body）：** HTTP请求消息的组成部分之一，请求体呈现发送给服务器的数据。 - **JSON/XML：** JSON、XML格式的数据。 如果请求体使用XML格式，XML header参数必须配置。 - 导入：可直接粘贴被调用API的JSON、JSON Schema或XML数据，减少逐个配置参数的工作量。导入文件示例请参见[JSON Schema/JSON/XML文件示例]。 - 复制：复制请求体参数的JSON或XML数据。 - 预览：可以预览参数的JSON或XML结构。 - 参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002173160033.png)：可选择是否开启"是否支持根节点输入"参数，开启并发布对应工具后，在创建流中添加该执行动作时可以自定义请求体参数的值。 - 参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002137722390.png)：新增参数，参数配置说明请参见[表4]。 - **form-data：** 表单数据，用于网页表单提交（含文件上传）、多类型数据混合传输（如文本 + 图片）。 参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002137880486.png)：新增参数，参数配置说明请参见[表4]。 - **Binary：** 直接传输非文本数据（如图片、视频、音频、可执行文件等），不进行结构化解析，以原始字节流形式发送。 输入、输出仅支持配置一处。例如，输出入参数选择了"Binary"，则输出不显示，反之亦成立。 - **查询参数（Query）：** 查询参数会追加到URL。例如，在 /items?id=#### 中，查询参数为ID。 单击参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002157345661.png)可以新增参数，参数配置说明请参见[表4]。 - **路径参数（Path）：**自动解析接口路径中包含的路径参数。 | 表4参数配置说明 | 参数 | 说明 | |:---|:---| | XML header | 当请求体为XML格式数据时，必须配置此参数。 XML header为XML文档的声明头，用于定义XML文档的基本格式和编码规则，是XML文档的标准起始部分。 | | 参数名称 | 输入参数的名称。由1\~128个字符组成，不能以中划线、英文小括号、空格开头。 | | 显示字段 | 用户在表单中看到的参数项标签。 | | 必填 | 勾选该参数是否是用户必填项。 | | 参数类型 | 选择参数类型，支持string、number、boolean、integer类型。 此外，当请求体（Body）为JSON或XML时，还支持array、object类型参数；当请求体（Body）为form-data时，还支持file类型参数。 | | 说明 | 关于输入值的介绍说明。 | | 操作 | - 单击![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002121984044.png)：配置参数在界面的显示样式。配置完成并发布对应工具后，在创建流中添加该执行动作时可以查看参数的界面显示效果。 - **参数类型：**选择参数类型。 - **格式：** 设置用户输入该参数时界面显示的样式，可选择文本框、日期时间、富文本、下拉列表。不同的参数类型可选择的格式不同。 当格式选择为下拉列表时，需设置标签和下拉列表的值。单击"新增"可进行添加。 设置完成后，如果勾选了"支持多选"，则可在创建流中添加该执行动作时选择多个值，否则，只能选择一个值。需要配置分隔符，分隔符只能输入单个特殊字符，如",""$"、"%"、"\^"、"\&"等，不设置时，默认为","。 - **可见性：** 设置用户输入该参数时界面显示的可见性。 无：在流中正常显示。 **高级：**默认隐藏在高级设置菜单里。 **隐藏：**该参数向用户隐藏。 **重要：**优先显示在表单的最开始。 - **默认值：**当格式选择为文本框、日期时间、富文本时，支持设置该参数的预设值。 - **单击** ![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002121825896.png)：新增节点。 - **单击** ![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002157264093.png)：删除该节点。 | 3. 单击"下一步"，配置输出参数，参数如[表2]所示。 表5输出参数说明 | 参数 | 说明 | |:---|:---| | 添加响应 | 单击"添加响应"，根据被调用API的响应码信息添加响应码。 | | 输出参数 | 配置输出参数，如被调用API没有响应参数可不填。 - **响应体：** HTTP响应消息的组成部分之一，响应体呈现发送给服务器的数据。 - **JSON/XML：** JSON、XML格式的数据。 - 参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002173175133.png)：新增参数，参数配置说明请参见[表4]。 - 当选择XML格式时，单击参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002173056813.png)，配置XML标签名。 - 导入：可直接粘贴被调用API的JSON Schema、JSON或XML数据，减少逐个配置参数的工作量。导入文件示例请参见[JSON Schema/JSON/XML文件示例]。 - 复制：复制请求体参数的JSON或XML数据。 - 预览：可以预览参数的JSON或XML结构。 - **Binary：**文件格式数据。输入、输出仅支持配置一处。例如，输出入参数选择了"Binary"，则输出不显示，反之亦成立。 - **响应头：** HTTP响应消息的组成部分之一，响应头负责通知服务器有关于客户端请求的信息。 单击参数列表"操作"列的![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002121984048.png)可以新增参数，参数配置说明请参见[表4]。 | 4. 单击"下一步"，调试校验工具，验证工具是否可用。 1. 配置用例，参数说明如[表6]所示。 表6用例参数说明 | 参数 | 说明 | |:---|:---| | 实例 | 配置实例是为了建立与工具的连接并验证用户权限，如果未配置实例，则无法进行调试。 单击"新建实例"，配置实例名称、描述及验证信息，验证信息填写工具创建时所配置的鉴权信息，单击"保存"。 验证信息与步骤[3]所选的验证方式相关，如果验证方式为"无验证"，则无需配置实例。 | | 输入参数 | 配置输入参数，向工具提供用于验证的样本数据。 | 2. 单击"提交测试"，在"测试结果预览"区域查看测试结果。 5. 工具调试完成后，单击"保存"。 #### JSON Schema/JSON/XML文件示例 - JSON Schema ``` { "properties": { "str": { "description": "", "default": "", "x-hw-default": "", "type": "string", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [] }, "obj": { "description": "", "default": "", "x-hw-default": "", "type": "object", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [], "properties": { "obj_str1": { "description": "", "default": "", "x-hw-default": "", "type": "string", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [] }, "obj_str2": { "description": "", "default": "", "x-hw-default": "", "type": "string", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [] } }, "required": [ "obj_str1", "obj_str2" ] }, "arr": { "description": "", "default": "", "x-hw-default": "", "type": "array", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [], "items": { "description": "", "default": "", "x-hw-default": "", "type": "string", "x-hw-label": "", "x-hw-visibility": "none", "format": "input", "x-hw-format": "input", "x-hw-select-options": [] } } }, "required": [ "str", "obj", "arr" ], "type": "object" } ``` - JSON ``` { "str": "string", "obj": { "obj_str1": "string", "obj_str2": "string" }, "arr": [ "string", "string" ] } ``` - XML ``` string string string string string string ``` #### 更多操作 工具创建完成后，您可以执行如[表7]的操作。 表7相关操作 | 操作 | 说明 | |:---|:---| | 设置工具鉴权 | 在工具列表中单击操作列的"设置鉴权"，设置鉴权信息，单击"保存"。只有经过身份验证和授权的用户才能使用工具。 | | 创建执行动作 | 在工具列表中单击工具名称，在工具详情页面创建执行动作，具体操作请参见[创建执行动作]。 | | 下载工具 | 在工具列表中选择操作列的"更多 \> 下载"，下载工具的.json格式文件。 | | 导入更新工具 | 在工具列表中选择操作列的"更多 \> 导入更新"，以导入.json格式API文件的方式更新工具。 | | 编辑工具 | 1. 在工具列表中，单击操作列的"修改"，支持编辑工具的名称、描述、图标、协议、主机地址、基准URL以及验证方式。 2. 单击"更新"。 | | 删除工具 | 工具删除后无法恢复，请谨慎操作。 1. 在工具列表中，选择操作列的"更多 \> 删除"。 2. 在弹出的提示框中单击"确认"。 | | 编辑工具的执行动作 | 在工具列表中单击![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002048491884.png)，展开执行动作列表，单击执行动作列表操作列的"编辑"。 | | 测试执行动作 | 在工具列表中单击![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002084569377.png)，展开执行动作列表，单击执行动作列表操作列的"测试"。 | | 删除执行动作 | 在工具列表中单击![](https://support.huaweicloud.com/usermanual-wiseagent/zh-cn_image_0000002048650176.png)，展开执行动作列表，单击执行动作列表操作列的"删除"。 | #### 相关文档 - 工具创建完成后，可在Agent、工作流中调用或通过API调用，请参考[在AI原生应用引擎中创建单Agent（自主规划模式）](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0597.html)、[创建工作流](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0846.html)以及[调用工具的执行动作](https://support.huaweicloud.com/api-appstage/OpenExecuteSkill.html)。 - 工具相关的OpenAPI请参见[应用中心](https://support.huaweicloud.com/api-appstage/topic_300000001.html)。 - [工具的输入参数支持图片格式吗](https://support.huaweicloud.com/appstage_faq/appstage_05_0259.html)。 - [用户如何将自己的接口接入AI原生应用引擎并通过Agent调用](https://support.huaweicloud.com/appstage_faq/appstage_05_0255.html)。