基于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个工具。
• 文件上传大小：当请求体的数据格式是form-data时，限制如下：
  • 图片文件： 单个文件大小不得超过5mb。
  • 其他文件： 单个文件大小不得超过128mb。

步骤1：创建插件

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

• 示例讲解使用“文字识别服务 > 通用文字识别api”，请提前在开通该api。
• 本示例使用的华为云文字识别服务属于收费服务，调用该接口将产生ocr接口费用，具体请参考文字识别服务。

1. 登录。
2. 在左侧导航栏中选择“开发中心 > 组件库”，在“插件”页签，单击页面右上角“创建插件”。
3. 在“创建插件”页面中，根据以下步骤配置插件信息。
   图1 创建插件
   

   表1 基础信息

   参数	说明	示例
   openapi导入	为了简化插件配置流程，可以使用此功能导入符合openapi3.0规范的json文件。平台将自动解析文件内容并填充相应的配置参数，从而避免繁琐的手动录入，提高配置效率。 注意： 鉴权信息：平台目前无法自动解析鉴权配置，导入后需要手动添加鉴权信息，否则工具调用时将因鉴权缺失而请求失败。 规范检查：配置文件导入并解析为工具后，建议逐一检查每个工具的请求参数和响应参数是否已正确解析。 仅支持导入get和post请求方式的接口。	本示例使用手动创建，不使用自动解析功能。 其他示例代码请参考openapi 3.0 配置文件示例说明。
   名称	用于标识当前插件，在“组件库 > 插件”页面会展示该名称。 命名规则：按照插件的实际功能命名，有助于agent进行插件的精准识别和调度。 命名要求：可以包含中文、英文、数字、下划线。 长度限制：2~64个字符。	文字识别
   描述	描述当前插件的类型、功能和适用场景。 需要按照插件的实际功能填写描述，有助于agent进行插件的精准识别和调度。	提供通用文字识别能力，可以对图片中的文字精准提取与解析，输出结构化文本结果，适配各类场景文字识别需求。
   插件图标	系统默认提供插件图标。输入名称和描述后，单击可以自动生成头像。用户也可以自定义图标，自定义图标步骤如下： 鼠标移动至系统默认图标上，单击鼠标左键。 上传已准备好的应用图标。 支持png、jpeg、gif、jpg格式图片，且图片大小不大于200kb。	系统默认图标
   仅我可见	开启后，该插件将变为私有，仅对当前登录用户可见，其他用户无法查看。 创建后该开关不再支持修改。	不开启

   表2 配置信息

   参数	说明	示例
   插件url	调用插件的url地址。包含协议，服务域名和基准url（可选）。 协议：api服务接口通信协议。 服务域名：提供api服务的服务域名。 基准url：是指域名的根路径（可理解为api的公共路径），默认为/，请根据实际api接口进行适配。	https://ocr.cn-southwest-2.myhuaweicloud.com/v2/{project_id}/ocr 注意需要单击右侧的按钮添加{project_id}变量。该变量表示项目id，用于标识用户在华为云特定区域下的资源归属。
   鉴权方式	选择调用api时是否需要鉴权。 无需鉴权：api可以公开访问，不需要任何形式的身份认证或授权。 api key：在调用api时提供一个唯一的api key进行鉴权。需配置以下信息：需填写密钥位置、密钥参数名称和取值。智能体在发起请求时，会自动把这个api key添加到请求的header（请求头）或query（url参数）中。 密钥位置：密钥是从header中读取还是从query中读取。 参数名称：api key的鉴权参数名称。 参数值：api key的具体值。 华为云认证：华为云iam认证，通过iam账号获取用户token进行认证。 iam认证url：获取iam用户token信息的接口。例如，https://{iam_host}/v3/auth/tokens。 账号名：iam用户所属账号信息，即账号名。 项目：该服务所属区域信息。例如，cn-southwest-2。 验证方式 iam用户名/密码（适用于临时测试、快速验证接口连通性或开发调试阶段） iam用户名：iam用户名称。 iam用户密码：iam用户的登录密码。 access key id/secret access key（适用于生产环境、自动化脚本调用或对长期稳定性要求较高的场景） access key id：访问密钥id。 secret access key：与访问密钥id结合使用的密钥。 关于密钥加密：当校验方式选择api key或华为云认证时，鼠标移动至“参数列表”或“验证方式”右侧的上，可查看密钥的加密方式。平台默认使用kms加密 默认密钥方式对认证密钥进行加密存储，防止信息泄露。 加密机制：使用用户选择的密钥派生dek进行加密，默认密钥为kms-agentarts/default。 费用说明：实例不收费，每月提供20,000次免费调用额度。解密时支持缓存，但敏感数据较多时可能超出免费次数。如需更换加密方式，具体请参考更换密钥的加密方式。超出后按实际调用次数计费，详见。	华为云文字识别服务采用“华为云认证”。 iam认证url：https://iam.cn-southwest-2.myhuaweicloud.com/v3/auth/tokens 项目：cn-southwest-2 验证方式：iam用户名/密码 账号名、iam用户名、iam用户密码：账号名、iam用户名请登录页面查询，密码按实际填入。 图2 查询账号名、iam用户名 图3 配置示例

