鸿蒙Agent架构落地:手把手教你用小艺搭一个能自动订外卖的智能体

一、为什么"订外卖"这件事值得搬上鸿蒙 Agent

HDC 2026 上华为把"意图即服务"摆到了系统级位置：2100 多项系统能力被全面 Skill 化，500 多家伙伴的 Skills 接入，2000 多个智能体上架，开放生态里已经有 50 多家头部伙伴的智能体在联调。一句话总结，鸿蒙正在把"打开 App 找服务"的旧链路，改写成"说出意图、Agent 替你调度"的链路。

这次升级的核心差异在于"系统级"三个字——小艺不是 App 抽屉里的一个聊天机器人，而是把调度能力下沉到操作系统底层。从"用户→找应用→找服务"的三跳范式，变成"用户说一句话→Agent 串起多个 Skill 直接把事办了"的一跳范式。

而"自动订外卖"恰好是检验这套链路最干净的样本——它同时考验了四个层面：

• • 系统级意图识别：理解"帮我订一份 30 元左右的川式盖码饭，少辣，送到公司"
• • 多 Skill 串接：位置服务 + 商家检索 + 菜单匹配 + 下单支付 + 状态回传
• • 跨设备协同：手机上开口、车机上确认、手表上看配送进度
• • 安全护栏：支付必须用户手动确认、本地优先、敏感数据不外发

把这四件事拆开讲清楚，就掌握了 HMAF（Harmony Agent Framework，鸿蒙智能体框架）落地的主线。下面进入实操。

二、先把三层架构理清：HMAF、Agent Framework Kit、A2A

很多开发者在第一关就被三个名词搞混，文档翻错页是常事。把它们分层放好，就能选对入口：

经验法则：做 App 内智能助手，从 Agent Framework Kit 入手；要做跨 App 协同，再补 A2A 与 Agent Card。下面要搭的"订外卖 Agent"，主战场在 Kit 层，但需要 A2A 把"位置 Skill"和"商家 Skill"串起来。

从 API 版本看，Agent Framework Kit 需要 API 20+（对应 HarmonyOS 6.0）。如果你的工程还在 API 18 或 19，可以先把代码结构按 Kit 接口写好，用本地模拟 handler 跑通，等升级到 6.0 后再打开真机调试。这种"先骨架后填肉"的写法，能把联调周期从两周压到一周。

三、Agent Card：让别人（或小艺）能找到你

HarmonyOS 6.0（API 20+）支持通过 /.well-known/agent-card.json 自动注册与发现——相当于 A2A 生态的"黄页条目"。Agent Card 解决的是"被找到"，Kit 解决的是"被调用"，两件事分阶段做，但都要做。

最小可用的 Agent Card JSON 结构示意：

{
  "name": "OrderLunchAgent",
  "description": "根据用户口味、预算和位置自动搜索并下单午餐外卖",
  "url": "https://your-app.example/agent",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "tools": true
  },
  "skills": [
    {
      "id": "search_restaurant",
      "name": "搜索附近餐厅",
      "description": "按位置、口味、价格区间返回候选商家列表"
    },
    {
      "id": "place_order",
      "name": "下单",
      "description": "向指定商家提交订单并发起支付"
    }
  ]
}

三个最易踩的坑：第一，name 字段必须和 ArkTS 侧 handler 名严格一致，否则调用静默失败；第二，description 不能笼统写"处理外卖请求"，要写清输入输出边界，模型才会正确路由；第三，skills 数组里每个 id 要唯一，后续 Tool 注册时按这个 id 绑定。

值得一提的是，Agent Card 同样支持 mTLS 鉴权字段 securitySchemes。如果你的 Tool 涉及支付或读取用户隐私数据，务必在 Card 里声明鉴权方式，否则小艺在路由时会把这类 Agent 标为低优先级，甚至不展示给用户。

四、Tool 定义：把"能办事"写进 Agent，而不是写进 Prompt

Agent 和普通 ChatBot 的分水岭在工具层。HMAF 推荐把业务能力封装成 Tool / Function，由 Agent 运行时调度，而不是把接口细节全塞进 system prompt。把业务塞进 Prompt，是 Agent 项目 80% 返工的根源——一旦业务字段调整，整段 Prompt 都要重写；而用 Tool，模型通过 schema 自动理解入参，改字段只改 schema 不改 Prompt。

4.1 工具定义三要素

4.2 搜索餐厅的 Tool Schema

{
  "name": "searchRestaurant",
  "description": "查询指定位置附近、口味与价格区间匹配的餐厅，返回商家名、评分、配送时长",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "经纬度坐标，如 39.9087,116.3975" },
      "cuisine": { "type": "string", "description": "菜系类型，如 川菜、湘菜、日料" },
      "maxPrice": { "type": "integer", "description": "人均价格上限，单位元" },
      "radius": { "type": "integer", "description": "搜索半径，单位米，默认 1500" }
    },
    "required": ["location", "cuisine"]
  }
}

