前言

Agent 这个词现在出现频率很高。我们在聊 HarmonyOS 7 的时候，它很容易被直接理解成一个智能助手、一个聊天入口，或者一个能够帮用户完成任务的新交互层。

这种理解不算错，但如果你已经在做 HarmonyOS 应用，问题会更具体。

• 现有应用里的功能，哪些可以被 Agent 调用。
• 一次用户意图会不会跨过多个页面。
• 哪些动作可以自动执行，哪些动作必须确认。
• 如果 Agent 调用失败，应用要怎么回退。
• 如果执行结果影响用户数据，日志、权限和确认流程怎么保留。

这些问题才是接入 Agent 之前最需要先处理的部分。

HarmonyOS 7 的智能化方向已经把 Agent、Skill 和 AI 开放能力放到同一条链路里。Agent 系统能力和模型能力开放，支持 Agent 能力构建和已有 Agent 的 A2A 接入，用来帮助应用 Agent 对接系统级智能入口。

所以，Agent 接入前的重点，可以先落到一个更工程化的问题上：

你手里的应用，是否已经把任务边界设计清楚。

我们先不急着讨论完整接入代码，也不把 Agent 当成单独的聊天界面来讲。我们先从真实项目出发，把一个任务拆开，看看哪些步骤适合自动处理，哪些步骤需要用户确认，哪些能力需要先沉到服务层，哪些记录必须保留下来。

一、先把 Agent 放回任务链路里理解

如果你已经做过一个工具类或者办公类应用，就会发现用户想完成的事情，通常不会刚好等于某一个按钮。

比如会议类应用里，用户真正想要的可能不是 点击生成纪要按钮，而是把一次会议整理成可以继续推进的工作结果。这个结果可能包含会议摘要、决议、待办事项、责任人、截止时间，还可能继续生成周报草稿。

从页面角度看，这些动作会散落在多个页面里。

页面	页面动作
会议详情页	查看录音、转写文本、纪要
纪要页	生成摘要、整理决议
待办页	提取待办、修改状态
联系人页	选择责任人
周报页	汇总项目进展

但是从 Agent 角度看，它更像一条连续任务链。

会议录音 → 会议转写 → 生成纪要 → 提取待办 → 分配责任人 → 生成周报 → 归档项目

这条链路里，每个节点都要回答几个问题。

问题	作用
这个节点能不能单独执行	决定是否适合做成可调用能力
这个节点需要什么输入	决定参数边界是否清楚
这个节点会产生什么结果	决定输出是否可保存和复用
这个节点失败后怎么处理	决定用户体验是否稳定
这个节点会不会修改关键数据	决定是否必须确认

我们在接入 Agent 之前，最好先完成这个拆解。这样做的好处是，Agent 以后无论从系统级智能入口进入，还是从应用内部入口进入，调用的都不是一堆散落在页面里的按钮逻辑，而是一组边界清楚的业务能力。

HarmonyOS 7 已经把 Agent 时代的软件工程创新放到 HDC 2026 的议程中里，同时开发文档中也有 Agent Framework Kit、Intents Kit、Core Speech Kit、Core Vision Kit、Natural Language Kit 等 AI 相关能力入口。Agent Framework Kit 用于在应用内拉起智能体组合，Intents Kit 则面向 HarmonyOS 级意图体系。

但在项目层面，第一步仍然不是直接寻找所有 API，而是先把应用自己的任务链拆清楚。API 能力只是后面的接入方式，任务边界才是应用自己的工程基础。

二、再把任务动作分成三类

任务链拆出来以后，下一步不是马上写代码，而是先判断每个动作的风险等级。

这个判断非常重要。因为 Agent 的能力越强，越不能把所有动作都当成自动化步骤。生成一段草稿、查询一条记录、整理一个摘要，失败以后通常还能修正。可是发送消息、删除数据、发布内容、分配责任人、提交订单，这些动作一旦执行，就会影响真实数据和真实协作关系。

我们可以先把任务动作分成三类。

动作类型	示例	处理建议
可自动执行	查询、摘要、草稿生成、内容分类	可以减少手动操作
建议确认	生成纪要、提取待办、改写文案	执行前后都要展示结果
必须确认	删除、发布、发送、支付、修改关键数据	不能跳过确认流程

这张表看起来简单，但放到项目里很实用。

比如会议场景里，生成纪要草稿 可以相对自动化。即使结果不够理想，用户还可以编辑、重新生成或者直接放弃。
但是 分配责任人 就不同了。这个动作会影响团队协作关系，如果 Agent 直接把待办分配给某个人，就可能造成误会。
再比如 发送周报，它不是一个单纯的内容生成动作，而是对外输出动作。生成草稿可以自动化，正式发送必须确认。

可以把会议任务链继续细化成这样。

任务节点	动作类型	原因
读取会议文本	可自动执行	只读取，不修改数据
生成纪要草稿	可自动执行	输出是草稿，可以修改
提取待办事项	建议确认	可能识别错误，需要用户确认
分配责任人	必须确认	会影响协作关系
设置截止时间	必须确认	会影响任务承诺
生成周报草稿	建议确认	输出需要人工审阅
发送周报	必须确认	属于对外发送动作

