鸿蒙智能体框架 HMAF 上手：从 Agent 注册到 ArkTS 联调

作者：张大鹏 | 大鹏AI教育 | 2026-05-21

标签：HarmonyOS HMAF AI Agent ArkTS DevEco Studio

---

---

阅读提示

昨天我们聊过「鸿蒙 App 怎么接 MCP 工具链」。今天换一条线：HarmonyOS 6 的 HMAF（鸿蒙智能体框架） 把 Agent 能力下沉到系统层------小艺可以调度第三方智能体，应用侧也要学会「注册 Agent、暴露工具、用 ArkTS 联调」。

这篇文章不讲概念堆叠，只拆一条能跑通的工作流：Agent 生命周期 → 工具注册 → hilog 联调 → ArkTS 页面触发。

---

1. 先分清三层：HMAF、Agent Framework Kit、A2A

很多开发者把三个名词混用，联调时会找错文档。

层级	是什么	开发者要关心什么
HMAF	系统级智能体生态框架	小艺入口、多 Agent 协同、系统调度策略
Agent Framework Kit	应用侧 SDK（API 20+）	FunctionComponent、FunctionController、应用内嵌 Agent UI
A2A 协议	Agent-to-Agent 互操作标准	Agent Card 发布、跨应用任务委托

我的实测结论是：做 App 内智能助手，先从 Agent Framework Kit 入手；要做跨 App 协同，再补 A2A 与 Agent Card。

---

2. Agent 生命周期：别跳过「注册 → 就绪 → 销毁」

HMAF 体系里，一个 Agent 不是「new 出来就能聊」，它有明确生命周期：

创建/注册 → 加载工具集 → 就绪(Ready) → 执行(Task) → 暂停/恢复 → 销毁

2.1 注册方式有两条路径

路径 A：小艺开放平台

适合要上架到小艺入口、或需要工作流编排的智能体。在开放平台配置 LLM / 工作流 / A2A 模式，完成调试后发布。官方披露已有 50+ 先锋鸿蒙智能体在开发中（微博、喜马拉雅、大众点评等）。

路径 B：应用内 Agent Framework Kit

适合「App 自带 AI 助手」场景。在 module.json5 声明 Agent 相关权限与 Ability，通过 Kit 提供的组件把 Agent 嵌进 ArkUI 页面。

HarmonyOS 6.0（API 20+）还支持 Agent Card 自动发现 ：应用可通过 /.well-known/agent-card.json 发布能力描述，系统自动完成注册与发现------相当于 A2A 生态的「黄页条目」。

2.2 Agent Card 最小字段

无论哪条路径，都建议先把 Agent Card 想清楚。最小 JSON 结构示意：

{
  "name": "StudyPlanAgent",
  "description": "查询与更新本周学习计划",
  "url": "https://your-app.example/agent",
  "capabilities": {
    "streaming": true,
    "tools": true
  },
  "skills": [
    {
      "id": "query_plan",
      "name": "查询计划",
      "description": "按日期范围返回学习任务列表"
    }
  ]
}

Agent Card 解决的是 「别人（或小艺）怎么发现你」 ；应用内 Kit 解决的是 「用户在你的 App 里怎么调用」。两件事都要做，但可以分阶段。

---

3. 工具注册：把「能办事」写进 Agent，而不是写进 Prompt

Agent 和普通 ChatBot 的分水岭在工具层。HMAF 体系推荐把业务能力封装成 Tool / Function，由 Agent 运行时调度，而不是把接口细节全塞进 system prompt。

3.1 工具定义三要素

要素	说明	常见踩坑
name	工具唯一标识	与 ArkTS 侧 handler 名不一致，调用静默失败
description	给模型看的自然语言说明	太笼统，模型乱选工具
parameters	JSON Schema 描述入参	缺 required 字段，模型传空对象

示例：查询学习计划的工具 schema：

{
  "name": "queryStudyPlan",
  "description": "查询指定日期范围内的学习任务，返回标题、截止时间和完成状态",
  "parameters": {
    "type": "object",
    "properties": {
      "startDate": { "type": "string", "description": "ISO 日期，如 2026-05-21" },
      "endDate": { "type": "string", "description": "ISO 日期" }
    },
    "required": ["startDate", "endDate"]
  }
}

3.2 ArkTS 侧绑定 handler

工具注册后，ArkTS 层要实现对应的 handler，把模型传来的 JSON 参数映射到本地 Ability 或 HTTP 调用：

// 伪代码示意 --- 以 Agent Framework Kit 官方 API 为准
import { FunctionController } from '@kit.AgentFrameworkKit';