schema 里有几条经验值得写进团队 Wiki：第一，description 字段尽量控制在 30–80 字，太短模型抓不到重点，太长会污染上下文窗口；第二，枚举类字段（如 cuisine）用 enum 而不是 string，模型选错的概率能从 25% 降到 5% 以下；第三，数值字段一定要带单位说明，比如"价格上限，单位元"，否则模型会用 token 数、角、分各种单位来理解。

4.3 ArkTS 侧绑定 handler

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

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

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

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

  aboutToAppear() {
    this.controller.registerTool('searchRestaurant', async (params: Record<string, string>) => {
      hilog.info(DOMAIN, TAG, 'searchRestaurant params=%{public}s', JSON.stringify(params));
      const result = await this.fetchRestaurants(
        params.location,
        params.cuisine,
        Number(params.maxPrice ?? 50),
        Number(params.radius ?? 1500)
      );
      hilog.info(DOMAIN, TAG, 'searchRestaurant result count=%{public}d', result.length);
      return JSON.stringify(result);
    });

    this.controller.registerTool('placeOrder', async (params: Record<string, string>) => {
      hilog.info(DOMAIN, TAG, 'placeOrder shop=%{public}s amount=%{public}s', params.shopId, params.amount);
      // 关键：支付环节必须弹出用户确认
      const confirmed = await this.askUserConfirm(params);
      if (!confirmed) return JSON.stringify({ status: 'cancelled' });
      const orderId = await this.submitOrder(params);
      return JSON.stringify({ status: 'ok', orderId });
    });
  }

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

关键原则：handler 里只做"参数校验 → 调用业务 → 返回结构化 JSON"，规划与多轮推理交给 Agent 运行时。一个常见反例是在 handler 里写"如果用户预算不够，就推荐更便宜的"——这种逻辑应该交给模型，handler 只负责把候选商家返回，让模型基于工具结果做最终决策。

五、用 hilog 把 Agent 链路"黑盒变透明"

Agent 联调最难的是：UI 显示"正在思考"，但不知道卡在哪一步——是模型没返回？工具没触发？还是 handler 抛异常？根据实战数据，70% 的 Agent 联调问题都能在 hilog 日志里直接定位。

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

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

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

// 检查点 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', String(result).slice(0, 200));

真机日志过滤命令：

hdc shell hilog -T OrderLunchAgent

推荐按这个顺序联调：

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

实测中最常见的三个翻车点：工具 description 太模糊 → 模型不调用，hilog 里只有对话没有 toolCall；handler 返回非 JSON 字符串 → Agent 运行时解析失败，UI 显示空白；权限未声明 → handler 调本地数据时抛异常，但 UI 只显示"服务异常"。把这三类问题前置到自测脚本里，能把联调阶段来回打断的次数减少一半以上。

六、把"订外卖"Agent 串起来

下面是一条可执行的开发流水线，把上面四节串成完整路径：

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

对于"订外卖"场景的最小 Tool 集合，建议从三个起步：

• • searchRestaurant：拉候选商家列表
• • getMenu：获取指定商家的菜单与价格
• • placeOrder：下单 + 支付（敏感操作，必须弹用户确认）

把 Tool 数量控制在 3 个以内，是减少模型选错工具概率的关键。Tool 越多，模型越容易"挑花眼"——经验数据显示，当 Tool 数量从 3 增加到 8 时，模型选错工具的概率会从 8% 上升到 22%。等核心链路稳了，再按需扩展到 5–8 个；如果超过 10 个，应该拆成多个 Agent 协同，而不是塞进同一个 Agent。

七、上架小艺开放平台：从本地到系统入口

当本地 Agent 跑通后，可以在小艺开放平台把能力暴露为 Skill。HDC 2026 上小艺开放平台做了三项关键升级：

• • A2A 协议升级：支持头部伙伴在端侧直接完成 Agent 间通信，出行类 Skill 可自动调用日历、天气、导航
• • A2UI 协议升级：通过标准化描述语言，一次定义交互逻辑，自动适配手机、平板、车机、智慧屏
• • VibeCoding：用自然语言描述需求，平台自动生成 Skill 代码框架

VibeCoding 的最大价值在于把"懂业务但不会写代码"的产品经理拉进了 Skill 开发流程。实测中，一个完整 Skill 的开发周期从过去的 3 周压缩到了 3–5 天，其中代码生成占 1 天，调试占 2 天，审核与上架占 1–2 天。

上架流程关键步骤：

1. 1. 在开发者联盟完成华为账号实名认证
2. 2. 进入小艺开放平台，绑定 App ID 与签名指纹
3. 3. 提交 Skill 的 manifest（含权限声明、隐私说明、调用配额）
4. 4. 走安全审核（依据 HDC 2026《鸿蒙智能安全白皮书》HPIC 架构）
5. 5. 灰度发布 → 全量上架