这里的核心思路是：Agent 可以减少操作步骤，但不能降低关键动作的确认要求。

如果一个应用没有这个分层，后面接入 Agent 时就容易把所有动作都放进同一条执行链里。短期看起来更智能，长期会带来安全、误操作和责任边界问题。尤其是办公、项目管理、本地生活、金融、医疗、合同这些场景，更要提前把确认边界设计清楚。

三、把任务节点整理成可调用能力

任务类型分清以后，接下来要看每个任务节点能不能被整理成可调用能力。

这里会回到上一篇提到的 Skill 思路。Agent 不是孤立存在的，它需要调用应用里的业务能力。一个能力如果还藏在页面事件里，只能通过用户点击按钮触发，就很难被 Agent 稳定复用。更好的方式，是把业务能力沉到服务层，让页面、Skill 候选入口、Agent 任务链都能调用同一套能力。

以会议类应用为例，任务链可以拆成这些能力。

任务节点	可调用能力	输入	输出
会议转写	获取会议文本	会议 ID、音频路径	转写文本
生成纪要	生成会议纪要	会议文本	摘要、决议、风险
提取待办	提取行动事项	会议文本、纪要	待办列表
分配责任人	更新待办责任人	待办 ID、联系人 ID	更新后的待办
生成周报	生成周报草稿	时间范围、项目 ID	周报草稿
归档项目	保存会议结果	会议 ID、纪要、待办	项目记录

这张表的重点，是把 Agent 任务链和应用服务能力对应起来。

我们可以先用项目侧接口草案固定能力边界。这里的代码不代表 HarmonyOS 7 Agent API 实测结果，它只是现有项目里可以提前整理的服务层结构。

export interface MeetingWorkflowInput {
  meetingId: string;
}

export interface MeetingWorkflowResult {
  summary: string;
  decisions: string[];
  actionItems: ActionItemDraft[];
  weeklyReportDraft?: string;
}

export interface ActionItemDraft {
  title: string;
  ownerId?: string;
  dueTime?: number;
  needConfirm: boolean;
}

有了这个结构以后，任务链就不会只停留在页面流程里。后续无论通过会议详情页按钮触发，还是通过 Agent 调用，都可以围绕同一套输入输出继续扩展。

再往下，可以把每个能力抽到服务层。

export class MeetingWorkflowService {
  async generateWorkflowDraft(
    input: MeetingWorkflowInput
  ): Promise<MeetingWorkflowResult> {
    const transcript = await this.loadTranscript(input.meetingId);
    const summary = await this.generateSummary(transcript);
    const actionItems = await this.extractActionItems(transcript);

    return {
      summary: summary.summary,
      decisions: summary.decisions,
      actionItems
    };
  }

  private async loadTranscript(meetingId: string): Promise<string> {
    return '';
  }

  private async generateSummary(transcript: string) {
    return {
      summary: '',
      decisions: []
    };
  }

  private async extractActionItems(transcript: string): Promise<ActionItemDraft[]> {
    return [];
  }
}

这段代码不解决 Agent 接入本身，但它解决了一个更基础的问题：任务链需要有稳定的服务层边界。没有这层边界，Agent 接入时就容易直接依赖页面状态，后续维护会非常麻烦。

这里大家可以注意一个细节：needConfirm 这个字段很重要。它不是为了展示好看，而是把任务风险边界放进了数据结构里。待办是否需要确认，不应该只由页面临时判断，最好在能力输出阶段就给出明确标记。这样后续进入 Agent 调用链时，确认逻辑也能继续复用。

四、为确认、失败和日志单独设计流程

任务链和服务能力整理以后，还有一件事经常被忽略：异常处理和日志记录。

如果你只是做页面按钮，失败以后弹一个 Toast，用户可能还能理解。但 Agent 调用链路更长，失败点也更多。可能是文本为空，可能是权限不足，可能是服务超时，可能是结果不符合预期，也可能是用户取消确认。任何一个地方没有处理好，最终体验都会变得很模糊。

所以在 Agent 接入前，确认、失败和日志需要单独设计。

可以先把失败情况分成几类。

失败类型	示例	处理方式
输入缺失	没有会议文本、没有音频	提示补充输入或返回原页面
权限不足	无法访问文件、联系人、通知	引导授权或降级处理
能力失败	生成失败、解析失败、服务超时	支持重试或手动编辑
用户取消	不确认待办、不发送周报	保留草稿，不继续执行
数据冲突	待办已修改、会议已删除	刷新数据并提示冲突
设备限制	当前设备不支持某能力	记录设备条件，提供替代路径

再看确认流程。

生成候选结果 → 展示结果 → 用户确认 → 执行写入 → 记录日志 → 返回状态

这个流程看起来比直接自动执行麻烦，但对真实项目更稳。因为很多 Agent 任务并不是单次查询，而是会修改用户数据。只要涉及保存、发送、删除、分配、发布，就需要把确认流程放在前面。

我们可以用一个项目侧确认结构来固定边界。

