鸿蒙智能体开发实战：11.自定义插件-尧图网络科技

前言

插件是智能体能力扩展的核心方式。通过插件，智能体可以调用外部API、访问数据库、执行复杂计算等。鸿蒙智能体平台支持多种插件类型，包括云插件、MCP插件和端插件，满足不同场景的需求。

本文将详细介绍如何开发和配置自定义插件，让智能体具备更强大的能力。无论是接入天气查询、订单管理还是AI绘图等外部服务，都可以通过插件快速实现。

插件是一个工具集，一个插件内可以包含一个或多个工具（API）。合理设计插件结构和工具划分，是构建高质量智能体的关键。

一、插件概述

1.1 什么是插件

插件是一种能力扩展单元，它封装了对外部服务的调用逻辑。智能体在运行时，大模型会根据用户的输入自动选择合适的插件和工具进行调用。

插件的工作流程：

用户输入 → 大模型理解意图 → 选择插件/工具 → 调用外部API → 返回结果 → 大模型整合输出

1.2 插件类型

鸿蒙智能体平台支持三种插件类型：

插件类型	说明	适用场景
云插件	部署在云端的API服务	查询天气、订单管理、数据分析等
MCP插件	基于MCP协议的标准化插件	跨平台工具集成、标准协议对接
端插件	运行在鸿蒙设备端的插件	设备控制、本地文件操作、端侧AI能力

插件类型选择示意图：

上图展示了在小艺开放平台中创建 MCP 插件的入口位置，开发者可以根据业务需求选择对应的插件类型。

1.3 插件 vs 工作流

对比维度	插件	工作流
粒度	单个工具或多个相关工具	多个步骤的组合流程
执行方式	由大模型自动调用	按预设流程执行
复杂度	低到中	中到高
适用场景	单一API调用	多步骤业务处理

二、创建云插件

2.1 插件创建入口

在小艺开放平台，通过「资源库」→「插件」→「新建插件」进入创建页面。

创建插件需要填写以下基本信息：

配置项	说明	示例
插件名称	插件的展示名称	“天气查询”
插件描述	说明插件功能，供大模型理解	“查询指定城市的天气信息”
插件图标	可选，展示用图标	—
插件分类	按功能分类	工具类/生活类/娱乐类

2.2 定义工具（API）

一个插件可以包含一个或多个工具。每个工具对应一个API接口：

{"openapi":"3.0.0","info":{"title":"天气查询插件","description":"查询城市天气信息","version":"1.0.0"},"servers":[{"url":"https://api.weather-service.com/v1"}],"paths":{"/weather/current":{"get":{"summary":"查询当前天气","operationId":"getCurrentWeather","parameters":[{"name":"city","in":"query","required":true,"schema":{"type":"string"},"description":"城市名称，如：北京、上海"}],"responses":{"200":{"description":"成功返回天气信息","content":{"application/json":{"schema":{"type":"object","properties":{"temperature":{"type":"number","description":"当前温度（摄氏度）"},"weather":{"type":"string","description":"天气状况，如：晴、多云、雨"},"humidity":{"type":"number","description":"湿度百分比"}}}}}}}}}}}

2.3 工具参数说明

工具参数定义遵循OpenAPI 3.0规范，核心参数如下：

参数属性	说明	是否必填
`name`	参数名称	是
`in`	参数位置：query/header/path/body	是
`required`	是否必须	否
`schema.type`	参数类型：string/number/integer/boolean/array	是
`description`	参数描述，越详细越好	推荐
`example`	示例值	否

提示：参数描述越详细，大模型越能准确提取用户输入中的参数值。

三、插件参数设置

3.1 执行设置

对于执行耗时较长的插件，可以配置异步任务模式：

{"async_config":{"enabled":true,"timeout":300,"callback_url":"https://your-server.com/callback"}}

异步任务说明：

配置项	说明
开启异步任务	插件耗时较长时，执行完自动Push通知用户
Webhook回调	任务完成后通过Webhook通知智能体
超时设置	任务执行超时时间

3.2 输入参数设置

输入参数支持默认值和启用控制：

