【寻迹校园 HarmonyOS NEXT 实战 43】Agent Framework Kit 还是 Intents Kit：HarmonyOS 小艺能力选型别走错路

本章导读：这是“寻迹校园 HarmonyOS NEXT 实战”系列第 43 篇。本文截至 2026-08-27 重新核对华为官方资料，从用户结果出发区分 Agent Framework Kit 的应用内智能体入口与 Intents Kit 的系统级意图能力，并解释寻迹校园为什么选择 FunctionComponent，以及设备、账号、应用关联、上架配置和审核不能被构建成功替代。

上图是原创架构概念图，不是系统小艺截图。两个 Kit 都与智能交互有关，但解决的入口、调用方和交付门槛不同。

一、不要从 Kit 名称开始选型

“我要接小艺”不是可执行需求。先把用户结果写清楚：

• 用户是否仍停留在自己的 App 内？
• 是用户主动打开一个指定智能体，还是系统理解一句话后调用 App 的业务能力？
• 需要的是一个 UI 入口，还是可被系统编排的业务意图？
• 业务主流程能否在 AI 不可用时继续完成？

同样叫“小艺能力”，答案不同，Kit 就不同。

二、官方定义给出的第一条边界

华为 HarmonyOS 文档中心将 Agent Framework Kit 描述为在应用内通过 UI 控件主动拉起智能体的服务；同一文档中心将 Intents Kit 定义为 HarmonyOS 级意图标准，用于连接应用或元服务内的业务功能。

可以先用一句话区分：

App 内给用户一个智能体入口 -> Agent Framework Kit
让系统理解并调用 App 能力 -> Intents Kit

这不是绝对互斥。一个成熟产品可能同时拥有应用内 Agent 入口和系统意图，但它们应是两个独立交付面。

三、Agent Framework Kit 更像“受控入口”

寻迹校园的用户已经在匹配结果页看到本机候选，此时需要一个明确按钮，把脱敏候选摘要带到指定小艺智能体做辅助比较。用户路径是：

本机候选 -> 准备脱敏摘要 -> 检查支持性
-> 用户复制摘要 -> FunctionComponent 打开小艺 -> 用户粘贴发送

用户不是在系统任意入口说“帮我找书包”，也不是要求系统直接创建一条失物记录。因此，应用内 UI 控件是更贴近当前结果的选择。

四、Intents Kit 面向系统级业务能力表达

Intents Kit 的重点是把“查询、创建、导航、执行”等业务能力表达成系统可理解、可发现、可调用的意图。官方 insightIntent API 说明，这类数据可以帮助系统学习、预测并在系统入口推荐 Intent；接口从 4.0.0(10) 起提供，具体能力仍要以当前 SDK 与产品配置为准。

官方参考：insightIntent API。

如果寻迹校园未来希望用户在系统入口说“登记我在图书馆丢失的黑色雨伞”，并由系统编排 App 的登记能力，就更接近 Intents Kit 的问题域。

五、错误选型会造成什么

真实目标	错误选择	后果
App 内打开指定智能体	先做复杂系统意图	配置与审核成本扩大，核心入口仍没落地
系统语义调用 App 功能	只放一个 FunctionComponent	用户必须先打开 App，系统无法发现业务能力
AI 只是辅助核验	把 AI 设为唯一主流程	账号、网络或平台失败会阻断认领
需要稳定参数交接	只看类型定义	真机行为可能与预期不同

选错 Kit 不一定编译失败，却可能交付一个不满足用户结果的能力。

六、寻迹校园为什么先选 FunctionComponent

项目已有完整本机闭环：登记、筛选、候选匹配、私密特征核验、交接与状态记录均不依赖小艺。小艺只承担“对最多三条脱敏候选列出相似点和冲突”。

因此它满足三个条件：

• 用户已在 App 内；
• 用户明确触发辅助能力；
• AI 不可用时可以返回原生候选继续核验。

这正适合把 FunctionComponent 作为可选增强，而不是把核心数据模型改造成系统意图。

七、组件接入前还要有支持性检查

项目不是直接渲染 FunctionComponent。XiaoYiFunctionPage 先调用：

const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
this.supported = await this.controller.isAgentSupport(context, 'agent_xxx');

只有 supported=true 才渲染组件；否则显示当前设备或账号暂不支持，并提供重试或返回路径。示例中的 Agent ID 已替换为占位符，公开文章不应暴露真实平台标识。

八、API 版本只是第一道门

宿主页在进入独立 Function 页面前检查 deviceInfo.sdkApiVersion < 20，并提示需要 HarmonyOS 6.0 或更高版本真机。当前本机 SDK 声明中，相关 Agent Kit 接口从 6.0.0(20) 起提供。

但 sdkApiVersion >= 20 只证明系统版本门槛可能满足，不能证明：

