前言

在前一篇文章中，我们学习了如何创建自定义插件。本篇文章将介绍如何在智能体中添加、配置和使用插件，让智能体具备调用外部能力的功能。

在智能体中使用插件，本质上是将已经开发好的插件绑定到智能体的编排中，配置参数、绑定卡片，使得大模型在对话过程中能够根据用户意图自动选择合适的插件进行调用。

插件是智能体能力的延伸。一个智能体可以同时绑定多个插件，大模型会根据用户输入的语义自动选择合适的插件来完成任务。

一、在智能体中添加插件

1.1 添加入口

在智能体的编排页面，找到能力拓展区域的「插件」配置项，点击「添加」按钮。

添加插件的步骤：

1. 在插件列表中浏览或搜索所需插件
2. 点击插件卡片查看详情
3. 点击「添加」按钮将插件绑定到智能体
4. 配置插件的参数和绑卡（可选）

1.2 插件选择

选择合适的插件需要考虑以下因素：

考量因素	说明
功能匹配	插件的功能是否与智能体的业务需求匹配
数据准确性	插件返回的数据是否准确可靠
响应速度	插件的API响应时间是否在可接受范围内
稳定性	插件服务是否稳定，是否有SLA保障

1.3 插件与智能体模式的兼容性

智能体模式	云插件	MCP插件	端插件
单Agent（LLM模式）	支持	支持	支持
工作流模式	支持（通过插件节点）	支持	支持
多Agents模式	支持	支持	支持
A2A模式	由外部服务实现	由外部服务实现	不支持
OpenClaw模式	由OpenClaw实现	由OpenClaw实现	不支持

二、插件参数配置

2.1 配置入口

添加插件后，点击「插件参数设置」图标进入配置页面。

配置页面包含三个区域：

1. 执行设置：配置异步任务、执行方式
2. 输入参数：配置参数默认值和可见性
3. 输出参数：配置融合生成

2.2 执行设置

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

{
    "async": {
        "enabled": true,
        "notify_on_complete": true,
        "description": "当插件执行超过3秒时，自动转为异步任务，完成后Push通知用户"
    }
}

异步任务的执行效果：

• 插件执行时，小艺APP在前台：等待结果返回
• 插件执行时，小艺APP在后台：执行完成后发送Push通知
• 用户点击Push通知后，进入智能体查看结果

2.3 输入参数控制

输入参数控制大模型是否可以看到和使用某个参数：

配置	开关状态	效果
启用 + 默认值	开启	大模型可读取默认值，但仍可自主选择其他值
不启用 + 默认值	关闭	大模型无法读取，始终使用默认值
启用 + 无默认值	开启	大模型必须从用户输入中提取参数值

适用场景：

# 场景1：API密钥（不启用）
config = {
    "param": "api_key",
    "enabled": False,
    "defaultValue": "sk-xxx",
    "reason": "API密钥应隐藏，大模型不需要知道"
}

# 场景2：用户输入（启用）
config = {
    "param": "city",
    "enabled": True,
    "description": "大模型从用户输入中提取城市名"
}

# 场景3：默认城市（启用，有默认值）
config = {
    "param": "city",
    "enabled": True,
    "defaultValue": "北京",
    "description": "用户未指定城市时默认使用北京"
}

2.4 输出参数与融合生成

融合生成控制大模型是否基于插件返回结果重新组织语言：

{
    "fusion_generation": {
        "enabled": true,
        "description": "开启后大模型会根据插件结果进行润色和补充说明"
    }
}

开启融合生成的效果：

// 插件返回原始数据
{"temperature": 25, "weather": "晴", "humidity": 30}

// 大模型融合生成后的回复
"当前北京天气晴朗，温度25°C，湿度30%，非常适合户外活动！建议您出门时可以带一件薄外套。"

关闭融合生成的效果：

// 插件返回的原始数据直接展示
"天气数据：温度25°C，天气：晴，湿度：30%"

三、插件绑卡

3.1 绑卡概念

插件绑卡是指将插件返回的数据以卡片形式展示给用户，比起纯文本，卡片可以呈现更丰富的信息。

3.2 绑卡操作步骤

1. 在插件配置中点击「绑定回复卡片」
2. 浏览可用的卡片模板
3. 选择适合的卡片并添加
4. 配置卡片数据与插件返回数据的映射关系

3.3 绑卡配置

{
    "card_binding": {
        "card_name": "weather_card",
        "data_mapping": {
            "temperature": "{{result.temperature}}",
            "weather_icon": "{{result.weather}}",
            "description": "{{result.weather_description}}"
        },
        "display_type": "DisplayFaCard"
    }
}

绑卡支持的特性：

1. 多卡绑定：同一插件支持绑定多张卡片
2. 同时输出：支持同一时刻输出多张卡片
3. 顺序编排：答复文本和卡片可按配置顺序输出
4. 条件出卡：通过绑卡标识设置出卡条件

3.4 绑卡标识

绑卡标识用于设置出卡条件：

标识类型	说明	匹配规则
String	字符串类型	完全相等时出卡
Array[String]	字符串数组	包含指定值时出卡
无标识	无条件	固定出卡

{
    "card_identifier": {
        "field": "weather",
        "type": "String",
        "condition": {
            "equals": "rain",
            "card": "umbrella_card"
        }
    }
}

四、插件调用机制

4.1 调用流程

大模型调用插件的完整流程：

