# 基于API创建插件 在AgentArts智能体平台中，当官方预置插件无法满足特定业务需求时，开发者需要自主创建插件。 #### 前提条件 已[开通AgentArts服务](https://support.huaweicloud.com/qs-agentarts/agentarts_04_0000.html)。 #### 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、插件与工具说明请参考[插件介绍](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0123.html)。 ![](https://support.huaweicloud.com/lowcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 示例讲解使用"文字识别服务 \> 通用文字识别API"，请提前在[文字识别服务控制台](https://console.huaweicloud.com/ocr)开通该API。 - 本示例使用的华为云文字识别服务属于收费服务，调用该接口将产生OCR接口费用，具体请参考文字识别服务[计费详情](https://support.huaweicloud.com/price-ocr/ocr_12_0006.html)。 1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏中选择"开发中心 \> 组件库"，在"插件"页签，单击页面右上角"创建插件"。 3. 在"创建插件"页面中，根据以下步骤配置插件信息。 图1创建插件 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790620.png "点击放大") 表1基础信息 | 参数 | 说明 | 示例 | |:---|:---|:---| | OpenAPI导入 | 为了简化插件配置流程，可以使用此功能导入符合OpenAPI 3.0规范的JSON文件。平台将自动解析文件内容并填充相应的配置参数，从而避免繁琐的手动录入，提高配置效率。 注意： - **鉴权信息** ：**平台目前无法自动解析鉴权配置**，导入后需要手动添加鉴权信息，否则工具调用时将因鉴权缺失而请求失败。 - **规范检查** ：配置文件导入并解析为工具后，**建议逐一检查每个工具的请求参数和响应参数是否已正确解析**。 - 仅支持导入GET和POST请求方式的接口。 | 本示例使用手动创建，不使用自动解析功能。 其他示例代码请参考[OpenAPI 3.0 配置文件示例说明]。 | | 名称 | 用于标识当前插件，在"组件库 \> 插件"页面会展示该名称。 命名规则：按照插件的实际功能命名，有助于Agent进行插件的精准识别和调度。 命名要求：可以包含中文、英文、数字、下划线。 长度限制：2\~64个字符。 | 文字识别 | | 描述 | 描述当前插件的类型、功能和适用场景。 需要按照插件的实际功能填写描述，有助于Agent进行插件的精准识别和调度。 | 提供通用文字识别能力，可以对图片中的文字精准提取与解析，输出结构化文本结果，适配各类场景文字识别需求。 | | 插件图标 | 系统默认提供插件图标。输入名称和描述后，单击![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717550111.png "点击放大")可以自动生成图标。用户也可以自定义图标，步骤如下： 1. 将鼠标移动至系统默认图标上，单击鼠标左键。 2. 上传已准备好的应用图标。 支持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 注意需要单击右侧的![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687950478.png)按钮添加{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_host}表示IAM Endpoint地址，即承载REST服务端点的服务器域名或IP。由于不同服务在不同区域的Endpoint各不相同，详情请参见[终端节点](https://support.huaweicloud.com/api-iam/iam_01_0001.html#section2)。 例如： 您需要获取"西南-贵阳一"区域的Token，则需使用"西南-贵阳一"区域的Endpoint（iam.cn-southwest-2.myhuaweicloud.com），并结合[获取IAM用户Token（使用密码）](https://support.huaweicloud.com/api-iam/iam_30_0001.html)API的资源路径（/v3/auth/tokens），拼接后的完整请求地址如下。 ``` https://iam.cn-southwest-2.myhuaweicloud.com/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或华为云认证时，鼠标移动至"参数列表"或"验证方式"右侧的![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717390239.png)上，可查看密钥的加密方式。平台默认使用**KMS加密+默认密钥** 方式对认证密钥进行加密存储，防止信息泄露。 - 加密机制：使用用户选择的密钥派生DEK进行加密，默认密钥为kms-agentarts/default。 - 费用说明：实例不收费，每月提供20,000次免费调用额度。解密时支持缓存，但敏感数据较多时可能超出免费次数。如需更换加密方式，具体请参考[更换密钥的加密方式](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0288.html)。超出后按实际调用次数计费，详见[密码安全中心计费说明](https://support.huaweicloud.com/price-dew/dew_03_0001.html)。 | 华为云文字识别服务采用"华为云认证"。 IAM认证url：https://iam.cn-southwest-2.myhuaweicloud.com/v3/auth/tokens 项目：cn-southwest-2 验证方式：IAM用户名/密码 账号名、IAM用户名、IAM用户密码：账号名、IAM用户名请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询，密码按实际填入。 图2查询账号名、IAM用户名 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687950476.png "点击放大") 图3配置示例 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717550115.png "点击放大") | 4. 单击"下一步 创建工具"，进入工具创建页面，或单击"完成插件创建"。如果选择后者，后续可继续在插件详情中添加工具。请参考[步骤2：创建工具]为插件添加工具。 #### 步骤2：创建工具 如需了解插件与工具的关系，请参考[插件介绍](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0123.html)。 1. 在"工具信息"页面，单击"创建工具"，请参照[表3]进行配置。 表3工具配置信息 | 参数 || 说明 | 示例 | |:---|---|:---|:---| | 名称 || 用于标识当前工具。 命名规则：按照工具的实际功能命名，有助于Agent进行插件的精准识别和调度。 | 通用文字识别 | | 描述 || 描述当前工具的类型、功能和适用场景。 需要按照工具的实际功能填写描述，有助于Agent进行插件的精准识别和调度。 | 识别图片上的文字信息，以JSON格式返回识别的文字和坐标。 | | 工具path || 工具path是API完整调用地址中，用于定位具体功能的后缀片段。 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790622.png "点击放大") ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717550117.png "点击放大") | /general-text 图4配置示例 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717390233.png "点击放大") | | 请求方式 || 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配置示例 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687950480.png "点击放大") | | 请求参数 | 查询参数(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配置示例 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790624.png "点击放大") | | 响应参数 | 流式响应 | 当插件调用的是一个带有思考效果的模型（如DeepSeek）或者耗时较长的接口，开启这个功能可以让API逐步（流式）返回响应结果，而不是等API完全获取结果后再一次性显示出来。 | 不启用 | | 响应参数 | 参数封装 | 满足后续插件使用过程中（如工作流的循环节点批量读取数组）要求输入为数组的规定，将对象类型(Object)响应变为数组(Array)，也就是将出参放到一对中括号\[\]中。 - 原参数列表：{"a":"string", "b":1}。 - 开启后：\[{"a":"string", "b":1}\]。 | 不启用 | 表4参数配置说明 | 参数 | 说明 | |:---|:---| | 参数名称 | 设置请求参数的名称，参数名称会作为大模型解析参数含义的依据。 命名规则：仅支持字母、数字、下划线或短横线。 说明： - 单击参数列表右侧的"添加参数"按钮，可以添加请求参数。 - 单击右侧的![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717390237.png)，可以删除添加的请求参数。 | | 中文名称 | 设置参数的中文名称，便于用户理解参数含义。 | | 参数类型 | 设置请求参数的数据类型。 注意： 请求头（Header）中，所有参数的值必须是字符串类型，不能设置其他类型。 | | 默认值 | 设置参数的默认值，当参数未提供时使用该值。 | | 描述 | 设置请求参数的详细描述信息，准确说明参数的含义、用途和格式要求，以提高大模型对参数识别和提取的准确性。 | | 参数校验 | 设置当前参数是否需要进行校验。 校验规则： - 参数名称：需要校验的参数名称。 - 校验类型： - **字符最大长度** - **枚举值** - **时间日期** - 校验规则：可设置指定格式和自定义格式。 - **指定格式**：选择系统预置的标准校验规则。当校验类型为时间日期时，支持指定格式。 - **自定义格式**：根据实际需求自定义校验规则。 | | 必填 | 设置该参数是否为必填项。 | 2. 配置完单击"确定"，工具创建完成后会跳转至插件详情页面。 3. 在工具列表中，单击"调试"按钮，输入问题后，单击"开始调试"。 必须连通公网，才能获取示例中的{project_id}的值。 对于文字识别插件示例，由于在创建插件的基准URL过程中，将{project_id}设置为变量，因此要填充该值。请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询"西南-贵阳一"区域对应的项目ID。 文字识别插件如果返回401或403报错，请检查"权限校验"配置中的Token或密钥是否正确。 图7获取文字识别插件项目ID ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687790626.png "点击放大") 4. 工具调试完成后，单击"确定"。 调试成功后，工具状态随之变为"成功"，此时可单击右上角"发布"，发布插件。 #### 相关操作 工具创建完成后，您可以在工具列表中查看每个工具的调试状态、智能体引用数和工作流引用数。您可以执行如[表5]的操作。 表5相关操作 | 操作 | 说明 | |:---|:---| | 编辑 | 在工具信息列表中，找到需要编辑的工具，单击该工具操作列中的"编辑"，可编辑工具信息。 | | 调试 | 在工具信息列表中，找到需要调试的工具，单击该工具操作列中的"调试"，在展开的弹框中输入参数信息对工具进行调试。 | | 删除 | 在工具信息列表中，找到需要删除的工具，单击该工具操作列中的"删除"，可删除工具。 | | 查看详情 | 在工具信息列表中，找到需要查看详细信息的工具，单击该工具名称，可查看工具的详细信息。 | #### 附录 创建文字识别插件所需的Token获取方法： 代码中账号名、IAM用户名、IAM用户密码：账号名、IAM用户名请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询，密码按实际填入。 图8查询账号名、IAM用户名 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717550113.png "点击放大") - 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文档通常包含以下核心模块： 表6OpenAPI 3.0核心模块 | 核心模块 | 说明 | |:---|:---| | openapi | 声明所使用的OpenAPI规范版本，如 3.0.1。 | | info | API的基本元信息，包括标题（title）、描述（description）和版本号（version）。 | | servers | API的服务器地址列表，定义请求的基础URL。 | | paths | 核心部分，定义所有可用的API路径及其支持的HTTP方法（GET、POST等），每个方法即对应一个具体的接口（工具）。 | | components（本示例未使用） | 可复用的数据模型、参数、响应体等定义，用于减少重复描述。 | | security（本示例未使用） | 全局或接口级别的鉴权方式声明，如API Key、华为云认证等。 | 平台在创建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: 错误信息 ```