基于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当前状态为已发货...”。
步骤1：创建插件
创建插件过程中，将结合“使用文字识别API创建插件”作为示例进行讲解，文字识别API、插件与工具说明请参考插件介绍。
- 登录AgentArts智能体平台，在左侧导航栏“个人空间”区域，选择目标空间。
- 在左侧导航栏中选择“开发中心 > 组件库”，在“插件”页签，单击页面右上角“创建插件”。
图1 创建插件
- 在“创建插件”页面中的“插件类型”中选择“API类型”，然后根据以下步骤配置插件信息。
表1 基本信息 参数
说明
示例
插件类型
根据实现机制与运行形态的不同，插件分为“API类型”和“函数类型”两种形态。
API类型
插件图标
单击默认图标按钮，可上传本地图片作为插件的自定义图标。
支持jpg、jpeg、png格式，不超过200KB。
系统默认图标
展示名称
用于标识当前插件，在“组件库 > 插件”页面会展示该名称。
命名规则：按照插件的实际功能命名，有助于Agent进行插件的精准识别和调度。
命名要求：可以包含中文、英文、数字、特殊字符等；
长度限制：1~64个字符。
文字识别
名称
插件的英文名称。
命名规则：按照插件的实际功能命名，有助于Agent进行插件的精准识别和调度。
命名要求：字母、数字和下划线（_）的组合，不允许使用其他特殊字符或空格；
长度限制：1~64个字符。
TextRecognitionPlugin
描述
描述当前插件的类型、功能和适用场景。
需要按照插件的实际功能填写描述，有助于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的具体值。
- 开通配置：设置在使用插件时，是否需要手动填写API Key。
- 无需手动开通：填写的API Key值将作为预置信息。
- 手动创建：填写的API Key值将作为插件后续调试使用，在Agent正式使用插件时，需要填写新的API Key值。
- 华为云认证：华为云IAM认证，通过IAM账号获取用户Token进行认证。
华为云文字识别服务采用“华为云认证”。
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。
文字识别支持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）中，所有参数的值必须是字符串类型，不能设置其他类型。
默认值
设置参数的默认值，当参数未提供时使用该值。
描述
设置请求参数的详细描述信息，准确说明参数的含义、用途和格式要求，以提高大模型对参数识别和提取的准确性。
参数校验
设置当前参数是否需要进行校验。
校验规则：
- 参数名称：需要校验的参数名称。
- 校验类型：
- 字符最大长度
- 枚举值
- 时间日期
- 校验规则：可设置指定格式和自定义格式。
- 指定格式：选择系统预置的标准校验规则。当校验类型为时间日期时，支持指定格式。
- 自定义格式：根据实际需求自定义校验规则。
必填
设置该参数是否为必填项。
- 单击“工具调测”按钮，输入参数值，单击“开始调测”检查调测结果。
对于文字识别插件示例，由于在创建插件的基准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"])