export interface ConfirmableAction<T> {
  actionId: string;
  title: string;
  payload: T;
  riskLevel: 'low' | 'medium' | 'high';
  confirmRequired: boolean;
}

export interface ActionExecutionResult {
  actionId: string;
  success: boolean;
  message?: string;
}

这里的 riskLevel 和 confirmRequired 是两个关键字段。它们可以帮助我们把动作风险写进结构里，而不是把风险判断散落在页面按钮和弹窗逻辑里。

日志记录也要尽早准备。

export interface AgentTaskLog {
  taskId: string;
  abilityName: string;
  inputSummary: string;
  resultStatus: 'success' | 'failed' | 'cancelled';
  errorMessage?: string;
  createdAt: number;
}

这个日志结构不一定一开始就很复杂，但至少要记录任务 ID、能力名称、输入摘要、执行状态、错误信息和时间。后续排查问题时，它会非常有用。尤其在 Beta 阶段，如果你要判断某个能力失败是因为接口、权限、设备还是业务数据，日志会比口头描述可靠得多。

五、用一个最小任务链完成接入前验证

前面讲了任务边界、能力拆分、确认流程和日志记录，最后还是要回到一个最小验证。

Agent 接入前，不建议一上来就做完整业务闭环。完整闭环里会有太多变量：录音、转写、纪要、待办、联系人、周报、项目归档、权限、同步、通知。任何一个环节出问题，排查都会很重。

更稳的方式，是先选一个最小任务链。

对于会议类应用，可以先选这条链路。

会议文本 → 生成纪要草稿 → 提取待办草稿 → 用户确认 → 保存草稿

这条链路有几个好处。

第一，它有明确输入。只需要一段会议文本。
第二，它有明确输出。结果是纪要草稿和待办草稿。
第三，它有确认环节。用户确认后再保存。
第四，它暂时不涉及发送、删除、支付、外部发布这些高风险动作。

可以把验证目标整理成表格。

验证项	目标
输入	能接收会议文本
纪要生成	能返回摘要和决议
待办提取	能返回待办标题和建议责任人
用户确认	能展示结果并等待确认
保存草稿	只保存确认后的结果
日志记录	能记录成功、失败、取消状态

这里可以用输入输出样例先固定验证目标。它不是模型效果证明，也不是 HarmonyOS 7 Agent API 实测结果，只是最小任务链的项目侧验证样例。

{
  "input": {
    "meetingText": "本次会议确认了版本节奏，接口联调时间，以及下周发布前的测试安排。"
  },
  "expectedOutput": {
    "summary": "会议围绕版本节奏、接口联调和发布测试安排展开。",
    "actionItems": [
      {
        "title": "确认接口联调时间",
        "needConfirm": true
      },
      {
        "title": "整理发布前测试清单",
        "needConfirm": true
      }
    ]
  }
}

有了这个最小链路，后续就可以逐步替换真实能力。

第一步先用手写逻辑或者 mock 数据跑通结构。
第二步接入真实 AI 能力生成纪要和待办。
第三步补充 Skill 候选入口。
第四步再考虑 Agent 任务调用。

这样做会慢一点，但项目会稳很多。尤其是 Beta 阶段，先把任务结构、确认流程和日志记录做清楚，比直接追求完整 Agent 效果更可靠。

如果放到会议随记类应用或会后行动台里，优先级可以这样排。

优先级	动作	原因
P0	整理任务链路	明确 Agent 要调用什么
P0	拆分服务能力	避免业务逻辑绑死页面
P1	增加确认结构	避免高风险动作自动执行
P1	记录执行日志	方便排查和复盘
P2	接入真实 Agent 能力	等文档、SDK 和设备条件更稳定
P2	扩展多端和系统入口	等核心链路稳定后再处理

这张表能避免一个常见问题：一开始就想做完整 Agent，结果任务链、确认流程、服务层、日志都没有准备好。我们先把 P0 和 P1 做扎实，后面接入 Agent 会轻松很多。

总结

Agent 接入前，最关键的准备不是马上写完整接入代码，而是先把任务边界设计清楚。

可以按照五步处理。

步骤	要做什么
1	把 Agent 放回真实任务链路里理解
2	将任务动作分成可自动执行、建议确认、必须确认
3	把任务节点整理成可调用服务能力
4	单独设计确认、失败和日志流程
5	用最小任务链完成接入前验证

如果你已经有 HarmonyOS 6 原生项目，可以先从现有业务里挑一条任务链。

会议类应用可以选 会议文本 → 纪要草稿 → 待办草稿 → 用户确认 → 保存草稿。

本地生活类应用可以选 查询需求 → 推荐结果 → 用户确认 → 创建预约草稿。

内容类应用可以选 素材输入 → 草稿生成 → 人工确认 → 保存模板。

这一步做完以后，Agent 接入会更清楚。你不会只盯着聊天入口，也不会把高风险动作直接放进自动化流程里。后面无论接入 Skill、Agent Framework Kit、Intents Kit，还是继续接 AI 开放能力，项目都会有一条更稳定的工程路径。