HMAF鸿蒙智能体框架开发实践：感知-决策-行动全链路实现

鸿蒙专家

随着大语言模型技术的成熟，人机交互正从图形用户界面（GUI）转向语言用户界面（LUI）。HarmonyOS推出的HMAF（鸿蒙智能体框架）作为操作系统级基础设施，旨在打通感知、决策、行动全链路，实现跨平台智能体协作。本文从开发角度解析HMAF的三层架构、核心能力及代码接入方式。

一、三层架构与开发入口
HMAF采用应用层、框架层、能力层三层设计。应用层通过Agent Framework Kit暴露两个关键模块：FunctionComponent用于声明式拉起智能体，AgentController管理生命周期。开发者只需约40行声明式代码即可接入系统级智能体，操作系统自动处理UI渲染、流式输出和网络通信。

二、感知层实现：环境感知智能体
感知是链路起点，包括交互感知和环境感知。以下代码展示环境感知智能体：每5秒轮询传感器数据，检测到人员存在且温度超标时自动通知空调智能体，光照不足时通知灯光智能体。

2. import { BaseAgent } from '@ohos.ai.agent';
4. export class EnvironmentSensorAgent extends BaseAgent {
5.     private temperature: number = 24;
6.     private brightness: number = 500;
7.     private presence: boolean = false;
8.     private pollingTimer: number = -1;
10.     constructor() {
11.         super('agent.environment.sensor', [
12.             'temperature_monitoring',
13.             'brightness_detection',
14.             'presence_sensing'
15.         ]);
16.         this.startSensorPolling();
17.     }
19.     private startSensorPolling(): void {
20.         this.pollingTimer = setInterval(async () => {
21.             this.temperature = 22 + Math.random() * 6;
22.             this.brightness = 300 + Math.random() * 400;
23.             this.presence = Math.random() > 0.3;
24.             if (this.presence) {
25.                 await this.checkEnvironmentAndNotify();
26.             }
27.         }, 5000);
28.     }
30.     private async checkEnvironmentAndNotify(): Promise<void> {
31.         if (this.temperature > 26) {
32.             await this.sendMessage('agent.ac.control', {
33.                 action: 'cooling',
34.                 targetTemperature: 24,
35.                 urgency: 'high'
36.             });
37.         }
38.         if (this.brightness < 200 && this.presence) {
39.             await this.sendMessage('agent.light.control', {
40.                 action: 'turn_on',
41.                 brightness: 70,
42.                 colorTemperature: 4000
43.             });
44.         }
45.     }
47.     onDestroy(): void {
48.         if (this.pollingTimer !== -1) {
49.             clearInterval(this.pollingTimer);
50.             this.pollingTimer = -1;
51.         }
52.     }
53. }

复制代码

三、决策层：多智能体协同与任务规划
决策层包含任务规划器和多智能体协同引擎。场景编排智能体可将用户高层意图拆解为子任务，并行调度多个专业智能体。例如创建“舒适休息”场景时，同时发送指令给空调、灯光、窗帘智能体，并支持失败回滚。

2. import { BaseAgent } from '@ohos.ai.agent';
4. export class SceneOrchestratorAgent extends BaseAgent {
5.     constructor() {
6.         super('agent.scene.orchestrator', [
7.             'scene_planning',
8.             'multi_agent_coordination',
9.             'task_decomposition'
10.         ]);
11.     }
13.     async createRelaxScene(): Promise<void> {
14.         const results = await Promise.all([
15.             this.sendMessage('agent.ac.control', {
16.                 action: 'cooling',
17.                 targetTemperature: 24,
18.                 mode: 'quiet'
19.             }),
20.             this.sendMessage('agent.light.control', {
21.                 action: 'set_scene',
22.                 scene: 'warm_relax',
23.                 brightness: 40
24.             }),
25.             this.sendMessage('agent.curtain.control', {
26.                 action: 'close',
27.                 speed: 'slow'
28.             })
29.         ]);
30.         const allSuccess = results.every(r => r.success === true);
31.         if (allSuccess) {
32.             console.info('舒适休息场景编排完成');
33.         } else {
34.             await this.rollbackScene(results);
35.         }
36.     }
38.     private async rollbackScene(results: Array<{success: boolean, agentId: string}>): Promise<void> {
39.         for (const result of results) {
40.             if (result.success) {
41.                 await this.sendMessage(result.agentId, { action: 'restore' });
42.             }
43.         }
44.     }
45. }

复制代码

四、行动层：服务调用与跨设备流转
行动层通过服务调用器标准化调用鸿蒙生态服务，兼容MCP协议。跨设备任务流转依赖分布式软总线，智能体之间通过Agent通信协议进行服务发现、能力协商和安全鉴权。该协议针对高频小数据量交互优化，跨设备协作时延降低70%。

五、智能体注册与拉起完整流程
开发者注册智能体时需声明agentId、名称、版本和能力列表；拉起时通过AgentController检测可用性，再调用FunctionComponent传入参数。

2. import agent from '@ohos.ai.agent';
3. import { AgentController, FunctionComponent } from '@ohos.ai.agentframeworkkit';
4. import { BusinessError } from '@ohos.base';
5. import hilog from '@ohos.hilog';
7. export class AgentIntegrationDemo {
8.     private agentId: string = 'agent.travel.booking';
10.     async registerTravelAgent(): Promise<void> {
11.         try {
12.             agent.registerAgent({
13.                 agentId: this.agentId,
14.                 name: 'TravelBookingAgent',
15.                 version: '1.0.0',
16.                 capabilities: [
17.                     'flight_search',
18.                     'hotel_booking',
19.                     'itinerary_planning',
20.                     'cross_device_handoff'
21.                 ]
22.             });
23.             hilog.info(0x0001, 'AgentDemo', '旅行预订智能体注册成功');
24.         } catch (err) {
25.             hilog.error(0x0001, 'AgentDemo', `注册失败: ${(err as BusinessError).message}`);
26.         }
27.     }
29.     async invokeTravelAgent(): Promise<void> {
30.         const isAvailable = await AgentController.isServiceAvailable(this.agentId);
31.         if (!isAvailable) {
32.             hilog.warn(0x0001, 'AgentDemo', '旅行预订智能体当前不可用');
33.             return;
34.         }
35.         FunctionComponent.create({
36.             agentId: this.agentId,
37.             params: {
38.                 destination: 'Beijing',
39.                 date: '2026-05-10',
40.                 preference: 'comfort'
41.             },
42.             onError: (err: BusinessError) => {
43.                 hilog.error(0x0001, 'AgentDemo', `智能体调用出错: ${err.code} - ${err.message}`);
44.             }
45.         });
46.         hilog.info(0x0001, 'AgentDemo', '旅行预订智能体已拉起');
47.     }
48. }

复制代码

六、开发总结
HMAF通过三层架构和分布式软总线，实现了极简开发（约40行代码接入）、自主决策（多智能体协同）、无缝流转（跨设备任务迁移）和生态兼容（MCP协议）。开发者应重点关注智能体能力声明的颗粒度、消息协议的标准化以及异常回滚机制，以构建稳健的智能体应用。

热心网友3

感谢楼主的详细分享！代码示例很清晰，特别是环境传感器智能体的轮询检测和多智能体协同的场景编排，很有参考价值。想问一下，在任务失败回滚方面，HMAF是否有内置的补偿机制还是需要开发者自己实现？期待后续关于行动层的更多内容。