4. 单击“下一步 创建工具”，进入工具创建页面，或单击“完成插件创建”。如果选择后者，后续可继续在插件详情中添加工具。请参考步骤2：创建工具为插件添加工具。

步骤2：创建工具

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

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

   表3 工具配置信息

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

   表4 参数配置说明

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

2. 配置完单击“完成”，工具创建完成后会跳转至插件详情页面。
3. 在工具列表中，单击“调试”按钮，输入问题后，单击“开始调试”。

   必须连通公网，才能获取示例中的{project_id}的值。

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

   文字识别插件如果返回401或403报错，请检查“权限校验”配置中的token或密钥是否正确。

   图7 获取文字识别插件项目id
   
4. 工具调试完成后，单击“确定”。

   调试成功后，工具状态随之变为“成功”，此时可单击右上角“发布”，发布插件。

相关操作

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

附录

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

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

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

• curl

  curl --location --request post 'https://iam.cn-southwest-2.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-southwest-2"
              } 
          } 
      } 
  }'

• python

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

openapi 3.0 配置文件示例说明

openapi 3.0 简介

openapi 3.0（前身为swagger）是一种用于描述restful api的标准规范格式。它以结构化的方式定义api的请求路径、参数、请求体、响应结构等信息，使得机器和人类都能快速理解api的能力与使用方式。

一个标准的openapi 3.0文档通常包含以下核心模块：

平台在创建agent插件时，会解析导入的openapi 3.0配置文件：

• info.title： 将作为插件名称。
• info.description：将作为插件描述。
• paths：下的每个接口将被解析为插件中的一个工具（tool）。

示例：

本示例提供了一个符合openapi 3.0规范的“用户管理 api”配置文件，旨在演示如何通过编写标准化的openapi 3.0规范的文件来定义agent插件。

通过详细解析文件结构（包括基本信息、服务器地址、接口路径）及具体的接口操作（如查询用户列表、创建新用户），本示例帮助用户理解openapi字段与平台插件配置项（如插件名称、工具定义、参数约束）之间的映射关系。您可以参考此示例，学习如何正确编写配置文件，以便将现有的restful api快速导入平台并解析为可用的工具。

openapi: 3.0.1
info:
  title: 用户管理 api
  description: 这是一个简单的用户管理 api 示例
  version: 1.0.0
servers:
  - url: https: //api.example.com/v1
    description: 生产服务器
paths:
  /users:
    get:
      summary: 获取用户列表
      description: 返回系统中的用户列表，支持分页和过滤
      operationid: getusers
      parameters:
        - name: page
          in: query
          description: 页码
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: 每页数量
          schema:
            type: integer
            default: 20
        - name: role
          in: query
          description: 按角色过滤
          schema:
            type: string
            enum: [admin, user, guest]
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: 用户总数
                  page:
                    type: integer
                    description: 当前页码
                  limit:
                    type: integer
                    description: 每页数量
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: 用户id
                        username:
                          type: string
                          description: 用户名
                        email:
                          type: string
                          format: email
                          description: 电子邮箱
                        role:
                          type: string
                          enum: [admin, user, guest]
                          description: 用户角色
                        createdat:
                          type: string
                          format: date-time
                          description: 创建时间
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 错误码
                  message:
                    type: string
                    description: 错误信息
        default:
          description: 服务器错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 错误码
                  message:
                    type: string
                    description: 错误信息
    post:
      summary: 创建新用户
      description: 创建一个新的用户账户
      operationid: createuser
      requestbody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - email
                - password
              properties:
                username:
                  type: string
                  minlength: 3
                  maxlength: 20
                  description: 用户名
                email:
                  type: string
                  format: email
                  description: 电子邮箱
                password:
                  type: string
                  minlength: 6
                  format: password
                  description: 密码
                role:
                  type: string
                  enum: [user, guest]
                  default: user
                  description: 用户角色
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: 用户id
                  username:
                    type: string
                    description: 用户名
                  email:
                    type: string
                    format: email
                    description: 电子邮箱
                  role:
                    type: string
                    enum: [admin, user, guest]
                    description: 用户角色
                  createdat:
                    type: string
                    format: date-time
                    description: 创建时间
        '400':
          description: 请求数据验证失败
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 错误码
                  message:
                    type: string
                    description: 错误信息
                  errors:
                    type: array
                    description: 详细错误列表
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          description: 错误字段
                        message:
                          type: string
                          description: 错误信息
        '409':
          description: 用户已存在
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 错误码
                  message:
                    type: string
                    description: 错误信息
        default:
          description: 服务器错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 错误码
                  message:
                    type: string
                    description: 错误信息