HarmonyOS NEXT API26（鸿蒙7）统一推出双路线轻量化智能体开发，彻底解决传统AI集成成本高、对话UI重复开发、跨应用智能体互通难的痛点：

1. 轻量化接入（零AI开发）：@kit.AgentFrameworkKit，一行UI组件嵌入已上架智能体，无需训练、无需本地推理，适合业务快速集成对话助手；
2. 轻量化自建智能体（端侧A2A）：AgentExtensionAbility，几行代码实现本地技能智能体，支持跨应用调用、系统小艺唤醒，适合自有业务工具型Agent。
   

本文分两条实战路线，从架构、配置、完整代码、避坑全流程落地，零基础可直接复用。

一、鸿蒙7 Agent整体架构分层

三层技术栈

1. 底层HMAF鸿蒙智能体框架（系统内核）
   负责自然语言意图识别、会话上下文管理、流式输出、A2A跨智能体通信、设备安全校验，开发者无需感知底层逻辑。
2. 应用开发层两套套件
   • @kit.AgentFrameworkKit：客户端接入，内置对话UI、会话控制器，快速拉起平台上架智能体（轻量化首选）；
   • @kit.AbilityKit 内置Agent扩展：服务端自建Agent，AgentExtensionAbility 实现自有技能，对外提供智能体服务。
3. 生态层小艺开放平台
   注册智能体、生成agentId、配置技能描述、上架分发，支持系统全局语音唤起。

两条开发路线选型对比

开发路线	套件	开发成本	适用场景
快速接入第三方智能体	AgentFrameworkKit	极低（10行UI代码）	商城客服、健康问答、知识库助手、通用对话
自建本地业务智能体	AgentExtensionAbility	低（纯业务逻辑）	本地工具、跨应用协同、系统语音唤起、离线技能

二、路线一：轻量化快速接入（FunctionComponent零UI开发）

2.1 前置准备

1. 前往小艺开放平台创建智能体，审核通过获取唯一agentId；
2. SDK版本：API26 HarmonyOS NEXT 7.0；
3. 网络权限声明（智能体需要联网推理）。

module.json5 权限配置

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:agent_network",
    "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
  }
]

2.2 完整页面实战代码

import { FunctionComponent, FunctionController, AgentController } from '@kit.AgentFrameworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';

const TAG = "LightAgentDemo";
const DOMAIN = 0x0002;

@Entry
@ComponentV2
struct AgentQuickPage {
  // 从小艺开放平台获取你的智能体ID
  private readonly AGENT_ID: string = "agentproxy_xxxxxx";
  // 智能体控制器
  private funcController: FunctionController = new FunctionController();
  // 智能体是否可用
  @State agentAvailable: boolean = false;

  aboutToAppear() {
    this.checkAgentSupport();
  }

  /** 校验当前设备是否支持该智能体 */
  private async checkAgentSupport() {
    const ctx = getContext(this) as common.UIAbilityContext;
    try {
      const support = await AgentController.isAgentSupport(ctx, this.AGENT_ID);
      this.agentAvailable = support;
      hilog.info(DOMAIN, TAG, `智能体可用性：${support}`);
    } catch (err)
      const e = err as BusinessError;
      hilog.error(DOMAIN, TAG, `校验失败 code:${e.code} msg:${e.message}`);
    }
  }

  build() {
    Column({ space: 24 }) {
      Text("轻量化智能体快速接入演示")
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .width("90%")
        .margin({ top: 30 });

      if (!this.agentAvailable) {
        Text("当前设备不支持该智能体，请检查网络/agentId")
          .fontColor("#F04142")
          .fontSize(14);
      } else {
        // 核心：FunctionComponent 内置对话弹窗，无需自定义UI
        FunctionComponent({
          agentId: this.AGENT_ID,
          // 自定义对话初始提示词
          prompt: "你是专属工具助手，仅回答应用内相关问题",
          // 会话打开回调
          onOpen: () => {
            hilog.info(DOMAIN, TAG, "智能体对话窗口已打开");
          },
          // 会话关闭回调
          onClose: () => {
            hilog.info(DOMAIN, TAG, "对话窗口关闭");
          },
          // 异常捕获
          onError: (err: BusinessError) => {
            hilog.error(DOMAIN, TAG, `智能体异常：${err.code} ${err.message}`);
          }
        })
        .width("90%")
        .height(52)
        .borderRadius(26)
        .backgroundColor("#0A59F7");
      }

      Blank();
      Text("💡 点击按钮自动拉起完整对话界面，支持多轮、流式输出、语音输入")
        .fontSize(12)
        .fontColor("#888888")
        .margin({ bottom: 40 });
    }
    .width("100%")
    .height("100%")
    .backgroundColor("#F8F9FA");
  }
}

