基于api创建插件-j9九游会登录

前提条件

• 已开通agentarts服务。
• 登录用户为空间所有者、空间管理员、开发工程师，详细信息请参考管理团队空间成员。

api形态插件

api类型插件是将现有的restful api（http/https 接口）封装为agent可调用的工具。他不承载业务逻辑，而是将大模型的自然语言指令“翻译”为标准的api请求，发送给外部系统。

典型适用场景：

• 数据检索：如天气查询、网络搜索、新闻查询。
• 状态变更：如发送信息、触发创建任务。
• 复杂业务逻辑处理：售后退换货处理（api后台校验商品是否满足退货条件、换货库存是否充足、生成退订链接、发送通知消息……）。

不适用场景：纯逻辑计算（简单数值计算）、简单的字符串处理（延迟高且浪费网络资源）。

插件调用链路：

1. 用户输入：帮我查一下订单12345的状态。
2. agent分析：命中插件get_order_status。
3. 参数生成：agent中模型生成结构化参数 { "order_id": "12345" }。
4. 请求构建：agent组装api插件请求。
5. 网络交互：agent向api服务器发起get /api/orders/12345请求。
6. 响应解析：服务器返回 json 数据，agent将其清洗后注入模型上下文。
7. 最终回复：模型根据数据生成自然语言：“订单12345当前状态为已发货...”。

约束限制

• 单个插件最多支持添加30个工具。

步骤1：创建插件

创建插件过程中，将结合“使用文字识别api创建插件”作为示例进行讲解，文字识别api、插件与工具说明请参考插件介绍。

示例讲解使用“文字识别服务 > 通用文字识别api”，请提前在开通该api。

1. 登录，在左侧导航栏“个人空间”区域，选择目标空间。
2. 在左侧导航栏中选择“开发中心 > 组件库”，在“插件”页签，单击页面右上角“创建插件”。
   图1 创建插件
   
3. 在“创建插件”页面中的“插件类型”中选择“api类型”，然后根据以下步骤配置插件信息。

   表1 基本信息

   参数	说明	示例
   插件类型	根据实现机制与运行形态的不同，插件分为“api类型”和“函数类型”两种形态。	api类型
   插件图标	单击默认图标按钮，可上传本地图片作为插件的自定义图标。 支持jpg、jpeg、png格式，不超过200kb。	系统默认图标
   展示名称	用于标识当前插件，在“组件库 > 插件”页面会展示该名称。 命名规则：按照插件的实际功能命名，有助于agent进行插件的精准识别和调度。 命名要求：可以包含中文、英文、数字、特殊字符等； 长度限制：1~64个字符。	文字识别
   名称	插件的英文名称。 命名规则：按照插件的实际功能命名，有助于agent进行插件的精准识别和调度。 命名要求：字母、数字和下划线（_）的组合，不允许使用其他特殊字符或空格； 长度限制：1~64个字符。	textrecognitionplugin
   描述	描述当前插件的类型、功能和适用场景。 需要按照插件的实际功能填写描述，有助于agent进行插件的精准识别和调度。	提供通用文字识别能力，可以对图片中的文字精准提取与解析，输出结构化文本结果，适配各类场景文字识别需求。

