基于API创建插件
在AgentArts智能体开发平台中，当官方插件市场无法满足特定业务需求时，开发者需要自主创建插件。根据实现机制与运行形态的不同，自定义插件主要分为“API类型插件”和“函数类型插件”两种形态。函数型插件介绍及创建请参考基于函数创建插件。
前提条件
- 已开通AgentArts服务。
- 登录用户为空间所有者、空间管理员、开发工程师，详细信息请参考管理团队空间成员。
API形态插件
API类型插件是将现有的RESTful API（HTTP/HTTPS接口）封装为Agent可调用的工具。他不承载业务逻辑，而是将大模型的自然语言指令“翻译”为标准的API请求，发送给外部系统。
典型适用场景：
- 数据检索：如天气查询、网络搜索、新闻查询。
- 状态变更：如发送信息、触发创建任务。
- 复杂业务逻辑处理：售后退换货处理（API后台校验商品是否满足退货条件、换货库存是否充足、生成退订链接、发送通知消息……）。
不适用场景：纯逻辑计算（简单数值计算）、简单的字符串处理（延迟高且浪费网络资源）。
插件调用链路：
- 用户输入：帮我查一下订单12345的状态。
- Agent分析：命中插件get_order_status。
- 参数生成：Agent中模型生成结构化参数{ "order_id": "12345" }。
- 请求构建：Agent组装API插件请求。
- 网络交互：Agent向API服务器发起GET /api/orders/12345请求。
- 响应解析：服务器返回JSON数据，Agent将其清洗后注入模型上下文。
- 最终回复：模型根据数据生成自然语言：“订单12345当前状态为已发货...”。
约束限制
单个插件最多支持添加30个工具。
步骤1：创建插件
创建插件过程中，将结合“使用文字识别API创建插件”作为示例进行讲解，文字识别API、插件与工具说明请参考插件介绍。
- 登录AgentArts智能体开发平台，在左侧导航栏“个人空间”区域，选择目标空间。
- 在左侧导航栏中选择“开发中心 > 组件库”，在“插件”页签，单击页面右上角“创建插件”。
图1 创建插件
- 在“创建插件”页面中的“插件类型”中选择“API类型”，然后根据以下步骤配置插件信息。
表1 基本信息 参数
说明
示例
插件类型
根据实现机制与运行形态的不同，插件分为“API类型”和“函数类型”两种形态。
API类型
导入并解析
为了简化插件配置流程，可以使用此功能导入符合OpenAPI3.0规范的JSON文件。平台将自动解析文件内容并填充相应的配置参数，从而避免繁琐的手动录入，提高配置效率。
注意：- 鉴权信息：平台目前无法自动解析鉴权配置，导入后需要手动添加鉴权信息，否则工具调用时将因鉴权缺失而请求失败。
- 规范检查：配置文件导入并解析为工具后，建议逐一检查每个工具的请求参数和响应参数是否已正确解析。
- 仅支持导入GET和POST请求方式的接口。
本示例使用手动创建，不适用自动解析功能。
其他示例代码请参考OpenAPI 3.0 配置文件示例说明。
插件图标
单击默认图标按钮，可上传本地图片作为插件的自定义图标。
支持jpg、jpeg、png格式，不超过200KB。
系统默认图标
名称
用于标识当前插件，在“组件库 > 插件”页面会展示该名称。
命名规则：按照插件的实际功能命名，有助于Agent进行插件的精准识别和调度。
命名要求：可以包含中文、英文、数字、下划线；
长度限制：2~64个字符。
文字识别
描述
描述当前插件的类型、功能和适用场景。
需要按照插件的实际功能填写描述，有助于Agent进行插件的精准识别和调度。
提供通用文字识别能力，可以对图片中的文字精准提取与解析，输出结构化文本结果，适配各类场景文字识别需求。
仅我可见
开启后，该插件将变为私有，仅对当前登录用户可见，其他用户无法查看。
创建后该开关不再支持修改。
不开启
- 单击“下一步”，在“配置信息”步骤中配置插件信息，请参照表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的具体值。
- 华为云认证：华为云IAM认证，通过IAM账号获取用户Token进行认证。
关于密钥加密：当校验方式选择API Key或华为云认证时，鼠标移动至“参数列表”或“验证方式”右侧的
上，可参看密钥的加密方式。平台默认使用KMS加密+默认密钥方式对认证密钥进行加密存储，防止信息泄露。
- 加密机制：使用用户选择的密钥派生DEK进行加密，默认密钥为kms-agentarts/default。
- 费用说明：实例不收费，每月提供20,000次免费调用次数。解密时支持缓存，但敏感数据较多时可能超出免费次数。如需更换加密方式，具体请参考更换密钥的加密方式。
华为云文字识别服务采用“华为云认证”。
IAM认证url：https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens
项目：cn-north-4
验证方式：IAM用户名/密码
账号名、IAM用户名、IAM用户密码：账号名、IAM用户名请登录“我的凭证”页面查询，密码按实际填入。
图3 查询账号名、IAM用户名
图4 配置示例
- 配置完单击“确定”。平台会自动跳转至工具信息页面，请参考步骤2：创建工具为插件添加工具。
步骤2：创建工具
如需了解插件与工具的关系，请参考插件介绍。
- 在“工具信息”页面，单击“创建工具”，请参照表3进行配置。
- 参考下表，继续完成工具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。 - 单击
，输入符合JSON或JSONSchema格式的参数内容。单击“确定”，平台将自动解析并完成导入。
注意：- 平台不支持导入包含“中文名称”的参数。如需设置“中文名称”参数，请在导入后手动配置。
- 此操作将覆盖原有的参数配置，请谨慎操作。
文字识别支持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实际的响应参数结构进行填写。
单击
，输入符合JSON或JSONSchema格式的参数内容。单击“确定”，平台将自动解析并完成导入。此操作将覆盖原有的参数配置，请谨慎操作。
增加一个响应参数，名称为result，并设置为必选。
图7 配置示例
表5 参数配置说明 参数
说明
参数名称
设置请求参数的名称，参数名称会作为大模型解析参数含义的依据。
命名规则：仅支持字母、数字、下划线或短横线。
说明：- 单击参数列表右侧的“添加参数”按钮，可以添加请求参数。
- 单击右侧的
，可以删除添加的请求参数。
中文名称
设置参数的中文名称，便于用户理解参数含义。
参数类型
设置请求参数的数据类型。
注意：请求头（Header）中，所有参数的值必须是字符串类型，不能设置其他类型。
默认值
设置参数的默认值，当参数未提供时使用该值。
描述
设置请求参数的详细描述信息，准确说明参数的含义、用途和格式要求，以提高大模型对参数识别和提取的准确性。
参数校验
设置当前参数是否需要进行校验。
校验规则：
- 参数名称：需要校验的参数名称。
- 校验类型：
- 字符最大长度
- 枚举值
- 时间日期
- 校验规则：可设置指定格式和自定义格式。
- 指定格式：选择系统预置的标准校验规则。当校验类型为时间日期时，支持指定格式。
- 自定义格式：根据实际需求自定义校验规则。
必填
设置该参数是否为必填项。
- 单击“工具调测”按钮，输入参数值，单击“开始调测”检查调测结果。
必须连通公网，才能获取示例中的{project_id}的值。
对于文字识别插件示例，由于在创建插件的基准URL过程中，将{project_id}设置为变量，因此要填充该值。请登录“我的凭证”页面查询“华北-北京四”区域对应的项目ID。
图8 获取文字识别插件项目ID
图9 工具调测
- 确保输出符合预期，再单击工具调测页面右下角的“自动解析”按钮，系统将自动生成响应参数。
- 工具调试完成后，单击“确定”。
工具创建完成后，可以在工具列表中查看创建完成的工具。
相关操作
工具创建完成后，您可以在工具列表中查看每个工具的调试状态、智能体引用数和工作流引用数。您可以执行如表6的操作。
附录
创建文字识别插件使用，Token获取方法：
代码中账号名、IAM用户名、IAM用户密码：账号名、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"])
OpenAPI 3.0 配置文件示例说明
OpenAPI 3.0 简介
OpenAPI 3.0（前身为Swagger）是一种用于描述RESTful API的标准规范格式。它以结构化的方式定义API的请求路径、参数、请求体、响应结构等信息，使得机器和人类都能快速理解API的能力与使用方式。
一个标准的OpenAPI 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: 错误信息