• 设备型号实际开放该能力；
• 用户已登录华为账号；
• 用户已接受隐私协议；
• Agent ID 与应用关系配置正确；
• 网络与地区条件满足；
• 平台审核状态允许调用。

所以版本检查之后仍必须调用 isAgentSupport()。

九、Intents 的上架配置是另一套门禁

官方 Intents Kit 上架配置指导 明确说明，进行意图注册配置和提交前，应用需要已经在 AppGallery Connect 上架，并使用同一账号操作。该页面更新时间为 2025-03-17，实际提交时仍应重新核对最新规则。

这说明“ArkTS 代码写好了”与“系统可以发现意图”之间，还隔着应用状态、平台配置和审核流程。

十、把平台条件拆成可验证清单

无论选哪个 Kit，都不要写一句“支持 HarmonyOS”就结束。至少拆成：

维度	验证问题
系统版本	当前 SDK 与真机 API 是否满足
设备能力	isAgentSupport 或对应能力检查是否通过
账号	是否登录、是否接受隐私协议
应用关联	Agent/Intent 与当前 bundle 是否正确绑定
平台配置	能力是否提交、保存、审核
运行行为	入口、参数、错误和回退是否真机复测
发布状态	本地、上传、提交审核、通过审核分别记录

这张表能避免把某一层成功写成端到端成功。

十一、用户数据方向也不同

Agent Framework Kit 的应用内入口通常由 App 主动准备上下文，但仍应遵守数据最小化。寻迹校园只生成最多 240 字的脱敏文字摘要，不传原图、手机号、证件号或私密核验答案。

Intents Kit 则需要把业务能力和参数结构表达给系统，字段设计必须同时考虑意图语义、权限、敏感数据和系统推荐范围。它不是“把整个页面对象序列化出去”。

十二、不要把 queryText 类型存在当成运行成功

本机 SDK 的 FunctionOptions 确实声明了可选 queryText，注释为初始查询文本。寻迹校园也把脱敏摘要放入该字段。

但空白新会话真机复测显示，文本没有自动出现在输入框，也没有自动发送。因此当前成功路径是用户明确复制、打开小艺、粘贴并发送；queryText 仅保留为兼容输入，不作为成功判据。

选型必须结合真机行为，不能停在 API 名称和类型定义。

十三、AI 能力不能吃掉原生主流程

正确架构是：

本机规则匹配（必选、可独立完成）
  -> 小艺辅助比较（可选）
  -> 私密特征核验（必选）
  -> 双方确认交接（必选）

即使账号未登录、网络异常、Agent 未关联或平台处于审核中，用户仍能返回候选列表查看详情并继续线下核验。

十四、选型决策树

上图是本文原创决策图。最上层先问“用户要获得什么结果”，再分别进入应用内 Agent 与系统级 Intent。图中前置条件是检查维度，不代表两个 Kit 的平台步骤完全相同。

十五、什么时候应该考虑同时使用两个 Kit

可以在业务成熟后采用双入口：

• App 内使用 Agent Framework Kit 做候选解释；
• 系统侧用 Intents Kit 暴露“创建失物记录”“查询我的处理进度”等明确能力；
• 两个入口共享同一 Service/Repository，而不是复制业务规则；
• 权限、隐私说明和失败回退分别验收。

前提是每个入口都有清晰用户价值，而不是为了覆盖更多 Kit 而堆功能。

十六、官方资料应怎样使用

平台能力变化快，文章发表前至少核对：

• HarmonyOS 文档中心对 Kit 的当前定位；
• 当前 SDK .d.ets 的 since、参数和错误码；
• AGC 上架配置的账号与应用状态要求；
• 当前真机的支持性检查和行为。

官方说明用于确定契约，项目代码用于确定实现，真机记录用于确定行为，三者不能互相替代。

十七、本章证据边界

本章能证明：寻迹校园当前实现使用 Agent Framework Kit 的 FunctionComponent 与 FunctionController.isAgentSupport()；官方文档将 Agent Framework Kit 与 Intents Kit 定位为不同层级的能力；项目已有真机打开小艺与显式复制/粘贴链路记录。

本章不能证明：所有地区和设备都支持、Intents Kit 已在本项目配置或审核、queryText 自动交接成功、未来平台规则不会变化。

十八、小结

Agent Framework Kit 与 Intents Kit 的真正分界不是“都能不能接小艺”，而是用户入口和能力暴露层级。寻迹校园当前需要的是 App 内可选的智能体辅助入口，所以先用 FunctionComponent，并让原生匹配闭环独立存在。

未来如果要让系统直接发现并调用“登记、查询、进度”等业务能力，再单独设计 Intents 合约、上架配置和审核证据，不能把一个组件入口包装成系统级意图。

下一篇：《【寻迹校园 HarmonyOS NEXT 实战 44】把候选交给小艺前先脱敏：XiaoYiAgentAdapter 的数据最小化设计》。