审核环节最常被打回的三类问题：权限申请与功能描述不符、未提供隐私政策链接、Tool 调用未做超时与重试降级。把这三项在自测阶段就准备好，能把审核周期从平均 7 天压缩到 3 天。

八、安全护栏：HPIC 与本地优先

鸿蒙智能体框架将安全能力内嵌于每一层。HPIC（HarmonyOS 个人智能计算系统）已经通过中国泰尔实验室的端侧隐私框架、云侧隐私框架、端云数据传输隐私三大检验，达到增强级要求。

实操中需要落实的 5 条安全基线：

• • 本地优先：用户的口味偏好、常点商家、配送地址默认留在端侧，仅在执行具体任务时按需上行
• • 数据最小化：Tool 入参只传必要字段，例如 placeOrder 不传用户完整地址，只传脱敏后的配送标签
• • 敏感操作确认：支付、修改配送地址、退款必须走用户手动确认弹窗，不能由 Agent 代决
• • 三重匿名盲化：云端侧日志中的用户标识做 hash + 桶混淆 + 差分隐私处理
• • Tool 调用配额：每个 Tool 设置 QPS 上限与每日调用上限，防滥用与误循环

配额设计上有一个容易忽略的细节：Tool 调用应该按"滑动窗口"而非"固定窗口"统计。例如某 Tool 的 QPS 上限是 10，固定窗口下用户可能在第 59 秒集中调 10 次、第 61 秒再调 10 次，瞬时压力直接翻倍；而 60 秒滑动窗口能更平滑地限制真实调用速率。

安全不是上线前的补丁，是 Agent 能跑长的地基。在 Tool 设计阶段就把"哪些动作需要用户确认"列清楚，比事后补审计日志高效得多。

九、避坑清单：把常见雷区提前标出

整理一份"如果只能记 8 件事"的清单：

1. 1. Agent Card 的 name 必须与 ArkTS handler 名严格一致
2. 2. Tool 的 description 要写清输入输出边界，不要写"处理 X 请求"
3. 3. parameters 必填字段必须在 required 数组里声明
4. 4. handler 返回值必须是可序列化的 JSON 字符串
5. 5. hilog 必打 4 个检查点：userInput、agentState、toolCall、toolResult
6. 6. 支付、地址修改、退款走用户手动确认，不让 Agent 代决
7. 7. 端侧 Tool 默认优先，云端 Skill 仅在端侧能力不足时调用
8. 8. 上架前自测弱网与超时降级，避免线上"服务异常"白屏

Agent 工程的复杂度，不在大模型，而在那 5–8 个 Tool 的契约设计。契约清楚，模型自己会组装；契约模糊，再强的模型也只能瞎猜。

十、从 Demo 到长期运行：把 Agent 当成产品来运营

很多团队把 Agent 当成"功能"上线，但忽视了它是一个需要长期运营的产品。Agent 上线只是 0，运营才是 1。从行业实践看，一个没有运营机制的 Agent，平均 3 个月就会出现"用户意图越来越偏、模型越来越不听话"的退化现象。

三件值得长期投入的事：

• • 持续评测：每周抽样 50 条真实对话，对照 Tool schema 验证模型调用是否符合预期。命中率低于 90% 的 Tool 要重写 description 或拆分；连续两周低于 80% 的 Tool 要考虑下线
• • 用户反馈闭环：在 Agent 回复底部加"这条帮到你了吗"的轻量反馈，把差评自动汇总成 Tool 优化任务。反馈数据沉淀 4 周以上，模型优化才有可靠样本
• • 版本灰度：Tool schema 改动要走"5% → 20% → 50% → 100%"的灰度节奏，每一档至少观察 24 小时再放量，避免一次全量引发线上故障

把 Agent 当成产品，意味着它有版本、有指标、有迭代节奏。没有运营的 Agent，跑得越久偏离用户越远。从"功能思维"切换到"产品思维"，是 Agent 团队在第二年最容易踩的坎。

十一、写在最后：把"对话"当成新的接口

回到"订外卖"这个场景，整套链路跑通后，用户最终感知到的是一句话："帮我订一份 30 元左右的川式盖码饭。"背后发生了什么？系统级意图识别、多 Skill 串接、跨设备协同、安全护栏四件事被小艺和你的 Agent 默默承接。

这就是 HDC 2026 上反复强调的范式迁移：从"用户找应用"到"意图找服务"，从"为屏幕设计"到"为意图设计"。Agent 不再是 App 抽屉里的一个玩具，而是操作系统层面的新接口。

对开发者来说，最重要的一步是动手搭一个最小可用的 Agent。3 个 Tool、1 个 Agent Card、4 个 hilog 检查点，跑通一遍后就会发现：很多"看起来很玄"的 Agent 能力，本质上就是清晰的契约设计 + 严密的工程联调。

剩下的，就是把这个最小版本放到真实用户手里，让数据告诉你下一步该优化什么。