2.3 核心能力说明

1. 零对话UI开发：FunctionComponent 内置系统标准对话弹窗，自带文本输入、语音、流式打字动画、历史会话；
2. 上下文自动托管：系统持久化会话记忆，退出重进保留对话；
3. 跨设备同步：超级终端下，手机/平板/PC共享同一套智能体会话；
4. 参数自定义：支持传入初始prompt、会话隔离标识、用户身份标签。

三、路线二：自建轻量化本地智能体 AgentExtensionAbility（A2A跨应用）

适合需要本地离线技能、被其他应用调用、系统小艺语音唤起场景，无需上架平台，纯本地运行。

3.1 工程目录创建

1. 新建ets/agentext/AgentExtAbility.ets；
2. module.json5注册AgentExtensionAbility；
3. 新增agent_config.json描述智能体技能卡片。

1）module.json5 注册扩展能力

"extensionAbilities": [
  {
    "name": "AgentExtAbility",
    "srcEntry": "./ets/agentext/AgentExtAbility.ets",
    "type": "agent",
    "exported": true,
    "description": "本地工具智能体",
    "metadata": [
      {
        "name": "agent_config",
        "value": "$profile:agent_config.json"
      }
    ]
  }
]

2）agent_config.json 智能体技能配置（核心）

{
  "agentCards": [
    {
      "agentId": "local_tool_agent_001",
      "name": "本地工具助手",
      "description": "本地计算、备忘录查询工具智能体",
      "version": "1.0.0",
      "capabilities": {
        "streaming": true
      },
      "skills": [
        {
          "id": "calc_num",
          "name": "数字计算",
          "description": "加减乘除四则运算",
          "examples": ["100+20等于多少","30*5"]
        },
        {
          "id": "get_note",
          "name": "查询备忘录",
          "description": "读取本地备忘录内容",
          "examples": ["查看我的备忘录","备忘录第一条是什么"]
        }
      ]
    }
  ]
}

3.2 AgentExtensionAbility 服务端完整代码（自建智能体逻辑）

import { AgentExtensionAbility, common, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = "LocalAgentService";
const DOMAIN = 0x0003;

export default class AgentExtAbility extends AgentExtensionAbility {
  onCreate(): void {
    hilog.info(DOMAIN, TAG, "本地智能体服务启动");
  }

  // 客户端发起连接，授权校验
  onAuth(proxy: common.AgentHostProxy): void {
    // 简易授权：校验调用方包名，仅允许本应用调用
    const callerBundle = proxy.getCallerBundleName();
    if (callerBundle === "com.example.agentdemo") {
      proxy.authorize("success");
    } else {
      proxy.authorize("deny");
    }
  }

  // 接收客户端指令，执行业务技能逻辑
  onData(proxy: common.AgentHostProxy, rawInput: string): void {
    hilog.info(DOMAIN, TAG, `收到用户指令：${rawInput}`);
    let reply = this.handleSkill(rawInput);
    // 回传结果给客户端
    proxy.sendData(reply);
  }

  // 技能分发逻辑：轻量化本地业务处理
  private handleSkill(input: string): string {
    // 1. 四则计算技能
    if (/[\d\+\-\*\/]/.test(input)) {
      try {
        const res = eval(input.replace(/[^0-9\+\-\*\/]/g, ""));
        return `计算结果：${res}`;
      } catch {
        return "算式解析失败，请输入合法数字运算";
      }
    }
    // 2. 备忘录查询技能
    if (input.includes("备忘录")) {
      return "你的备忘录：1. 下午3点会议；2. 提交开发文档";
    }
    // 默认回复
    return "暂未识别该指令，支持计算、备忘录查询";
  }

  onDestroy(): void {
    hilog.info(DOMAIN, TAG, "本地智能体服务销毁");
  }
}

3.3 客户端调用本地自建智能体代码

import { common, wantAgent } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = "AgentClient";
@Entry
@ComponentV2
struct LocalAgentClientPage {
  @State inputText: string = "";
  @State replyText: string = "";
  private agentProxy: common.AgentHostProxy | null = null;

  aboutToDisappear() {
    this.disconnectAgent();
  }

  // 连接本地自建Agent服务
  async connectAgent() {
    const want = {
      bundleName: "com.example.agentdemo",
      abilityName: "AgentExtAbility"
    };
    try {
      this.agentProxy = await wantAgent.connectAgent(want, {
        onConnect: (proxy) => {
          hilog.info(0x0004, TAG, "智能体连接成功");
          // 监听服务端返回数据
          proxy.on("data", (msg: string) => {
            this.replyText = msg;
          });
        },
        onDisconnect: () => {
          this.agentProxy = null;
          promptAction.showToast({ message: "智能体断开连接" });
        }
      });
    } catch (err)
      promptAction.showToast({ message: "连接智能体失败" });
    }
  }

  // 发送指令给本地智能体
  sendCommand() {
    if (!this.agentProxy || !this.inputText.trim()) return;
    this.agentProxy.sendData(this.inputText);
  }

  disconnectAgent() {
    if (this.agentProxy) wantAgent.disconnectAgent(this.agentProxy);
  }

  build() {
    Column({ space: 20 }) {
      Text("本地自建智能体（离线轻量化）")
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .width("90%")
        .margin({ top: 20 });

      Row() {
        TextInput({ text: this.inputText })
          .layoutWeight(1)
          .height(44)
          .onChange(v => this.inputText = v);
        Button("发送")
          .height(44)
          .onClick(() => this.sendCommand());
      }
      .width("90%");

      Button("连接本地智能体")
        .width("90%")
        .height(48)
        .onClick(() => this.connectAgent());

      if (this.replyText) {
        Text(`智能体回复：\n${this.replyText}`)
          .width("90%")
          .padding(16)
          .backgroundColor("#F0F7FF")
          .borderRadius(12);
      }
    }
    .width("100%")
    .height("100%")
    .padding({ bottom: 30 });
  }
}