4. 单击“下一步”，在“配置信息”步骤中配置插件信息，请参照表2完成配置。

   表2 配置信息

   参数	说明	示例
   协议	api服务接口通信协议。 https http	https
   服务域名	提供api服务的服务域名。 单击右侧的按钮，在服务域名中添加变量。添加变量后，可以在变量参数部分设置参数的描述。 以华为云通用文字识别api为例https://{endpoint}/v2/{project_id}/ocr/general-text，该api中{endpoint}即表示服务域名。 文字识别服务在“华北-北京四”区域的“endpoint”为“ocr.cn-north-4.myhuaweicloud.com”	ocr.cn-north-4.myhuaweicloud.com
   基准url	基准url（base url）是指域名的根路径（可理解为api的公共路径），默认为/，请根据实际api接口进行适配。 例如，华为云文字识别服务，中不同api接口都有相同的基准url：/v2/{project_id}/ocr	/v2/{project_id}/ocr 注意需要单击右侧的按钮添加{project_id}变量。该变量表示项目id，用于标识用户在华为云特定区域下的资源归属。 图2 配置示例
   权限校验	选择调用api时是否需要鉴权。 无需鉴权：api可以公开访问，不需要任何形式的身份验证或授权。 api key：在调用api时提供一个唯一的api key进行鉴权。需配置以下信息 需填写密钥位置、密钥参数名称和取值。agent在发起请求时，会自动把这个api key塞到请求的 header（请求头） 或 query（url参数） 中 密钥位置：密钥是从header中读取还是从query中读取。 参数名称：api key的鉴权参数名称。 参数值：api key的具体值。 开通配置：设置在使用插件时，是否需要手动填写api key。 无需手动开通：填写的api key值将作为预置信息。 手动创建：填写的api key值将作为插件后续调试使用，在agent正式使用插件时，需要填写新的api key值。 华为云认证：华为云iam认证，通过iam账号获取用户token进行认证。 iam认证url：获取iam用户token信息的接口。例如，https://{iam_host}/v3/auth/tokens。 账号名：iam用户所属账号信息，即账号名。 项目：该服务所属区域信息。例如，cn-north-4。 验证方式 iam用户名/密码 iam用户名：iam用户名称。 iam用户密码：iam用户的登录密码。 access key id/secret access key access key id：访问密钥id。 secret access key：与访问密钥id结合使用的密钥。	华为云文字识别服务采用“华为云认证”。 iam认证url：https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens 项目：cn-north-4 验证方式：iam用户名/密码 账号名、iam用户名、iam用户密码：账号名、iam用户名请登录页面查询，密码按实际填入。 图3 查询账号名、iam用户名 图4 配置示例

5. 配置完单击“确定”。平台会自动跳转至工具信息页面，请参考步骤2：创建工具为插件添加工具。

步骤2：创建工具

如需了解插件与工具的关系，请参考插件介绍。

1. 在“工具信息”页面，单击“创建工具”，请参照表3进行配置。

   表3 工具基础信息配置

   参数	说明	示例
   展示名称	用于标识当前工具。 命名规则：按照工具的实际功能命名，有助于agent进行插件的精准识别和调度。	通用文字识别
   名称	工具的英文名称。 命名规则：按照工具的实际功能命名，有助于agent进行插件的精准识别和调度。 命名要求：可以包含大小写字母、数字、下划线。 长度限制：1~64个字符。	recognizegeneraltext
   描述	描述当前工具的类型、功能和适用场景。 需要按照工具的实际功能填写描述，有助于agent进行插件的精准识别和调度。	识别图片上的文字信息，以json格式返回识别的文字和坐标。

