很多开发者对 AgentFrameworkKit 的认知停留在「拉起智能体对话的 UI 组件」但它远不止是一个前端控件——它是鸿蒙系统级智能体生态面向应用层的唯一标准接入入口向下串联着 HMAF 鸿蒙智能体中枢、A2A 标准化通信协议、分布式软总线与全链路安全体系向上为应用提供「零成本接入系统智能体生态」的标准化能力。本文从顶层架构、核心组件、通信协议到全链路执行流程完整拆解 AgentFrameworkKit 的底层设计与系统级智能体的协作逻辑。一、顶层定位HMAF 框架下的应用接入层要理解 AgentFrameworkKit首先要理清鸿蒙智能体的整体架构。鸿蒙 6 起正式落地的HMAFHarmonyOS Mobile Agent Framework鸿蒙智能体框架是操作系统级的智能体中枢采用「中枢-终端-链路-生态」四层架构AgentFrameworkKit 是应用层对接这套体系的封装入口。1.1 HMAF 四层全局架构架构层级核心角色职责说明中枢层系统智能体小艺全场景协同大脑集成端云盘古大模型负责意图解析、任务拆解、全局调度、跨设备协调是所有智能体任务的总入口与总统筹终端层领域智能体垂直场景专业执行者如天气、日程、文档、出行等具备专属技能包负责执行具体子任务链路层A2A 通信协议 分布式软总线智能体间的标准化通信底座实现毫秒级双向通信、跨设备数据无缝流转保障协同的实时性生态层开放平台 系统插件提供 50 即插即用系统能力插件地图、支付、OCR 等同时支持第三方开发者上架自定义智能体1.2 AgentFrameworkKit 的分层职责AgentFrameworkKit 隶属于 HMAF 的应用开发套件层自身又分为三层结构从上到下分别对接应用 UI、业务逻辑与底层协议UI 接入层以FunctionComponent声明式组件为核心一行代码即可在应用页面内嵌入智能体对话入口系统接管对话 UI、流式渲染、异常处理应用无需自建聊天界面。控制管理层以AgentController为核心负责智能体可用性检测、会话生命周期管理、事件回调分发、上下文参数注入是应用侧的控制中枢。协议适配层内置 A2A 协议客户端实现向下对接系统 Agent 管理服务负责能力发现、通道建立、数据收发、安全校验的全流程封装应用无需感知底层通信细节。核心设计理念对应用开发者透明。开发者不需要懂智能体调度、A2A 协议、跨设备传输只要传入智能体 ID就能获得完整的系统级智能体能力。二、核心组件深度拆解AgentFrameworkKit 的对外能力主要由三大组件构成分别对应「UI 展示、生命周期管理、服务端承载」三个核心场景。2.1 FunctionComponent声明式智能体 UI 组件这是开发者接触最多的组件也是最容易被误解的组件——它不是一个简单的弹窗控件而是系统智能体 UI 在应用内的渲染载体。核心能力一键拉起指定智能体支持全屏、半屏、悬浮等多种展示形态内置完整的对话 UI、流式输出渲染、加载状态、错误重试等交互逻辑支持向智能体注入应用上下文如当前页面内容、用户信息实现场景化问答提供结果回调智能体执行完成后可将结构化数据返回给应用设计价值将智能体的 UI 交互成本降到近乎为零。应用不需要写聊天界面、不需要处理流式渲染、不需要管理会话状态所有 UI 与交互逻辑由系统统一提供体验与系统小艺完全一致。2.2 AgentController智能体生命周期控制器AgentController 是整个框架的控制中枢负责所有非 UI 的管理能力可用性检测isAgentSupport()检测当前设备、当前账号是否支持指定智能体兼容不支持的设备优雅降级。会话管理创建、销毁、挂起、恢复智能体会话管理会话上下文与生命周期。事件回调提供智能体打开、关闭、出错、任务完成、参数返回等全生命周期事件回调。参数注入向智能体传递初始参数、上下文数据、用户身份信息实现「进入页面即获得场景化服务」的无感体验。2.3 AgentExtensionAbility智能体服务端载体如果说前两个组件是「客户端侧」的接入能力AgentExtensionAbility就是「服务端侧」的智能体载体是提供智能体能力的应用必须实现的组件。它是一种特殊的 ExtensionAbility运行在独立进程中负责接收客户端通过 A2A 协议发来的任务请求执行对应技能逻辑调用自身业务能力将执行结果通过标准化通道返回给调用方处理双向安全认证、流式数据输出、异常报错简单理解客户端用 AgentFrameworkKit 调别人服务端用 AgentExtensionAbility 被别人调。系统小艺、其他应用的智能体都通过这个标准组件对外提供服务。三、核心通信机制A2A 端侧协议全解析系统级智能体之所以能跨应用、跨设备无缝协同核心依赖标准化的A2AAgent-to-Agent通信协议。它解决了过去跨应用智能体对接成本高、协议不统一、安全无保障的行业痛点。3.1 整体架构客户端-代理-服务端三层A2A 通信不是两个智能体直接相连而是通过系统 Agent 管理服务做统一代理调度形成标准的三层架构客户端智能体 → 系统Agent管理服务 → 服务端智能体客户端任务发起方通过 AgentFrameworkKit 发起调用请求系统代理统一管理所有智能体的注册信息负责能力发现、路由调度、安全校验、流量管控服务端能力提供方通过 AgentExtensionAbility 接收并处理任务这种中心化代理设计的优势非常明显智能体之间不需要两两对接只要对接系统标准协议即可安全校验统一在代理层完成避免每个智能体重复实现安全逻辑支持全局调度与负载均衡多设备场景下自动选择最优执行端3.2 完整通信五阶段一次标准的 A2A 跨应用调用从注册到释放共分为五个阶段阶段1能力注册预置阶段提供智能体服务的应用在工程agent_config.json中配置AgentCard描述文件明确定义智能体基本信息名称、描述、图标、唯一 ID技能列表每个技能的 ID、功能描述输入输出 Schema结构化的参数定义包括参数类型、必填项、取值范围应用安装后系统 Agent 管理服务自动读取并注册这些能力形成全局智能体能力目录。关键设计输入 Schema 由系统统一校验。调用方参数不符合 Schema 会直接被系统拦截不需要服务端自己写参数校验逻辑大幅降低重复开发成本。阶段2连接建立客户端发起调用请求后系统 Agent 管理服务根据能力描述匹配到对应的目标智能体唤醒目标应用的 AgentExtensionAbility 组件建立双向 IPC 通信通道跨设备场景下自动切换为分布式软总线通道返回连接句柄给客户端整个建连过程在几十毫秒内完成用户无感知。阶段3安全认证可选对于高敏感场景支持双向安全认证客户端发起认证请求携带自身身份凭证服务端在onAuth()回调中校验身份通过authorize()回复认证结果认证基于设备证书 应用签名双重校验确保通信双方均为可信应用认证失败直接断开连接拒绝数据交互阶段4双向数据通信连接建立后双方进入全双工通信状态客户端通过sendData()向服务端发送任务请求与参数服务端在onData()回调中接收请求执行业务逻辑服务端通过sendData()向客户端返回执行结果支持流式响应SSE适配大模型逐字输出的场景支持任务进度上报、追问澄清、状态同步等复杂交互阶段5连接释放任务完成后客户端主动断开连接系统回收 IPC 通道与进程资源长时间空闲时系统也会自动释放闲置连接避免资源浪费。3.3 跨设备通信软总线底座加持A2A 协议天然支持跨设备调用底层完全基于分布式软总线 2.0 实现同账号可信组网内的设备智能体能力自动共享调用流程与同设备完全一致系统自动判断目标智能体所在设备跨设备数据走软总线高速通道端到端延迟 ≤8ms支持任务接力手机上发起的任务可以流转到平板、车机上继续执行四、系统级智能体端到端执行全链路我们以「用户对小艺说帮我查上海后天的天气并添加到日程提醒」为例完整拆解一次多智能体协同的全流程。意图接收与拆解系统中枢小艺接收用户语音指令大模型解析意图并拆解为两个子任务① 查询上海后天天气 ② 将天气信息添加到日程提醒。能力发现与匹配系统 Agent 管理服务从全局能力目录中匹配到「天气智能体」和「日程智能体」两个服务校验输入输出 Schema 兼容性确认可串联执行。通道建立与第一个任务执行建立与天气智能体的 A2A 通信通道传入「城市上海天数后天」的参数。天气智能体执行查询返回结构化的天气结果。任务串联与第二个任务执行中枢将天气结果作为参数注入到日程智能体的调用请求中建立与日程智能体的通道发起添加日程请求。日程智能体完成日程创建返回执行结果。结果汇总与回复中枢汇总两个智能体的执行结果生成自然语言回复通过语音 卡片形式展示给用户。资源回收任务完成后断开两个智能体的连接释放通道与进程资源本次协同结束。五、全链路安全机制三锁一钥防护体系系统级智能体的安全等级远高于应用内自建智能体整套体系遵循「三锁一钥」安全设计原则身份锁双端身份强校验所有接入生态的智能体必须经过开发者签名 平台审核通信时校验应用签名与设备证书伪造的智能体无法接入系统网络从源头杜绝恶意服务。通信锁全链路加密传输同设备通信走系统安全 IPC 通道跨设备通信走分布式软总线国密加密信道全程数据密文传输中间节点无法窃听。执行锁沙箱隔离最小权限每个智能体运行在独立的沙箱进程中权限最小化只能访问自身业务所需的系统能力无法越权读取用户隐私、访问其他应用数据。数据钥TEE 敏感数据保护用户隐私数据、身份凭证存储在端侧 TEE 安全环境中智能体只能在用户授权后临时访问无法持久化存储、无法上传云端。六、选型对比系统级 Agent vs 应用内自建 Agent很多开发者会困惑什么时候用 AgentFrameworkKit 接入系统智能体什么时候用 AIKit 自建应用内智能体两者定位不同适用场景完全不同。对比维度AgentFrameworkKit 系统级智能体AIKit 自建应用内智能体开发成本极低几行代码接入UI、模型、调度全部由系统提供高需要自建 UI、对接模型、实现工具调用、管理会话生态协同支持跨应用、跨设备多智能体协同可被系统小艺调度仅应用内可用无法与其他应用、系统能力联动数据隐私数据经过系统服务流转遵循系统隐私规范数据完全在应用内可控性更强离线能力依赖云端大模型与平台配置必须联网可完全离线运行基于端侧模型推理能力边界受限于智能体开放的技能与系统插件完全自定义可实现任意业务逻辑适用场景快速接入智能对话、需要跨应用协同、希望被系统生态调度强隐私场景、纯离线需求、高度定制化业务逻辑七、常见踩坑与最佳实践必须联网使用系统级智能体依赖云端大模型与智能体平台配置纯离线环境无法使用。纯离线场景请选择 AIKit 端侧推理方案。包名与 agentId 必须匹配智能体 ID 与应用包名是绑定关系在开放平台注册时的包名必须和实际应用包名一致否则会拉起失败。模拟器不支持调试AgentFrameworkKit 依赖系统智能体服务模拟器无法提供完整能力必须使用真机调试且设备需登录华为账号。不要过度依赖系统智能体做核心业务逻辑系统级智能体定位是生态协同与辅助增强应用核心业务逻辑建议仍由应用自身实现智能体作为入口与辅助能力存在。服务端智能体尽量轻量化AgentExtensionAbility 适合做轻量任务处理重计算、大文件操作建议交由主应用进程完成避免智能体进程内存过高被系统回收。总结AgentFrameworkKit 不是一个简单的聊天 UI 控件而是鸿蒙智能体生态向应用层伸出的标准接口。它的真正价值是让普通应用不用从零搭建大模型、不用自建调度系统、不用对接其他应用就能快速接入整个鸿蒙系统级智能体网络既可以调用其他应用的智能体能力也可以让自身能力被系统小艺调度、被其他应用调用从「独立的应用」变成「全场景智能体生态中的一个节点」。理解这套架构后再去做智能体相关的开发就不会只停留在「加个对话按钮」的表层而是能从生态协同的角度设计更合理的智能体落地方案。
很多开发者对 AgentFrameworkKit 的认知停留在「拉起智能体对话的 UI 组件」但它远不止是一个前端控件——它是鸿蒙系统级智能体生态面向应用层的唯一标准接入入口向下串联着 HMAF 鸿蒙智能体中枢、A2A 标准化通信协议、分布式软总线与全链路安全体系向上为应用提供「零成本接入系统智能体生态」的标准化能力。本文从顶层架构、核心组件、通信协议到全链路执行流程完整拆解 AgentFrameworkKit 的底层设计与系统级智能体的协作逻辑。一、顶层定位HMAF 框架下的应用接入层要理解 AgentFrameworkKit首先要理清鸿蒙智能体的整体架构。鸿蒙 6 起正式落地的HMAFHarmonyOS Mobile Agent Framework鸿蒙智能体框架是操作系统级的智能体中枢采用「中枢-终端-链路-生态」四层架构AgentFrameworkKit 是应用层对接这套体系的封装入口。1.1 HMAF 四层全局架构架构层级核心角色职责说明中枢层系统智能体小艺全场景协同大脑集成端云盘古大模型负责意图解析、任务拆解、全局调度、跨设备协调是所有智能体任务的总入口与总统筹终端层领域智能体垂直场景专业执行者如天气、日程、文档、出行等具备专属技能包负责执行具体子任务链路层A2A 通信协议 分布式软总线智能体间的标准化通信底座实现毫秒级双向通信、跨设备数据无缝流转保障协同的实时性生态层开放平台 系统插件提供 50 即插即用系统能力插件地图、支付、OCR 等同时支持第三方开发者上架自定义智能体1.2 AgentFrameworkKit 的分层职责AgentFrameworkKit 隶属于 HMAF 的应用开发套件层自身又分为三层结构从上到下分别对接应用 UI、业务逻辑与底层协议UI 接入层以FunctionComponent声明式组件为核心一行代码即可在应用页面内嵌入智能体对话入口系统接管对话 UI、流式渲染、异常处理应用无需自建聊天界面。控制管理层以AgentController为核心负责智能体可用性检测、会话生命周期管理、事件回调分发、上下文参数注入是应用侧的控制中枢。协议适配层内置 A2A 协议客户端实现向下对接系统 Agent 管理服务负责能力发现、通道建立、数据收发、安全校验的全流程封装应用无需感知底层通信细节。核心设计理念对应用开发者透明。开发者不需要懂智能体调度、A2A 协议、跨设备传输只要传入智能体 ID就能获得完整的系统级智能体能力。二、核心组件深度拆解AgentFrameworkKit 的对外能力主要由三大组件构成分别对应「UI 展示、生命周期管理、服务端承载」三个核心场景。2.1 FunctionComponent声明式智能体 UI 组件这是开发者接触最多的组件也是最容易被误解的组件——它不是一个简单的弹窗控件而是系统智能体 UI 在应用内的渲染载体。核心能力一键拉起指定智能体支持全屏、半屏、悬浮等多种展示形态内置完整的对话 UI、流式输出渲染、加载状态、错误重试等交互逻辑支持向智能体注入应用上下文如当前页面内容、用户信息实现场景化问答提供结果回调智能体执行完成后可将结构化数据返回给应用设计价值将智能体的 UI 交互成本降到近乎为零。应用不需要写聊天界面、不需要处理流式渲染、不需要管理会话状态所有 UI 与交互逻辑由系统统一提供体验与系统小艺完全一致。2.2 AgentController智能体生命周期控制器AgentController 是整个框架的控制中枢负责所有非 UI 的管理能力可用性检测isAgentSupport()检测当前设备、当前账号是否支持指定智能体兼容不支持的设备优雅降级。会话管理创建、销毁、挂起、恢复智能体会话管理会话上下文与生命周期。事件回调提供智能体打开、关闭、出错、任务完成、参数返回等全生命周期事件回调。参数注入向智能体传递初始参数、上下文数据、用户身份信息实现「进入页面即获得场景化服务」的无感体验。2.3 AgentExtensionAbility智能体服务端载体如果说前两个组件是「客户端侧」的接入能力AgentExtensionAbility就是「服务端侧」的智能体载体是提供智能体能力的应用必须实现的组件。它是一种特殊的 ExtensionAbility运行在独立进程中负责接收客户端通过 A2A 协议发来的任务请求执行对应技能逻辑调用自身业务能力将执行结果通过标准化通道返回给调用方处理双向安全认证、流式数据输出、异常报错简单理解客户端用 AgentFrameworkKit 调别人服务端用 AgentExtensionAbility 被别人调。系统小艺、其他应用的智能体都通过这个标准组件对外提供服务。三、核心通信机制A2A 端侧协议全解析系统级智能体之所以能跨应用、跨设备无缝协同核心依赖标准化的A2AAgent-to-Agent通信协议。它解决了过去跨应用智能体对接成本高、协议不统一、安全无保障的行业痛点。3.1 整体架构客户端-代理-服务端三层A2A 通信不是两个智能体直接相连而是通过系统 Agent 管理服务做统一代理调度形成标准的三层架构客户端智能体 → 系统Agent管理服务 → 服务端智能体客户端任务发起方通过 AgentFrameworkKit 发起调用请求系统代理统一管理所有智能体的注册信息负责能力发现、路由调度、安全校验、流量管控服务端能力提供方通过 AgentExtensionAbility 接收并处理任务这种中心化代理设计的优势非常明显智能体之间不需要两两对接只要对接系统标准协议即可安全校验统一在代理层完成避免每个智能体重复实现安全逻辑支持全局调度与负载均衡多设备场景下自动选择最优执行端3.2 完整通信五阶段一次标准的 A2A 跨应用调用从注册到释放共分为五个阶段阶段1能力注册预置阶段提供智能体服务的应用在工程agent_config.json中配置AgentCard描述文件明确定义智能体基本信息名称、描述、图标、唯一 ID技能列表每个技能的 ID、功能描述输入输出 Schema结构化的参数定义包括参数类型、必填项、取值范围应用安装后系统 Agent 管理服务自动读取并注册这些能力形成全局智能体能力目录。关键设计输入 Schema 由系统统一校验。调用方参数不符合 Schema 会直接被系统拦截不需要服务端自己写参数校验逻辑大幅降低重复开发成本。阶段2连接建立客户端发起调用请求后系统 Agent 管理服务根据能力描述匹配到对应的目标智能体唤醒目标应用的 AgentExtensionAbility 组件建立双向 IPC 通信通道跨设备场景下自动切换为分布式软总线通道返回连接句柄给客户端整个建连过程在几十毫秒内完成用户无感知。阶段3安全认证可选对于高敏感场景支持双向安全认证客户端发起认证请求携带自身身份凭证服务端在onAuth()回调中校验身份通过authorize()回复认证结果认证基于设备证书 应用签名双重校验确保通信双方均为可信应用认证失败直接断开连接拒绝数据交互阶段4双向数据通信连接建立后双方进入全双工通信状态客户端通过sendData()向服务端发送任务请求与参数服务端在onData()回调中接收请求执行业务逻辑服务端通过sendData()向客户端返回执行结果支持流式响应SSE适配大模型逐字输出的场景支持任务进度上报、追问澄清、状态同步等复杂交互阶段5连接释放任务完成后客户端主动断开连接系统回收 IPC 通道与进程资源长时间空闲时系统也会自动释放闲置连接避免资源浪费。3.3 跨设备通信软总线底座加持A2A 协议天然支持跨设备调用底层完全基于分布式软总线 2.0 实现同账号可信组网内的设备智能体能力自动共享调用流程与同设备完全一致系统自动判断目标智能体所在设备跨设备数据走软总线高速通道端到端延迟 ≤8ms支持任务接力手机上发起的任务可以流转到平板、车机上继续执行四、系统级智能体端到端执行全链路我们以「用户对小艺说帮我查上海后天的天气并添加到日程提醒」为例完整拆解一次多智能体协同的全流程。意图接收与拆解系统中枢小艺接收用户语音指令大模型解析意图并拆解为两个子任务① 查询上海后天天气 ② 将天气信息添加到日程提醒。能力发现与匹配系统 Agent 管理服务从全局能力目录中匹配到「天气智能体」和「日程智能体」两个服务校验输入输出 Schema 兼容性确认可串联执行。通道建立与第一个任务执行建立与天气智能体的 A2A 通信通道传入「城市上海天数后天」的参数。天气智能体执行查询返回结构化的天气结果。任务串联与第二个任务执行中枢将天气结果作为参数注入到日程智能体的调用请求中建立与日程智能体的通道发起添加日程请求。日程智能体完成日程创建返回执行结果。结果汇总与回复中枢汇总两个智能体的执行结果生成自然语言回复通过语音 卡片形式展示给用户。资源回收任务完成后断开两个智能体的连接释放通道与进程资源本次协同结束。五、全链路安全机制三锁一钥防护体系系统级智能体的安全等级远高于应用内自建智能体整套体系遵循「三锁一钥」安全设计原则身份锁双端身份强校验所有接入生态的智能体必须经过开发者签名 平台审核通信时校验应用签名与设备证书伪造的智能体无法接入系统网络从源头杜绝恶意服务。通信锁全链路加密传输同设备通信走系统安全 IPC 通道跨设备通信走分布式软总线国密加密信道全程数据密文传输中间节点无法窃听。执行锁沙箱隔离最小权限每个智能体运行在独立的沙箱进程中权限最小化只能访问自身业务所需的系统能力无法越权读取用户隐私、访问其他应用数据。数据钥TEE 敏感数据保护用户隐私数据、身份凭证存储在端侧 TEE 安全环境中智能体只能在用户授权后临时访问无法持久化存储、无法上传云端。六、选型对比系统级 Agent vs 应用内自建 Agent很多开发者会困惑什么时候用 AgentFrameworkKit 接入系统智能体什么时候用 AIKit 自建应用内智能体两者定位不同适用场景完全不同。对比维度AgentFrameworkKit 系统级智能体AIKit 自建应用内智能体开发成本极低几行代码接入UI、模型、调度全部由系统提供高需要自建 UI、对接模型、实现工具调用、管理会话生态协同支持跨应用、跨设备多智能体协同可被系统小艺调度仅应用内可用无法与其他应用、系统能力联动数据隐私数据经过系统服务流转遵循系统隐私规范数据完全在应用内可控性更强离线能力依赖云端大模型与平台配置必须联网可完全离线运行基于端侧模型推理能力边界受限于智能体开放的技能与系统插件完全自定义可实现任意业务逻辑适用场景快速接入智能对话、需要跨应用协同、希望被系统生态调度强隐私场景、纯离线需求、高度定制化业务逻辑七、常见踩坑与最佳实践必须联网使用系统级智能体依赖云端大模型与智能体平台配置纯离线环境无法使用。纯离线场景请选择 AIKit 端侧推理方案。包名与 agentId 必须匹配智能体 ID 与应用包名是绑定关系在开放平台注册时的包名必须和实际应用包名一致否则会拉起失败。模拟器不支持调试AgentFrameworkKit 依赖系统智能体服务模拟器无法提供完整能力必须使用真机调试且设备需登录华为账号。不要过度依赖系统智能体做核心业务逻辑系统级智能体定位是生态协同与辅助增强应用核心业务逻辑建议仍由应用自身实现智能体作为入口与辅助能力存在。服务端智能体尽量轻量化AgentExtensionAbility 适合做轻量任务处理重计算、大文件操作建议交由主应用进程完成避免智能体进程内存过高被系统回收。总结AgentFrameworkKit 不是一个简单的聊天 UI 控件而是鸿蒙智能体生态向应用层伸出的标准接口。它的真正价值是让普通应用不用从零搭建大模型、不用自建调度系统、不用对接其他应用就能快速接入整个鸿蒙系统级智能体网络既可以调用其他应用的智能体能力也可以让自身能力被系统小艺调度、被其他应用调用从「独立的应用」变成「全场景智能体生态中的一个节点」。理解这套架构后再去做智能体相关的开发就不会只停留在「加个对话按钮」的表层而是能从生态协同的角度设计更合理的智能体落地方案。
