创建工具

前提条件

• 需要具备AI原生应用引擎管理员或开发者权限，权限申请操作请参考AppStage组织成员申请权限。
• 已获取API服务的连接信息以及调用API所需的访问权限和密钥。

创建工具

将选定的API服务注册为一个工具。

1. 进入AI原生应用引擎。
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。 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请求消息的组成部分之一，请求头负责通知服务器有关于客户端请求的信息。 单击参数列表“操作”列的可以新增参数，参数配置说明请参见表4。 请求体（Body）：HTTP请求消息的组成部分之一，请求体呈现发送给服务器的数据。 JSON/XML：JSON、XML格式的数据。 如果请求体使用XML格式，XML header参数必须配置。 导入：可直接粘贴被调用API的JSON、JSON Schema或XML数据，减少逐个配置参数的工作量。导入文件示例请参见JSON Schema/JSON/XML文件示例。 复制：复制请求体参数的JSON或XML数据。 预览：可以预览参数的JSON或XML结构。 参数列表“操作”列的：可选择是否开启“是否支持根节点输入”参数，开启并发布对应工具后，在创建流中添加该执行动作时可以自定义请求体参数的值。 参数列表“操作”列的：新增参数，参数配置说明请参见表4。 form-data：表单数据，用于网页表单提交（含文件上传）、多类型数据混合传输（如文本 + 图片）。 参数列表“操作”列的：新增参数，参数配置说明请参见表4。 Binary：直接传输非文本数据（如图片、视频、音频、可执行文件等），不进行结构化解析，以原始字节流形式发送。 输入、输出仅支持配置一处。例如，输出入参数选择了“Binary”，则输出不显示，反之亦成立。 查询参数（Query）：查询参数会追加到URL。例如，在 /items?id=#### 中，查询参数为ID。 单击参数列表“操作”列的可以新增参数，参数配置说明请参见表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类型参数。
   说明	关于输入值的介绍说明。
   操作	单击：配置参数在界面的显示样式。配置完成并发布对应工具后，在创建流中添加该执行动作时可以查看参数的界面显示效果。 参数类型：选择参数类型。 格式：设置用户输入该参数时界面显示的样式，可选择文本框、日期时间、富文本、下拉列表。不同的参数类型可选择的格式不同。 当格式选择为下拉列表时，需设置标签和下拉列表的值。单击“新增”可进行添加。 设置完成后，如果勾选了“支持多选”，则可在创建流中添加该执行动作时选择多个值，否则，只能选择一个值。需要配置分隔符，分隔符只能输入单个特殊字符，如“,”“$”、“%”、“^”、“&”等，不设置时，默认为“,”。 可见性：设置用户输入该参数时界面显示的可见性。 无：在流中正常显示。 高级：默认隐藏在高级设置菜单里。 隐藏：该参数向用户隐藏。 重要：优先显示在表单的最开始。 默认值：当格式选择为文本框、日期时间、富文本时，支持设置该参数的预设值。 单击：新增节点。 单击：删除该节点。

3. 单击“下一步”，配置输出参数，参数如表2所示。

   表5 输出参数说明

   参数	说明
   添加响应	单击“添加响应”，根据被调用API的响应码信息添加响应码。
   输出参数	配置输出参数，如被调用API没有响应参数可不填。 响应体：HTTP响应消息的组成部分之一，响应体呈现发送给服务器的数据。 JSON/XML：JSON、XML格式的数据。 参数列表“操作”列的：新增参数，参数配置说明请参见表4。 当选择XML格式时，单击参数列表“操作”列的，配置XML标签名。 导入：可直接粘贴被调用API的JSON Schema、JSON或XML数据，减少逐个配置参数的工作量。导入文件示例请参见JSON Schema/JSON/XML文件示例。 复制：复制请求体参数的JSON或XML数据。 预览：可以预览参数的JSON或XML结构。 Binary：文件格式数据。输入、输出仅支持配置一处。例如，输出入参数选择了“Binary”，则输出不显示，反之亦成立。 响应头：HTTP响应消息的组成部分之一，响应头负责通知服务器有关于客户端请求的信息。 单击参数列表“操作”列的可以新增参数，参数配置说明请参见表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

  <root>
  	<str>string</str>
  	<arr>string</arr>
  	<arr>string</arr>
  	<arr>string</arr>
  	<obj>
  		<obj_str1>string</obj_str1>
  		<obj_str2>string</obj_str2>
  	</obj>
  </root>

更多操作

工具创建完成后，您可以执行如表7的操作。

相关文档

• 工具创建完成后，可在Agent、工作流中调用或通过API调用，请参考在AI原生应用引擎中创建单Agent（自主规划模式）、创建工作流以及调用工具的执行动作。
• 工具相关的OpenAPI请参见应用中心。
• 工具的输入参数支持图片格式吗。
• 用户如何将自己的接口接入AI原生应用引擎并通过Agent调用。