创建工具

前提条件

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

创建工具

1. 在AI原生应用引擎的左侧导航栏选择“Agent编排中心 > 我的工具”，单击“创建工具”。
2. 在“创建工具”页面，配置如表1所示参数。

   表1 工具参数配置说明

   参数名称	参数说明
   名称	自定义工具名称。名称长度不能超过32个字符，可包含中文、大小写字母、数字、下划线、中划线、英文小括号，不能以下划线、中划线、英文小括号开头。
   描述	填写工具功能或作用等描述。
   图标	支持选择系统图标。
   协议	API服务接口通信协议。 https http
   主机地址	提供API服务的服务器地址。以https://aiae.appstage.myhuaweicloud.com/v1/chat/completions为例，主机地址为aiae.appstage.myhuaweicloud.com。
   基准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。 自定义：自定义用户在创建连接时的身份验证方式。 无验证：用户不需要任何身份验证即可创建与连接器的连接。无验证时，任何用户都可以使用您的连接器。

3. 配置完单击“创建”。

   工具创建成功后，进入工具详情页面，请参考创建执行动作添加执行动作。

创建执行动作

1. 在工具详情页面，单击“创建执行动作”，配置执行动作基础信息，参数如表2所示。

   表2 执行动作基本信息参数说明

   参数	说明
   名称	执行动作是需要完成的特定任务，自定义执行动作的名称，比如，“发送电子邮件”。“更新行”。 长度不能超过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格式的数据。 参数列表“操作”列的：可选择是否开启“是否支持根节点输入”参数，开启并发布对应工具后，在创建流中添加该执行动作时可以自定义请求体参数的值。 参数列表“操作”列的：新增参数，参数配置说明请参见表4。 导入：可直接粘贴被调用API的JSON、JSON Schema或XML数据，减少逐个配置参数的工作量。导入文件示例请参见JSON Schema/JSON/XML文件示例。 如果请求体使用XML格式，XML header参数必须配置。 复制：复制请求体参数的JSON或XML数据。 预览：可以预览参数的JSON或XML结构。 form-data：文件格式数据。 参数列表“操作”列的：新增参数，参数配置说明请参见表4。 Binary：文件格式数据。输入、输出仅支持配置一处。例如，输出入参数选择了“Binary”，则输出不显示，反之亦成立。 查询参数（Query）：查询参数会追加到URL。例如，在 /items?id=#### 中，查询参数为ID。 单击参数列表“操作”列的可以新增参数，参数配置说明请参见表4。 路径参数（Path）：路径与路径模板一起使用，其中参数值实际上是操作URL的一部分。

   表4 参数配置说明

   参数	说明
   参数名称	输入参数的名称。
   显示字段	用户在表单中看到的参数项标签。
   必填	勾选该参数是否是用户必填项。
   参数类型	选择参数类型，支持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文件示例。 如果响应体使用XML格式，XML header参数必须配置。 复制：复制请求体参数的JSON或XML数据。 预览：可以预览参数的JSON或XML结构。 Binary：文件格式数据。输入、输出仅支持配置一处。例如，输出入参数选择了“Binary”，则输出不显示，反之亦成立。 响应头：HTTP响应消息的组成部分之一，响应头负责通知服务器有关于客户端请求的信息。 单击参数列表“操作”列的可以新增参数，参数配置说明请参见表4。

4. 单击“下一步”，调试校验工具，验证工具是否可用。
   1. 配置用例设置参数，参数说明如表6所示。配置完成后，单击“提交测试”。

      表6 配置用例设置参数说明

      参数	说明
      实例	选择已创建好的实例。 也支持新建实例，单击“新建实例”，配置实例名称、描述及验证信息，验证信息填写工具创建时所配置的鉴权信息，单击“保存”。 验证信息与步骤3所选的验证方式相关，如果验证方式为“无验证”，则无需配置实例。
      定义参数	配置输入参数。

   2. 在测试结果预览区域，查看测试结果。

5. 工具调试完成后，单击“保存”。

   新创建的工具显示在“我的工具”列表中，任务状态为“待上架”，请参考表1上架工具。

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的操作。