鸿蒙智能体开发实战：12.使用插件

前言在前一篇文章中我们学习了如何创建自定义插件。本篇文章将介绍如何在智能体中添加、配置和使用插件让智能体具备调用外部能力的功能。在智能体中使用插件本质上是将已经开发好的插件绑定到智能体的编排中配置参数、绑定卡片使得大模型在对话过程中能够根据用户意图自动选择合适的插件进行调用。插件是智能体能力的延伸。一个智能体可以同时绑定多个插件大模型会根据用户输入的语义自动选择合适的插件来完成任务。一、在智能体中添加插件1.1 添加入口在智能体的编排页面找到能力拓展区域的「插件」配置项点击「添加」按钮。添加插件的步骤在插件列表中浏览或搜索所需插件点击插件卡片查看详情点击「添加」按钮将插件绑定到智能体配置插件的参数和绑卡可选1.2 插件选择选择合适的插件需要考虑以下因素考量因素说明功能匹配插件的功能是否与智能体的业务需求匹配数据准确性插件返回的数据是否准确可靠响应速度插件的API响应时间是否在可接受范围内稳定性插件服务是否稳定是否有SLA保障1.3 插件与智能体模式的兼容性智能体模式云插件MCP插件端插件单AgentLLM模式支持支持支持工作流模式支持通过插件节点支持支持多Agents模式支持支持支持A2A模式由外部服务实现由外部服务实现不支持OpenClaw模式由OpenClaw实现由OpenClaw实现不支持二、插件参数配置2.1 配置入口添加插件后点击「插件参数设置」图标进入配置页面。配置页面包含三个区域执行设置配置异步任务、执行方式输入参数配置参数默认值和可见性输出参数配置融合生成2.2 执行设置对于执行耗时较长的插件可以开启异步任务模式{async:{enabled:true,notify_on_complete:true,description:当插件执行超过3秒时自动转为异步任务完成后Push通知用户}}异步任务的执行效果插件执行时小艺APP在前台等待结果返回插件执行时小艺APP在后台执行完成后发送Push通知用户点击Push通知后进入智能体查看结果2.3 输入参数控制输入参数控制大模型是否可以看到和使用某个参数配置开关状态效果启用 默认值开启大模型可读取默认值但仍可自主选择其他值不启用 默认值关闭大模型无法读取始终使用默认值启用 无默认值开启大模型必须从用户输入中提取参数值适用场景# 场景1API密钥不启用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 绑卡操作步骤在插件配置中点击「绑定回复卡片」浏览可用的卡片模板选择适合的卡片并添加配置卡片数据与插件返回数据的映射关系3.3 绑卡配置{card_binding:{card_name:weather_card,data_mapping:{temperature:{{result.temperature}},weather_icon:{{result.weather}},description:{{result.weather_description}}},display_type:DisplayFaCard}}绑卡支持的特性多卡绑定同一插件支持绑定多张卡片同时输出支持同一时刻输出多张卡片顺序编排答复文本和卡片可按配置顺序输出条件出卡通过绑卡标识设置出卡条件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: 查询航班flightsawaitflight_search_plugin.call({from:北京,to:上海,date:2026-04-13})# Step 2: 查询用户信息user_infoawaituser_info_plugin.call({userId:current_user})# Step 3: 创建订单orderawaitbooking_plugin.call({flightId:flights[0].id,passenger:user_info.name,contact:user_info.phone})5.2 条件调用大模型根据上下文判断是否需要调用插件# 用户输入你好# 大模型判断无需调用插件直接回复response你好有什么可以帮助你的吗# 用户输入北京今天天气怎么样# 大模型判断需要调用天气插件weather_dataawaitweather_plugin.call({city:北京})responsef北京今天{weather_data.weather}{weather_data.temperature}°C5.3 插件的优先级当智能体绑定多个插件时大模型根据以下因素选择插件插件描述的匹配度描述越准确匹配率越高工具名称的语义名称越直观越容易被选中历史调用记录之前成功调用的插件优先级更高六、常见问题与排查6.1 插件调用失败排查问题可能原因解决方案插件未调用插件描述不清晰优化插件描述信息参数提取错误参数描述不完整补充参数的描述和示例值API返回错误服务端异常检查API服务的运行状态超时API响应慢开启异步任务或优化API性能6.2 调试技巧# 通过调试页面查看插件调用详情# 可以查看的信息# 1. 调用的插件名称# 2. 使用的工具名称# 3. 请求的参数值# 4. 返回的原始数据# 5. 执行耗时6.3 性能优化# 插件调用优化建议optimization_tips{缓存:对于高频查询如天气建议加缓存减少API调用,批量:多个相关查询尽量合并为一个插件工具,超时:合理设置超时时间避免长时间等待,降级:主API不可用时提供备用方案}七、最佳实践7.1 插件配置建议合理命名插件和工具名称要直观反映功能详细描述描述信息要包含触发条件和返回值说明参数示例为每个参数提供示例值分步调试先在模拟集中测试再上真实环境7.2 注意事项注意端插件执行依赖设备端应用在网页端无法正常调试端插件需要在真机上进行体验调试。插件配置检查清单 □ 插件描述是否准确描述了功能 □ 参数是否都有清晰的描述和示例值 □ 必要参数是否标记为required □ API地址是否可公网访问 □ 是否需要配置异步任务 □ 是否需要绑定回复卡片 □ 融合生成开关是否按需配置八、插件生态与进阶方向8.1 插件组合策略在实际业务中单个插件往往无法满足复杂需求。通过合理组合多个插件可以实现更强大的智能体能力串行组合前一个插件的输出作为后一个插件的输入并行组合多个插件同时执行汇总结果条件组合根据用户意图选择不同的插件组合8.2 持续优化建议定期回顾插件调用日志优化插件描述关注小艺开放平台的插件市场更新参与开发者社区学习最佳实践提示插件生态正在快速发展建议保持对官方文档和社区动态的关注。总结本文详细介绍了在鸿蒙智能体中使用插件的完整流程添加插件选择合适插件绑定到智能体参数配置执行设置、输入/输出参数控制插件绑卡卡片绑定和数据映射配置调用机制大模型自动调用插件的完整流程多插件协作顺序调用、条件调用策略问题排查常见问题和性能优化建议通过合理配置和使用插件可以大大扩展智能体的能力边界。下一篇文章将介绍消息推送功能的开发。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源插件开发指南 - 华为开发者联盟插件参数设置 - 华为开发者联盟插件绑卡 - 华为开发者联盟插件调试 - 华为开发者联盟插件模拟集 - 华为开发者联盟云插件创建指南 - 华为开发者联盟端插件配置 - 华为开发者联盟智能体编排指南 - 华为开发者联盟