# 基于API创建插件 在AgentArts智能体开发平台中，当官方插件市场无法满足特定业务需求时，开发者需要自主创建插件。根据实现机制与运行形态的不同，自定义插件主要分为"API类型插件"和"函数类型插件"两种形态。函数型插件介绍及创建请参考[基于函数创建插件](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0127.html)。 #### 前提条件 - 已[开通AgentArts服务](https://support.huaweicloud.com/qs-agentarts0/agentarts_04_0000.html)。 - 登录用户为空间所有者、空间管理员、开发工程师，详细信息请参考[管理团队空间成员](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0216.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个工具。 #### 步骤1：创建插件 创建插件过程中，将结合"使用文字识别API创建插件"作为示例进行讲解，文字识别API、插件与工具说明请参考[插件介绍](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0123.html)。 ![](https://support.huaweicloud.com/usermanual-agentarts0/public_sys-resources/note_3.0-zh-cn.png) 示例讲解使用"文字识别服务 \> 通用文字识别API"，请提前在[文字识别服务控制台](https://console.huaweicloud.com/ocr)开通该API。 1. 登录[AgentArts智能体开发平台](https://console.huaweicloud.com/versatile/#/home/overview)，在左侧导航栏"个人空间"区域，选择目标空间。 2. 在左侧导航栏中选择"开发中心 \> 组件库"，在"插件"页签，单击页面右上角"创建插件"。 图1创建插件 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544472.png) 3. 在"创建插件"页面中的"插件类型"中选择"API类型"，然后根据以下步骤配置插件信息。 表1基本信息 | 参数 | 说明 | 示例 | |:---|:---|:---| | 插件类型 | 根据实现机制与运行形态的不同，插件分为"API类型"和"函数类型"两种形态。 | API类型 | | 导入并解析 | 为了简化插件配置流程，可以使用此功能导入符合OpenAPI3.0规范的JSON文件。平台将自动解析文件内容并填充相应的配置参数，从而避免繁琐的手动录入，提高配置效率。 注意： - **鉴权信息** ：**平台目前无法自动解析鉴权配置**，导入后需要手动添加鉴权信息，否则工具调用时将因鉴权缺失而请求失败。 - **规范检查** ：配置文件导入并解析为工具后，**建议逐一检查每个工具的请求参数和响应参数是否已正确解析**。 - 仅支持导入GET和POST请求方式的接口。 | 本示例使用手动创建，不适用自动解析功能。 其他示例代码请参考[OpenAPI 3.0 配置文件示例说明]。 | | 插件图标 | 单击默认图标按钮，可上传本地图片作为插件的自定义图标。 支持jpg、jpeg、png格式，不超过200KB。 | 系统默认图标 | | 名称 | 用于标识当前插件，在"组件库 \> 插件"页面会展示该名称。 命名规则：按照插件的实际功能命名，有助于Agent进行插件的精准识别和调度。 命名要求：可以包含中文、英文、数字、下划线； 长度限制：2\~64个字符。 | 文字识别 | | 描述 | 描述当前插件的类型、功能和适用场景。 需要按照插件的实际功能填写描述，有助于Agent进行插件的精准识别和调度。 | 提供通用文字识别能力，可以对图片中的文字精准提取与解析，输出结构化文本结果，适配各类场景文字识别需求。 | | 仅我可见 | 开启后，该插件将变为私有，仅对当前登录用户可见，其他用户无法查看。 创建后该开关不再支持修改。 | 不开启 | 4. 单击"下一步"，在"配置信息"步骤中配置插件信息，请参照[表2]完成配置。 表2配置信息 | 参数 | 说明 | 示例 | |:---|:---|:---| | 协议 | API服务接口通信协议。 - https - http | https | | 服务域名 | 提供API服务的服务域名。 单击右侧的![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384562.png)按钮，在服务域名中添加变量。添加变量后，可以在变量参数部分设置参数的描述。 以华为云通用文字识别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 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544514.png) | /v2/{project_id}/ocr 注意需要单击右侧的![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544522.png)按钮添加{project_id}变量。该变量表示项目ID，用于标识用户在华为云特定区域下的资源归属。 图2配置示例 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384548.png) | | 权限校验 | 选择调用API时是否需要鉴权。 - **无需鉴权**：API可以公开访问，不需要任何形式的身份验证或授权。 - **API Key** ：在调用API时提供一个唯一的API Key进行鉴权。需配置以下信息 需填写密钥位置、密钥参数名称和取值。Agent在发起请求时，会自动把这个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-north-4。 - 验证方式 - 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/usermanual-agentarts0/zh-cn_image_0000002569424221.png)上，可参看密钥的加密方式。平台默认使用**KMS加密+默认密钥** 方式对认证密钥进行加密存储，防止信息泄露。 - 加密机制：使用用户选择的密钥派生DEK进行加密，默认密钥为kms-agentarts/default。 - 费用说明：实例不收费，每月提供20,000次免费调用次数。解密时支持缓存，但敏感数据较多时可能超出免费次数。如需更换加密方式，具体请参考[更换密钥的加密方式](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0288.html)。 | 华为云文字识别服务采用"华为云认证"。 IAM认证url：https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens 项目：cn-north-4 验证方式：IAM用户名/密码 账号名、IAM用户名、IAM用户密码：账号名、IAM用户名请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询，密码按实际填入。 图3查询账号名、IAM用户名 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384542.png) 图4配置示例 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344231.png) | 5. 配置完单击"确定"。平台会自动跳转至工具信息页面，请参考[步骤2：创建工具]为插件添加工具。 #### 步骤2：创建工具 如需了解插件与工具的关系，请参考[插件介绍](https://support.huaweicloud.com/usermanual-agentarts0/agentarts_05_0123.html)。 1. 在"工具信息"页面，单击"创建工具"，请参照[表3]进行配置。 表3工具基础信息配置 | 参数 | 说明 | 示例 | |:---|:---|:---| | 展示名称 | 用于标识当前工具。 命名规则：按照工具的实际功能命名，有助于Agent进行插件的精准识别和调度。 | 通用文字识别 | | 名称 | 工具的英文名称。 - 命名规则：按照工具的实际功能命名，有助于Agent进行插件的精准识别和调度。 - 命名要求：可以包含大小写字母、数字、下划线。 - 长度限制：1\~64个字符。 | RecognizeGeneralText | | 描述 | 描述当前工具的类型、功能和适用场景。 需要按照工具的实际功能填写描述，有助于Agent进行插件的精准识别和调度。 | 识别图片上的文字信息，以JSON格式返回识别的文字和坐标。 | 2. 参考下表，继续完成工具URL、请求参数、相应参数等信息的配置。 表4工具配置 | 参数 || 说明 | 示例 | |:---|---|:---|:---| | 导入并解析 | - | AI自动解析API请求参数，需填入API的cURL或openAPI的原始内容。 | 本示例使用手动创建，不适用自动解析功能。 | | 工具URL | 请求方式 | API的请求方式，支持**POST** 或**GET**。 | POST | | 工具URL | 工具path | 工具path是API完整调用地址中，用于定位具体功能的后缀片段。 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424213.png) ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424241.png) | /general-text ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344249.png) | | 请求参数 | 参数封装 | 满足某些接口强制要求入参为数组的规定，将对象类型(Object)参数变为数组(Array)，也就是将入参放到一对中括号\[\]中。 - 原参数列表：{"a":"string", "b":1}。 - 开启后：\[{"a":"string", "b":1}\]。 | 不启用 | | 请求参数 | 请求头(Header) | HTTP请求消息的组成部分之一，请求头负责通知服务器有关于客户端请求的信息。 单击![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384530.png)可以新增参数，参数配置说明请参见[表5]。 | 新增两个请求头参数，并设置为必选： X-Auth-Token：获取代码请参考[附录]。 Content-Type：取值为application/json 图5配置示例 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424231.png) | | 请求参数 | 请求体(Body) | HTTP请求消息的组成部分之一，请求体呈现发送给服务器的数据。 可以根据以下两种方式添加参数： - 单击![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424253.png)可以新增参数，参数配置说明请参见[表5]。 - 单击![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344287.png)，输入符合JSON或JSONSchema格式的参数内容。单击"确定"，平台将自动解析并完成导入。 注意： - 平台不支持导入包含"中文名称"的参数。如需设置"中文名称"参数，请在导入后手动配置。 - 此操作将覆盖原有的参数配置，请谨慎操作。 | 文字识别支持2种请求方式，使用图片的url，或者图片的Base64编码。 此处使用url，并设置为必选，使用base64编码需要填写为image。 图6配置示例 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569344271.png) | | 请求参数 | 查询参数(Query) | HTTP请求消息的组成部分之一，用于向服务器传递额外的参数信息。这些参数通常以键值对的形式出现，并且附在URL的路径后面，通过?分隔。 例如，在/items?id=123中，查询参数为ID，值为123。 单击![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544518.png)可以新增参数，参数配置说明请参见[表5]。 | 文字识别插件不涉及 | | 请求参数 | 路径参数(Path) | 自动解析工具path中包含的路径参数。工具path中支持可变参数配置。 例如：/weather/weatherInfo{path_1}/{path_2}。 | 文字识别插件不涉及 | | 响应参数 | 流式响应 | 当插件调用的是一个带有思考效果的模型（如DeepSeek）或者耗时较长的接口，开启这个功能可以让API将获取的响应随时吐出，而不是等API完全获取结果后再一次性显示出来。 | 不启用 | | 响应参数 | 参数封装 | 满足后续插件使用过程中（如工作流的循环节点批量读取数组）要求输入为数组的规定，将对象类型(Object)响应变为数组(Array)，也就是将出参放到一对中括号\[\]中。 - 原参数列表：{"a":"string", "b":1}。 - 开启后：\[{"a":"string", "b":1}\]。 | 不启用 | | 响应参数 | 参数列表 | 响应参数清单，按照API实际的响应参数结构进行填写。 单击![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384524.png)，输入符合JSON或JSONSchema格式的参数内容。单击"确定"，平台将自动解析并完成导入。 此操作将覆盖原有的参数配置，请谨慎操作。 | 增加一个响应参数，名称为result，并设置为必选。 图7配置示例 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384572.png) | 表5参数配置说明 | 参数 | 说明 | |:---|:---| | 参数名称 | 设置请求参数的名称，参数名称会作为大模型解析参数含义的依据。 命名规则：仅支持字母、数字、下划线或短横线。 说明： - 单击参数列表右侧的"添加参数"按钮，可以添加请求参数。 - 单击右侧的![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544492.png)，可以删除添加的请求参数。 | | 中文名称 | 设置参数的中文名称，便于用户理解参数含义。 | | 参数类型 | 设置请求参数的数据类型。 注意： 请求头（Header）中，所有参数的值必须是字符串类型，不能设置其他类型。 | | 默认值 | 设置参数的默认值，当参数未提供时使用该值。 | | 描述 | 设置请求参数的详细描述信息，准确说明参数的含义、用途和格式要求，以提高大模型对参数识别和提取的准确性。 | | 参数校验 | 设置当前参数是否需要进行校验。 校验规则： - 参数名称：需要校验的参数名称。 - 校验类型： - **字符最大长度** - **枚举值** - **时间日期** - 校验规则：可设置指定格式和自定义格式。 - **指定格式**：选择系统预置的标准校验规则。当校验类型为时间日期时，支持指定格式。 - **自定义格式**：根据实际需求自定义校验规则。 | | 必填 | 设置该参数是否为必填项。 | 3. 单击"工具调测"按钮，输入参数值，单击"开始调测"检查调测结果。 必须连通公网，才能获取示例中的{project_id}的值。 对于文字识别插件示例，由于在创建插件的基准URL过程中，将{project_id}设置为变量，因此要填充该值。请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询"华北-北京四"区域对应的项目ID。 图8获取文字识别插件项目ID ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538544460.png) 图9工具调测 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002538384556.png) 4. 确保输出符合预期，再单击工具调测页面右下角的"自动解析"按钮，系统将自动生成响应参数。 5. 工具调试完成后，单击"确定"。 工具创建完成后，可以在工具列表中查看创建完成的工具。 #### 相关操作 工具创建完成后，您可以在工具列表中查看每个工具的调试状态、智能体引用数和工作流引用数。您可以执行如[表6]的操作。 表6相关操作 | 操作 | 说明 | |:---|:---| | 编辑 | 在工具信息列表中，找到需要编辑的工具，单击该工具操作列中的"编辑"，可编辑工具信息。 | | 调试 | 在工具信息列表中，找到需要调试的工具，单击该工具操作列中的"调试"，在展开的弹框中输入参数信息对工具进行调试。 | | 删除 | 在工具信息列表中，找到需要删除的工具，单击该工具操作列中的"删除"，可删除工具。 | | 查看详情 | 在工具信息列表中，找到需要查看详细信息的工具，单击该工具名称，可查看工具的详细信息。 | #### 附录 创建文字识别插件使用，Token获取方法： 代码中账号名、IAM用户名、IAM用户密码：账号名、IAM用户名请登录["我的凭证"](https://console.huaweicloud.com/iam/#/myCredential)页面查询，密码按实际填入。 图10查询账号名、IAM用户名 ![](https://support.huaweicloud.com/usermanual-agentarts0/zh-cn_image_0000002569424239.png) - 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"]) ``` #### OpenAPI 3.0 配置文件示例说明 **OpenAPI 3.0 简介** OpenAPI 3.0（前身为Swagger）是一种用于描述RESTful API的标准规范格式。它以结构化的方式定义API的请求路径、参数、请求体、响应结构等信息，使得机器和人类都能快速理解API的能力与使用方式。 一个标准的OpenAPI 3.0文档通常包含以下核心模块： 表7OpenAPI 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: 错误信息 ```