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

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

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

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

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

2. 核心 API 分工

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

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

// 伪代码：结构示意，以 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）

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

6. 与昨日 HMAF 文的边界

7. 下一步（DevEco 真机）

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

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

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