@Entry
@Component
struct AgentPage {
  private controller: FunctionController = new FunctionController();

  aboutToAppear() {
    this.controller.registerTool('queryStudyPlan', async (params: Record<string, string>) => {
      const result = await this.fetchPlanFromLocal(params.startDate, params.endDate);
      return JSON.stringify(result);
    });
  }

  build() {
    FunctionComponent({ agentId: 'StudyPlanAgent', controller: this.controller })
  }
}

关键原则：handler 里只做「参数校验 → 调用业务 → 返回结构化 JSON」；规划与多轮推理交给 Agent 运行时。

---

4. hilog 联调：Agent 链路的「黑盒变透明」

Agent 联调最难的是：UI 显示「正在思考」，但不知道卡在哪一步------是模型没返回？工具没触发？还是 handler 抛异常？

4.1 必开日志域

在 DevEco Studio 中，用 hilog 给 Agent 链路打 4 个检查点：

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0xA001;
const TAG = 'StudyAgent';

// 检查点 1：用户输入
hilog.info(DOMAIN, TAG, 'userInput: %{public}s', userText);

// 检查点 2：Agent 状态变更
hilog.info(DOMAIN, TAG, 'agentState: %{public}s', state);

// 检查点 3：工具调用
hilog.info(DOMAIN, TAG, 'toolCall: %{public}s params=%{public}s', toolName, JSON.stringify(params));

// 检查点 4：工具返回
hilog.info(DOMAIN, TAG, 'toolResult: %{public}s', result.slice(0, 200));

HiLog 过滤命令：

hdc shell hilog -T StudyAgent

4.2 联调工作流（推荐顺序）

步骤	动作	通过标准
1	静态检查 Agent Card / 权限声明	编译无告警，权限弹窗正常
2	纯文本对话（不触发工具）	hilog 可见 userInput → agentState=Ready → 回复
3	强制触发单工具	hilog 可见 toolCall + toolResult
4	多轮 + 工具链	状态机无卡死，错误有 fallback 文案
5	弱网 / 断网	端侧策略符合预期（降级或提示）

我实测中最常见的三个问题：

1. 工具 description 太模糊 → 模型不调用，hilog 里只有对话没有 toolCall
2. handler 返回非 JSON 字符串 → Agent 运行时解析失败，UI 显示空白
3. 权限未声明 → handler 调本地数据时抛异常，但 UI 只显示「服务异常」

---

5. 完整工作流拆解：从 0 到 ArkTS 联调

把上面内容合成一条可执行的开发流水线：

① DevEco 创建 API 20+ 工程
    ↓
② module.json5 声明 Agent 权限与 Ability
    ↓
③ 编写 Agent Card（或接入小艺开放平台）
    ↓
④ 定义 1--3 个 Tool schema + ArkTS handler
    ↓
⑤ FunctionComponent 嵌入 Agent UI
    ↓
⑥ hilog 四检查点联调
    ↓
⑦ 真机验证权限弹窗 + 弱网降级

5.1 与 MCP 的关系（怎么选）

场景	推荐
App 内助手、调本地 Ability	Agent Framework Kit + 原生 Tool
复用已有 MCP Server 生态	MCP 作工具层，Agent Kit 作 UI + 编排
跨 App 委托任务	A2A + Agent Card

不必二选一：Kit 管 UI 与生命周期，MCP 管工具标准化，这在 HarmonyOS 6 工程里是完全可行的组合。

---

6. 小结

HMAF 把鸿蒙 Agent 从 Demo 推向了系统级生态。对应用开发者来说，落地抓手是三条：

1. 生命周期：注册 → 就绪 → 执行 → 销毁，Agent Card 别省略
2. 工具注册：schema 写清楚，handler 只干业务
3. hilog 联调：四个检查点让黑盒变透明

---

下一步你可以这样做

1. 用 DevEco Studio 创建 API 20+ 工程，引入 Agent Framework Kit
2. 先只做 1 个 Agent + 1 个 Tool（比如查本地 Mock 数据），跑通 hilog 全链路
3. 在真机上验证权限弹窗与错误 fallback，再考虑接小艺开放平台或 A2A 跨应用协同

如果你已经在做鸿蒙 Agent 工程，欢迎在评论区贴你的 Agent Card 字段设计 或 hilog 踩坑记录------我可以帮你对照 Kit 文档做第二轮联调清单。

---

参考：华为《Agent 时代，鸿蒙应用生而智能》白皮书 · HarmonyOS 开发者社区 Agent Framework Kit 文档 · OpenHarmony A2A 协议实战