鸿蒙智能体开发实战：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"}
}
}
}
}
}
}
}
}
}
}
}
}
}
总结
本文详细介绍了鸿蒙智能体自定义插件的开发全流程：
- 插件概述：插件类型、工作流程、与工作流的对比
- 创建云插件：插件创建、OpenAPI工具定义、参数说明
- 参数设置：执行设置、输入/输出参数控制
- 模拟集：创建和使用模拟数据进行调试
- 调试升级：插件调试方法和版本管理策略
- 最佳实践：设计原则和常见问题排查
插件是智能体能力的"肌肉"，掌握插件开发可以让智能体实现几乎任何功能。下一篇文章将介绍如何在智能体中使用和管理插件。
如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！
相关资源：
作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。
更多推荐
0
0- 0
已为社区贡献19条内容
所有评论(0)