2. 参考下表，继续完成工具url、请求参数、相应参数等信息的配置。

   表4 工具配置

   参数		说明	示例
   导入并解析	-	ai自动解析api请求参数，需填入api的curl或openapi的原始内容。	本示例使用手动创建，不适用自动解析功能。
   工具url	请求方式	api的请求方式，支持post或get。	post
   	工具path	工具path是api完整调用地址中，用于定位具体功能的后缀片段。	/general-text
   请求参数	参数封装	满足某些接口强制要求入参为数组的规定，将对象类型 (object)参数变为数组 (array) ，也就是将入参放到一对中括号 [] 中。 原参数列表：{"a":"string", "b":1}。 开启后：[{"a":"string", "b":1}]。	不启用
   	请求头(header)	http请求消息的组成部分之一，请求头负责通知服务器有关于客户端请求的信息。 单击参数列表右侧的“添加参数”可以新增参数，参数配置说明请参见表5。	新增两个请求头参数，并设置为必选： x-auth-token：获取代码请参考附录。 content-type：取值为application/json 图5 配置示例
   	请求体(body)	http请求消息的组成部分之一，请求体呈现发送给服务器的数据。 单击参数列表右侧的“添加参数”可以新增参数，参数配置说明请参见表5。	文字识别支持2种请求方式，使用图片的url，或者图片的base64编码。 此处使用url，并设置为必选，使用base64编码需要填写为image。 图6 配置示例
   	查询参数(query)	http请求消息的组成部分之一，用于向服务器传递额外的参数信息。这些参数通常以键值对的形式出现，并且附在url的路径后面，通过?分隔。 例如，在 /items?id=123 中，查询参数为id，值为123。 单击参数列表右侧的“添加参数”可以新增参数，参数配置说明请参见表5。	文字识别插件不涉及
   	路径参数(path)	自动解析工具path中包含的路径参数。工具path中支持可变参数配置。 例如：/weather/weatherinfo{path_1}/{path_2}。	文字识别插件不涉及
   响应参数	流式响应	当插件调用的是一个带有思考效果的模型（如deepseek）或者耗时较长的接口，开启这个功能可以让api将获取的响应随时吐出，而不是等api完全获取结果后再一次性显示出来。	不启用
   	参数封装	满足后续插件使用过程中（如工作流的循环节点批量读取数组）要求输入为数组的规定，将对象类型 (object) 响应变为数组 (array)，也就是将出参放到一对中括号 [] 中。 原参数列表：{"a":"string", "b":1}。 开启后：[{"a":"string", "b":1}]。	不启用
   	参数列表	响应参数清单，按照api实际的响应参数结构进行填写。	增加一个响应参数，名称为result，并设置为必选。 图7 配置示例

   表5 参数配置说明

   参数	说明
   参数名称	设置请求参数的名称，参数名称会作为大模型解析参数含义的依据。 命名规则：仅支持字母、数字、下划线或短横线。 说明： 单击参数列表右侧的“添加参数”按钮，可以添加请求参数。 单击右侧的，可以删除添加的请求参数。
   中文名称	设置参数的中文名称，便于用户理解参数含义。
   参数类型	设置请求参数的数据类型。 注意： 请求头（header）中，所有参数的值必须是字符串类型，不能设置其他类型。
   默认值	设置参数的默认值，当参数未提供时使用该值。
   描述	设置请求参数的详细描述信息，准确说明参数的含义、用途和格式要求，以提高大模型对参数识别和提取的准确性。
   参数校验	设置当前参数是否需要进行校验。 校验规则： 参数名称：需要校验的参数名称。 校验类型： 字符最大长度 枚举值 时间日期 校验规则：可设置指定格式和自定义格式。 指定格式：选择系统预置的标准校验规则。当校验类型为时间日期时，支持指定格式。 自定义格式：根据实际需求自定义校验规则。
   必填	设置该参数是否为必填项。

3. 单击“工具调测”按钮，输入参数值，单击“开始调测”检查调测结果。

   对于文字识别插件示例，由于在创建插件的基准url过程中，将{project_id}设置为变量，因此要填充该值。请登录页面查询“华北-北京四”区域对应的项目id。

   图8 获取文字识别插件项目id
   
   图9 工具调测
   
4. 确保输出符合预期，再单击工具调测页面右下角的“自动解析”按钮，系统将自动生成响应参数。
5. 工具调试完成后，单击“确定”。

   工具创建完成后，可以在工具列表中查看创建完成的工具。

相关操作

工具创建完成后，您可以在工具列表中查看每个工具的调试状态、智能体引用数和工作流引用数。您可以执行如表6的操作。

附录

创建文字识别插件使用，token获取方法：

代码中账号名、iam用户名、iam用户密码：账号名、iam用户名请登录页面查询，密码按实际填入。

图10 查询账号名、iam用户名

• curl

  curl --location --request post 'https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens' \
  --header 'content-type: application/json' \
  --data-raw '{ 
      "auth": { 
          "identity": { 
              "methods": [ 
                  "password" 
              ], 
              "password": { 
                  "user": { 
                      "name": "iam用户名",
                      "password": "密码",
                      "domain": { 
                          "name": "账号名"
                      } 
                  } 
              } 
          }, 
          "scope": { 
              "project": { 
                  "name": "cn-north-4"
              } 
          } 
      } 
  }'

• python

  import requests
  import json
  url = "https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens"
  payload = json.dumps({
    "auth": {
      "identity": {
        "methods": [
          "password"
        ],
        "password": {
          "user": {
            "name": "iam用户名",
            "password": "密码",
            "domain": {
              "name": "账号名"
            }
          }
        }
      },
      "scope": {
        "project": {
          "name": "cn-north-4"
        }
      }
    }
  })
  headers = {
    'content-type': 'application/json'
  }
  response = requests.request("post", url, headers=headers, data=payload)
  print(response.headers["x-subject-token"])