鸿蒙 NEXT 也能接 MCP？用 ArkTS 跑通 AI Agent 工具链

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

标签：HarmonyOS AI Agent MCP ArkTS DevEco Studio

📖 阅读提示

如果你已经会在 Cursor、Claude Code 里接 MCP，下一步很自然：鸿蒙原生 App 能不能也让 AI Agent 调工具？

结论先说：能，但不要把 MCP 直接理解成"在手机里塞一个聊天框"。更稳的做法是：

ArkTS 只做 薄 UI：输入、消息列表、加载态、权限提示
Agent 服务负责 规划与工具调用
MCP Server 把本地/后端能力包装成标准工具
实际敏感的数据，再交给端侧模型或本地工具处理

前言：别只做聊天框，Agent 的价值在"能办事"

很多 AI Demo 卡在一个地方：界面很好看，回答也流畅，但它只能"说"，不能"做"。

比如用户在鸿蒙 App 里问：

帮我查一下本周学习计划，顺便把没完成的任务列出来。

普通 ChatBot 只能猜。Agent 要做的是：

识别用户意图
查询本地计划或后端接口
汇总结果
必要时继续追问或执行操作

这就是 MCP 值得接入的地方：让模型以统一协议调用工具，而并非把业务逻辑写死在提示词里。

1. 鸿蒙 Agent ≠ 只有一个聊天框

1.1 推荐三层拆分

层	职责	常见技术
交互层	对话 UI、多轮状态、权限提示	ArkUI、Navigation
推理层	规划、ReAct、记忆	云端大模型 API / 端侧小模型
工具层	可调用能力集合	MCP Server、HarmonyOS Ability、分布式接口

MCP 的价值在 工具层标准化：同一套"工具描述 + 调用协议"，换模型不必重写业务接口。

1.2 和 HMAF 的关系（怎么理解）

华为公开的 HMAF（鸿蒙智能体框架） 方向，是把端侧算力、系统能力与智能体编排结合起来。可以先这样理解：

系统侧：提供更顺的 Agent 生命周期、设备协同
开发侧 ：仍需要你自己的 工具定义（很多场景仍可用 MCP 思路封装 HTTP/本地服务）

不必二选一：HMAF 管「住哪儿跑」 ，MCP 管「工具长什么样」。

2. MCP 接入路线（DevEco 工程向）

2.1 最小链路：ArkTS → Agent 服务 → MCP Server

先列工具清单：读文件、查配置、调鸿蒙系统 API、访问业务后端
实现 MCP Server（Node / Python 最常见；与 App 可同机或局域网）
App 内推理服务 通过 HTTP/Socket 调 MCP，或经中间层聚合
ArkTS UI 只关心会话与结果展示，不直接堆业务逻辑

注意：下面是工程骨架示意，方便理解调用边界。真实项目要补权限、鉴权、超时、错误码和真机测试。

2.2 第一步：先把工具定义清楚

不要一上来就接大模型。先把"模型能调用什么"写成工具表。

json 复制代码

{
  "name": "search_study_plan",
  "description": "查询用户本周学习计划和完成状态",
  "inputSchema": {
    "type": "object",
    "properties": {
      "week": { "type": "string", "description": "周标识，例如 2026-W21" }
    },
    "required": ["week"]
  }
}

这一步非常关键。工具描述越清楚，模型越少乱调。

2.3 第二步：MCP Server 包装真实能力

Node / Python 都可以。核心不是语言，而是把业务能力包装成稳定接口。

typescript 复制代码

// 示意：MCP Server 内部注册一个查询学习计划的工具
server.tool(
  "search_study_plan",
  {
    week: z.string()
  },
  async ({ week }) => {
    const tasks = await queryStudyPlanFromDb(week);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(tasks)
        }
      ]
    };
  }
);

真实落地时，我建议把工具分成三类：

类型	示例	风险
只读工具	查询计划、读取配置	低
写入工具	新增任务、修改日程	中，需要二次确认
敏感工具	通讯录、定位、文件	高，必须权限前置

2.4 第三步：ArkTS 不直接调工具，只调 Agent 服务

typescript 复制代码

// ArkTS 侧只负责把用户问题交给 Agent 服务
async function askAgent(prompt: string): Promise<string> {
  const response = await http.createHttp().request(
    'http://127.0.0.1:3000/agent/run',
    { method: http.RequestMethod.POST, extraData: JSON.stringify({ prompt }) }
  );
  return JSON.parse(response.result as string).answer;
}

Agent 服务做三件事：

接收 ArkTS 的用户输入
让模型判断是否需要调用工具
把 MCP 工具结果整理成 App 可展示的回答

这样做的好处是：ArkTS 不背复杂推理逻辑，MCP Server 不关心 UI，Agent 服务负责中间编排。

2.5 返回结构也要稳定

避免直接把大模型原文扔给页面。建议 Agent 服务统一返回：

json 复制代码

{
  "answer": "你本周还有 3 个学习任务未完成，其中 ArkTS 状态管理优先级最高。",
  "actions": [
    { "type": "open_page", "target": "StudyPlanPage" }
  ],
  "toolCalls": [
    { "name": "search_study_plan", "status": "success" }
  ]
}

页面只消费 answer 和 actions，调试时再看 toolCalls。

2.6 三个常见坑

坑	现象	建议
工具描述含糊	模型乱调、死循环	每个 tool 写清入参、反例
主线程调网络	UI 卡顿	Agent 推理放 Worker / 后台服务
权限未前置	调用失败难排查	敏感能力先弹窗授权，再暴露给工具

3. 开源参考：鸿蒙上的 Agent 框架

社区已有 JiuwenClaw-on-OpenHarmony 等实践，方向是：在 OpenHarmony / HarmonyOS NEXT 场景里探索 ReAct、工具调用、记忆与任务调度。适合作为"工具层如何拆"的参考，而并非照搬到生产。

阅读重点：

工具注册表如何映射到鸿蒙能力
记忆存在哪（Preferences / RDB）
失败重试与超时策略

4. 和「端侧大模型」如何配合？

下一篇（002）会写 HarmonyOS 5 端侧问答。本篇只划边界：

场景	更合适方案
强隐私、弱网、简单问答	端侧小模型 + 本地 RAG
复杂规划、多工具编排	云端模型 + MCP 工具链
既要隐私又要工具	端侧模型做意图分类，敏感数据本地工具处理

我的建议是：不要一开始就追求"全端侧 Agent"。

更现实的组合是：

敏感文本：端侧处理
工具编排：云端或局域网 Agent 服务处理
写入动作：App 侧弹窗二次确认
调用日志：本地保留，便于排查模型误调

5. 跑通前检查清单

工具是否分级：只读 / 写入 / 敏感
ArkTS 是否只负责 UI 与请求封装
Agent 服务是否有超时、重试、错误码
写入动作是否需要二次确认
敏感能力是否先授权，再暴露给工具
是否记录 toolCalls，方便排查模型误调

6. 下一步怎么做

鸿蒙开发 AI Agent，不要从"聊天框"开始，而要从 工具链 开始。

我的推荐架构很简单：

ArkTS 薄 UI + Agent 编排服务 + MCP 工具层

这样既能复用 MCP 生态，又不会把推理、权限、业务逻辑全部塞进页面。后面如果接入端侧大模型，也可以让端侧模型处理敏感问答，让 MCP 负责复杂工具编排。

📚 参考来源

作者：张大鹏｜来源：大鹏AI教育
标签：AI · 鸿蒙 · HarmonyOS · MCP · Agent
原创内容，转载需授权

万事如意，吉祥如意