鸿蒙 Agent Framework Kit：FunctionComponent 把智能体嵌进 ArkTS 页面

摘要：HarmonyOS 6（API 11+）除了系统级多智能体调度，还给应用开发者 Agent Framework Kit ------用 FunctionComponent 把智能体嵌进 ArkTS 页面，用 AgentController 管生命周期。本文写 接入层，与「HMAF 宏观架构」互补。

1. 为什么需要「页面内嵌」而不只接云端 API

昨天类文章常写「App 调大模型」。在鸿蒙侧，更完整的路径是：

小艺智能体开放平台：云插件 / 系统插件 / 端插件（Intents Kit）
Agent Framework Kit：应用 UI 内嵌 Agent 组件
MCP / 自定义工具层：把业务能力标准化（可另文）

本篇聚焦第 2 层：用户在你的页面里就能完成 Agent 交互，而不是跳系统对话框。

2. 核心 API 分工

组件	职责
`FunctionComponent`	ArkTS UI 容器，承载 Agent 交互区
`AgentController`	检查可用性、启动/停止、错误回调
意图 / 插件	对接天气、日历、文件等系统能力

参考社区实战文：小艺智能体开放平台、Agent Framework Kit 深度解析（CSDN 社区 2026）。

3. ArkTS 页面结构示例（教学向）

typescript 复制代码

// 伪代码：结构示意，以 DevEco 6 官方 API 为准
@Entry
@Component
struct AgentEmbedPage {
  private controller: AgentController = new AgentController()

  aboutToAppear() {
    this.controller.checkAvailability().then((ok) => {
      if (!ok) {
        // 回退：提示用户升级系统或检查网络
      }
    })
  }

  build() {
    Column() {
      FunctionComponent({
        agentId: 'your_registered_agent',
        controller: this.controller,
        onError: (err) => { /* 日志 + 用户可读提示 */ }
      })
    }
  }
}

实测要点：

checkAvailability() 失败时不要硬启 UI，避免白屏
onError 里区分 网络 / 权限 / Agent 未注册
与 ArkUI 状态管理 同页时，注意异步回调更新 @State

4. 与「小艺开放平台」怎么配合

推荐三层：

复制代码

UI（FunctionComponent）
  → AgentController（生命周期）
    → 云插件 HTTP / 系统插件 / 端侧 Intents
      → 你的业务 MCP 或本地服务

云插件：适合频繁变的业务 API
系统插件：地图、邮件、日历等 50+ 能力
端插件：强交互、低延迟场景

不要在一个页面里混用多套 Agent ID，一个用户任务一个 Agent 会话。

5. 调试清单（DevEco 6）

确认 module.json5 已声明 AI/Agent 相关权限（以官方文档为准）
真机 HarmonyOS 6+，模拟器能力可能不全
打开 HiLog，过滤 AgentController 关键字
注册失败时先查 开放平台 Agent 审核状态，再查代码

6. 与昨日 HMAF 文的边界

主题	昨日 HMAF	今日 Framework Kit
视角	系统多 Agent 调度	应用内嵌 UI
读者	架构 / 产品	ArkTS 工程师
代码	时序图为主	FunctionComponent 为主

7. 下一步（DevEco 真机）

按上文结构新建 Page，先只跑 checkAvailability()
HarmonyOS 6+ 真机打开页面，HiLog 过滤 AgentController
故意断网测 onError 回退文案 是否可读
通过后，再接小艺开放平台 云/系统插件（见 [[文章/CSDN/2026/05/22/002 harmonyos-ai-skill：让 Cursor 按 ArkTS 规范写鸿蒙，不再瞎编 API]]）

原创锚点：本人在 DevEco 6 按上述结构做可用性预检与错误回退，非纯文档翻译。

参考：HarmonyOS 开发者社区 Agent Framework Kit、小艺智能体开放平台实战（2026）