步骤1: 用户输入 "北京今天天气怎么样？"
步骤2: 大模型分析意图 → "用户想查询天气"
步骤3: 大模型选择插件 → "天气查询插件"
步骤4: 大模型提取参数 → {"city": "北京"}
步骤5: 系统调用插件API → GET /weather/current?city=北京
步骤6: 获取API返回结果 → {"temperature": 25, "weather": "晴"}
步骤7: 大模型融合生成回复 → "北京今天天气晴朗，温度25°C..."

4.2 插件调用日志

智能体运行时，每次插件调用都会记录日志：

{
    "timestamp": "2026-04-12T10:30:00Z",
    "plugin": "天气查询插件",
    "tool": "getCurrentWeather",
    "request": {
        "city": "北京"
    },
    "response": {
        "temperature": 25,
        "weather": "晴",
        "humidity": 30
    },
    "duration_ms": 320,
    "status": "success"
}

4.3 插件调用超时处理

超时时间	处理策略
< 3秒	同步等待
3-30秒	转为异步任务，返回处理中状态
> 30秒	返回超时错误，提示用户稍后查看

五、多插件协作

5.1 顺序调用

智能体可以依次调用多个插件处理复杂请求：

# 用户输入："帮我订一张明天从北京到上海的机票"
# 大模型可能依次调用以下插件：

# Step 1: 查询航班
flights = await flight_search_plugin.call({
    "from": "北京",
    "to": "上海",
    "date": "2026-04-13"
})

# Step 2: 查询用户信息
user_info = await user_info_plugin.call({
    "userId": "current_user"
})

# Step 3: 创建订单
order = await booking_plugin.call({
    "flightId": flights[0].id,
    "passenger": user_info.name,
    "contact": user_info.phone
})

5.2 条件调用

大模型根据上下文判断是否需要调用插件：

# 用户输入："你好"
# 大模型判断：无需调用插件，直接回复
response = "你好！有什么可以帮助你的吗？"

# 用户输入："北京今天天气怎么样"
# 大模型判断：需要调用天气插件
weather_data = await weather_plugin.call({"city": "北京"})
response = f"北京今天{weather_data.weather}，{weather_data.temperature}°C"

5.3 插件的优先级

当智能体绑定多个插件时，大模型根据以下因素选择插件：

1. 插件描述的匹配度：描述越准确，匹配率越高
2. 工具名称的语义：名称越直观，越容易被选中
3. 历史调用记录：之前成功调用的插件优先级更高

六、常见问题与排查

6.1 插件调用失败排查

问题	可能原因	解决方案
插件未调用	插件描述不清晰	优化插件描述信息
参数提取错误	参数描述不完整	补充参数的描述和示例值
API返回错误	服务端异常	检查API服务的运行状态
超时	API响应慢	开启异步任务或优化API性能

6.2 调试技巧

# 通过调试页面查看插件调用详情
# 可以查看的信息：
# 1. 调用的插件名称
# 2. 使用的工具名称
# 3. 请求的参数值
# 4. 返回的原始数据
# 5. 执行耗时

6.3 性能优化

# 插件调用优化建议
optimization_tips = {
    "缓存": "对于高频查询（如天气），建议加缓存减少API调用",
    "批量": "多个相关查询尽量合并为一个插件工具",
    "超时": "合理设置超时时间，避免长时间等待",
    "降级": "主API不可用时提供备用方案"
}

七、最佳实践

7.1 插件配置建议

1. 合理命名：插件和工具名称要直观反映功能
2. 详细描述：描述信息要包含触发条件和返回值说明
3. 参数示例：为每个参数提供示例值
4. 分步调试：先在模拟集中测试，再上真实环境

7.2 注意事项

注意：端插件执行依赖设备端应用，在网页端无法正常调试端插件，需要在真机上进行体验调试。

插件配置检查清单：
□ 插件描述是否准确描述了功能？
□ 参数是否都有清晰的描述和示例值？
□ 必要参数是否标记为required？
□ API地址是否可公网访问？
□ 是否需要配置异步任务？
□ 是否需要绑定回复卡片？
□ 融合生成开关是否按需配置？

八、插件生态与进阶方向

8.1 插件组合策略

在实际业务中，单个插件往往无法满足复杂需求。通过合理组合多个插件，可以实现更强大的智能体能力：

1. 串行组合：前一个插件的输出作为后一个插件的输入
2. 并行组合：多个插件同时执行，汇总结果
3. 条件组合：根据用户意图选择不同的插件组合

8.2 持续优化建议

• 定期回顾插件调用日志，优化插件描述
• 关注小艺开放平台的插件市场更新
• 参与开发者社区，学习最佳实践

提示：插件生态正在快速发展，建议保持对官方文档和社区动态的关注。

总结

本文详细介绍了在鸿蒙智能体中使用插件的完整流程：

1. 添加插件：选择合适插件绑定到智能体
2. 参数配置：执行设置、输入/输出参数控制
3. 插件绑卡：卡片绑定和数据映射配置
4. 调用机制：大模型自动调用插件的完整流程
5. 多插件协作：顺序调用、条件调用策略
6. 问题排查：常见问题和性能优化建议

通过合理配置和使用插件，可以大大扩展智能体的能力边界。下一篇文章将介绍消息推送功能的开发。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• 插件开发指南 - 华为开发者联盟
• 插件参数设置 - 华为开发者联盟
• 插件绑卡 - 华为开发者联盟
• 插件调试 - 华为开发者联盟
• 插件模拟集 - 华为开发者联盟
• 云插件创建指南 - 华为开发者联盟
• 端插件配置 - 华为开发者联盟
• 智能体编排指南 - 华为开发者联盟