引言

HarmonyOS 7（API 26）最重磅的新能力就是 Agent 框架。简单说，Agent 就是"智能的应用程序功能单元"——它能被系统级的智能入口（如智慧助手、控制中心等）发现和调用，实现应用与系统的深度融合。

你写的一个功能，用户不用打开App，直接在系统层面就能调用它——这就是Agent的价值。

---

一、什么是 Agent

Agent 的核心特征：

• 可发现：系统知道你的Agent提供什么能力
• 可调用：用户通过系统入口直接使用
• 即用即走：用完即销毁，不常驻后台

---

二、Agent 的开发范式

2.1 创建一个最简单的Agent

Agent 本质上是一个 UIAbility，通过配置声明自己是Agent：

// WeatherAgent.ets
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { Agent, AgentSession } from '@kit.AgentKit';

@Agent({
  name: 'weather_query',          // Agent 唯一标识
  label: '查天气',                 // 显示名称
  description: '查询指定城市的天气信息',
  skills: ['query_weather']       // 声明能力
})
export default class WeatherAgent extends UIAbility {
  // 处理Agent调用请求
  onAgentSessionCreate(session: AgentSession): void {
    const { city } = session.getIntent();
    const weather = this.queryWeather(city);
    session.reply(weather);       // 返回结果
    session.close();              // 结束会话
  }

  private queryWeather(city: string): string {
    return `${city}: 晴, 25°C, 湿度60%`;
  }
}

2.2 配置声明

在 module.json5 中注册Agent：

{
  "module": {
    "abilities": [
      {
        "name": "WeatherAgent",
        "srcEntry": "./ets/agent/WeatherAgent.ets",
        "type": "agent",           // 声明为Agent类型
        "skills": [
          { "name": "query_weather" }
        ]
      }
    ]
  }
}

---

三、Agent 的 A2A 通信

Agent 可以调用其他 Agent，实现能力的组合——这叫 A2A（Agent-to-Agent） 通信。

// 天气Agent 中调用地理编码Agent
import { AgentSession } from '@kit.AgentKit';

class WeatherAgent extends UIAbility {
  async onAgentSessionCreate(session: AgentSession) {
    const city = session.getIntent().city;
    
    // 调用另一个Agent获取城市坐标（A2A）
    const geoSession = await Agent.startAgent({
      agentName: 'geo_code',
      intent: { city }
    });
    const { latitude, longitude } = await geoSession.getResult();
    
    // 再用坐标查天气
    const weatherSession = await Agent.startAgent({
      agentName: 'weather_data',
      intent: { latitude, longitude }
    });
    const weather = await weatherSession.getResult();
    
    session.reply(weather);
    session.close();
  }
}

---

四、Vibe Coding + Skill 开发

HarmonyOS 7 还支持 Vibe Coding——用自然语言描述功能，系统自动生成Skill。

// 用 @Vibe 描述一个Skill
@Vibe('翻译英文文本为中文')
export function translateText(text: string): string {
  // 系统会自动对接翻译API
  return `翻译结果: ${text}`;
}

Skill 可以被系统级智能入口调用，用户在智慧助手中说"翻译xxx"，系统自动找到你的翻译Skill并执行。

---

五、应用的 Agent 接入流程

接入步骤

步骤	操作	说明
1	梳理功能	找出应用中适合Agent化的能力
2	命名Agent	给每个Agent唯一的 name 和 label
3	声明 skills	描述这个Agent能做什么
4	开发逻辑	实现 onAgentSessionCreate 方法
5	注册配置	在 module.json5 中配置
6	测试验证	通过 DevEco Studio 的Agent调试工具
7	上架	审核通过后用户可用

---

六、最佳实践

✅ Agent 适合的场景

• 信息查询：天气、快递、股票、翻译
• 快捷操作：设提醒、记笔记、发消息
• 跨应用流程：查天气 → 加行程 → 设提醒

⚠️ 注意事项

• Agent 不能长时间运行：即用即走，超过30秒会被系统回收
• 回复数据大小限制：单次回复不超过 1MB
• 权限独立：Agent 的权限声明独立于主Ability
• 资源占用：多个 Agent 同时运行会竞争系统资源

---

七、与传统 Ability 的对比

特性	传统 UIAbility	Agent
启动方式	用户手动打开	系统智能调用
生命周期	完整前后台	即用即走
发现性	桌面图标	系统Agent列表
通信方式	Want 显式启动	A2A 智能路由
适用场景	完整页面体验	单一功能服务

---

总结

HarmonyOS 7 的 Agent 框架将应用从"图标启动"升级为"能力即服务"。

记住核心流程：定义技能 → @Agent 装饰 → 注册配置 → 处理会话。用 Agent 把你的功能"发布"到系统层面，用户在任何入口都能使用你的能力。