{"parameters":[{"name":"city","defaultValue":"北京","enabled":true,"description":"城市名称，启用时大模型可读取并修改"},{"name":"api_key","defaultValue":"sk-xxxx","enabled":false,"description":"API密钥，关闭时大模型无法读取，使用默认值"}]}

参数启用控制策略：

启用 + 默认值：大模型可以读取并自主决定是否使用其他值
关闭 + 默认值：大模型无法读取，始终使用默认值（适合API密钥等敏感参数）
启用 + 无默认值：大模型必须从用户输入中提取

3.3 输出参数设置

输出参数控制大模型是否对插件结果进行融合生成：

配置项	说明	效果
融合生成开启	大模型会基于结果重新组织语言	回复更自然，但可能丢失细节
融合生成关闭	直接展示插件返回的原始数据	数据准确，但不够口语化

四、插件模拟集

4.1 模拟集的作用

插件模拟集允许开发者在不调用真实API的情况下测试插件的执行效果。这在开发调试阶段非常有用。

4.2 创建模拟集

{"mock_data":[{"name":"北京晴天模拟","trigger":{"city":"北京"},"response":{"temperature":25,"weather":"晴","humidity":30}},{"name":"上海雨天模拟","trigger":{"city":"上海"},"response":{"temperature":18,"weather":"小雨","humidity":85}}]}

五、插件调试

5.1 调试方法

在小艺开放平台上，添加插件后可以直接调试：

进入智能体的调试页面
发送包含插件触发条件的消息
查看插件的调用参数和返回结果

调试信息包括：

插件名称：被调用的插件
工具名称：被调用的具体工具
请求参数：大模型提取的参数值
插件结果：API返回的原始数据

5.2 调试注意事项

问题	说明
云插件调试	直接在网页端调试即可
端插件调试	依赖设备端应用，需要在真机上调试
参数错误	检查参数定义和用户输入提取逻辑
超时	检查API响应时间，考虑配置异步任务

六、插件升级

6.1 升级策略

插件支持版本管理，每次修改后可以创建新版本：

{"version":"1.1.0","changelog":["新增：支持查询未来7天天气预报","优化：API响应时间减少50%","修复：特殊字符导致的参数解析错误"]}

6.2 版本兼容性

变更类型	是否兼容	说明
新增工具	兼容	不影响现有工具调用
新增参数	兼容	现有参数保持不变
修改参数名	不兼容	需要更新智能体配置
删除工具	不兼容	移除后相关调用会失败

七、最佳实践

7.1 插件设计原则

单一职责：每个插件聚焦于一个业务领域
合理粒度：一个插件包含3-5个相关工具为宜
描述详尽：插件和工具的描述要清晰准确
参数示例：为参数提供示例值，帮助大模型理解

7.2 常见问题

# 问题1：插件调用失败检查项： ① 插件是否已上架 ② API地址是否可访问 ③ 参数是否匹配# 问题2：大模型未正确调用插件检查项： ① 插件描述是否清晰 ② 参数描述是否完整 ③ 工具名称是否有意义

提示：建议先在模拟集环境中充分测试，再切换到真实API环境。

八、完整开发示例

以下是一个订单查询插件的完整示例：

{"openapi":"3.0.0","info":{"title":"订单查询插件","version":"1.0.0","description":"支持订单查询、物流追踪和订单状态变更"},"servers":[{"url":"https://api.example.com"}],"paths":{"/order/query":{"post":{"summary":"查询订单详情","operationId":"queryOrder","parameters":[{"name":"orderId","in":"query","required":true,"schema":{"type":"string"},"description":"订单号"}],"responses":{"200":{"description":"订单信息","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["pending","paid","shipped","completed","cancelled"]},"amount":{"type":"number"},"createTime":{"type":"string"}}}}}}}}},"/order/track":{"post":{"summary":"查询物流信息","operationId":"trackOrder","parameters":[{"name":"orderId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"物流追踪信息","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"company":{"type":"string"},"trackingNumber":{"type":"string"},"status":{"type":"string"},"updates":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"location":{"type":"string"},"description":{"type":"string"}}}}}}}}}}}}}}