四、两条路线选型最佳实践

场景1：快速搭建对话客服、知识库问答

选 AgentFrameworkKit + FunctionComponent
优势：无需开发AI逻辑、自带对话UI、支持语音输入、云端大模型能力，开发仅10行代码。

场景2：本地离线工具、跨应用调用、系统语音唤起

选 AgentExtensionAbility 自建本地智能体
优势：纯本地运行、无网络依赖、可被小艺全局唤醒、支持A2A跨应用智能体互通，隐私性强。

五、高频踩坑避坑指南

路线一（FunctionComponent）坑点

1. agentId无效，组件不显示
   • 原因：智能体未在小艺平台审核上架；包名与平台绑定不一致；网络无权限。
   • 解决：核对平台申请的agentId，添加INTERNET权限，真机联网测试。
2. 弹窗打不开、直接报错
   • 先调用AgentController.isAgentSupport前置校验，不要直接渲染组件。
3. 会话不保存历史
   • 系统默认持久化会话，如需隔离多用户，传入唯一sessionId区分会话。

路线二（AgentExtensionAbility）坑点

1. connectAgent连接失败
   • module.json5未配置exported:true；agent_config.json格式错误；包名不匹配。
2. 收不到onData回调
   • 客户端连接成功后，必须等待onConnect回调完成再调用sendData。
3. 其他应用无法调用智能体
   • onAuth授权逻辑放开允许的调用方包名，不要仅放行自身应用。
4. 模拟器无法调试
   Agent扩展依赖系统智能体运行时，必须真机测试。

六、性能轻量化优化要点

1. 会话复用：页面常驻复用FunctionController/AgentHostProxy，不要频繁销毁重建；
2. 本地Agent轻量化：技能逻辑避免重型计算，复杂任务异步子线程处理；
3. 流式输出：配置capabilities.streaming:true，分段返回文本，减少等待卡顿；
4. 权限最小化：仅申请INTERNET，本地智能体无需额外隐私权限；
5. 内存回收：页面aboutToDisappear主动断开Agent连接，防止进程泄漏。

总结

鸿蒙7 Agent轻量化开发分为云端快速接入和本地自建智能体两条独立路线，覆盖绝大多数AI交互场景：

• 对外对话、知识库场景用AgentFrameworkKit，极致轻量化，零UI开发；
• 本地工具、跨应用协同、离线场景用AgentExtensionAbility，完全自主可控。
  两套方案均大幅降低传统AI智能体开发成本，依托HMAF底层框架托管会话、意图、流式输出，开发者仅需聚焦业务技能逻辑。