前言

上一篇我们用 openPangu 2.0 给智能生活助手加上了对话能力，但一个 Agent 能干的事毕竟有限。今天来聊聊 HarmonyOS 7 的 A2A（Agent-to-Agent）协议——让你的多个 Agent 像同事一样互相协作。

A2A 协议到底是什么

简单说，A2A 就是 Agent 之间的"通信标准"。你可以把它理解成 Agent 世界的 HTTP：定义了谁能发起请求、消息长什么样、怎么回复、出错了怎么办。

Google 今年也发布了自己的 A2A 协议规范，但 HarmonyOS 7 的端侧 A2A 跟系统深度绑在一起。它不只是定义了一个协议格式，而是直接在系统服务层提供了消息路由、Agent 注册、权限管控这些基础设施。你不用自己搭中间件，系统帮你全搞定了。

端侧 A2A 的核心设计思路是"去中心化"——每个 Agent 都是对等的，不存在什么"主控 Agent"。Agent A 可以给 Agent B 发消息，Agent B 处理完把结果返回，也可以拒绝、转发、甚至把任务拆成子任务分发给其他 Agent。

Agent 注册：先让系统认识你

要参与 A2A 通信，Agent 得先向系统注册。在 ArkTS 里，这一步通过 agentManager 来完成：

import { agentManager, agent } from '@kit.AgentKit';

// 定义 Agent 的能力描述
const weatherAgentDescriptor: agent.AgentDescriptor = {
  agentId: 'com.example.smartlife.weather',
  name: '天气助手',
  capabilities: [
    {
      id: 'get_forecast',
      description: '查询指定城市未来天气',
      inputSchema: {
        type: 'object',
        properties: {
          city: { type: 'string', description: '城市名称' },
          days: { type: 'number', description: '预报天数，默认7天' }
        },
        required: ['city']
      }
    }
  ]
};

// 注册到系统
agentManager.registerAgent(weatherAgentDescriptor, {
  onTaskReceived: async (task: agent.AgentTask) => {
    // 收到任务后的处理逻辑
    return await handleWeatherTask(task);
  }
});

注意 capabilities 里的 inputSchema，这就是告诉其他 Agent"我能干什么、你得给我什么参数"。A2A 协议用这套 schema 来做请求校验，参数不对直接拒绝，省得你自己在业务层写一堆校验逻辑。

Agent 间发消息：调用别人的能力

注册好了之后，任何 Agent 都可以通过 agentManager.sendTask 来调用别的 Agent。回到我们的实战场景：天气 Agent 查到明天有雨，想自动调用日程 Agent 给用户加一条带伞提醒。

async function handleWeatherTask(task: agent.AgentTask): Promise<agent.TaskResult> {
  const { city, days = 7 } = task.input;
  
  // 1. 获取天气数据（假设已有内部实现）
  const forecast = await fetchForecast(city, days);
  
  // 2. 检查是否有雨天，如果有就调用日程 Agent
  const rainyDays = forecast.filter(d => d.condition === 'rain');
  
  if (rainyDays.length > 0) {
    // 构造 A2A 任务，发给日程 Agent
    const reminderTask: agent.AgentTaskRequest = {
      targetAgentId: 'com.example.smartlife.calendar',
      capabilityId: 'add_reminder',
      input: {
        title: `${city}明天有雨，记得带伞`,
        time: rainyDays[0].date + 'T07:30:00',
        type: 'weather_alert'
      },
      // 设置超时和重试策略
      timeoutMs: 3000,
      retryPolicy: { maxRetries: 2, backoffMs: 500 }
    };
    
    const result = await agentManager.sendTask(reminderTask);
    
    if (result.status === agent.TaskStatus.COMPLETED) {
      console.info('日程提醒已添加');
    }
  }
  
  // 3. 返回天气结果给调用方
  return {
    status: agent.TaskStatus.COMPLETED,
    output: { forecast, remindersAdded: rainyDays.length > 0 }
  };
}

这段代码跑通之后，用户体验是这样的：用户对天气 Agent 说"明天天气怎么样"，Agent 不仅返回天气信息，还默默帮你加了一条"带伞"提醒。多 Agent 协作的感觉一下就出来了。

任务编排：串行还是并行

实际场景中，一个请求可能涉及多个 Agent。比如用户说"帮我规划周末"，你需要天气 Agent 查天气、日程 Agent 看排期、推荐 Agent 给活动建议。

A2A 协议支持两种编排方式。串行就是 A 干完给 B，B 干完给 C，像流水线。并行就是同时发任务给 A、B、C，等所有结果回来再汇总。

并行编排用 Promise.allSettled 就能搞定：

async function planWeekend(): Promise<WeekendPlan> {
  // 同时发给三个 Agent
  const [weatherResult, scheduleResult, suggestResult] = await Promise.allSettled([
    agentManager.sendTask({
      targetAgentId: 'com.example.smartlife.weather',
      capabilityId: 'get_forecast',
      input: { city: '北京', days: 2 }
    }),
    agentManager.sendTask({
      targetAgentId: 'com.example.smartlife.calendar',
      capabilityId: 'get_free_slots',
      input: { startDate: '2026-06-27', days: 2 }
    }),
    agentManager.sendTask({
      targetAgentId: 'com.example.smartlife.recommend',
      capabilityId: 'suggest_activities',
      input: { category: 'outdoor', distance: 20 }
    })
  ]);
  
  // 汇总结果，生成计划
  return buildWeekendPlan(weatherResult, scheduleResult, suggestResult);
}

这里我踩了个坑：Promise.allSettled 里如果某个 Agent 超时了，它不会被取消，只是返回 rejected 状态。你得自己处理这种情况，比如降级策略——天气查不到就跳过天气相关的建议。

权限和安全

端侧 A2A 不是谁都能随便调谁的。系统层面有权限管控：Agent 在注册时声明自己的能力，其他 Agent 调用时需要用户授权（敏感操作）或系统自动放行（低风险查询类）。

在 module.json5 里需要声明你想调用的 Agent 类型：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERACT_WITH_AGENT",
        "reason": "$string:agent_interact_reason",
        "usedScene": { "abilities": ["EntryAbility"] }
      }
    ]
  }
}

另外，涉及用户数据的 Agent 间通信（比如日程 Agent 需要读日历数据），系统会弹授权框让用户确认。别想着绕过这一步，审核会直接打回来。

踩坑经验

说实话，A2A 的 API 目前还有些粗糙的地方。最大的坑是 Agent 注册的时序问题——如果你在 onCreate 里注册 Agent，但这时候系统服务可能还没完全启动，注册会静默失败。我的做法是放在 onWindowStageCreate 里，加一个重试机制：

async function registerWithRetry(descriptor: agent.AgentDescriptor, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      await agentManager.registerAgent(descriptor, handler);
      console.info(`Agent 注册成功: ${descriptor.agentId}`);
      return;
    } catch (e) {
      console.warn(`注册失败，重试 ${i + 1}/${retries}`);
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  throw new Error('Agent 注册最终失败');
}

另一个容易忽略的点是 任务超时。A2A 的默认超时是 5 秒，如果你的 Agent 需要调网络（比如查天气），5 秒很可能不够。一定要在 AgentTaskRequest 里显式设置 timeoutMs。

小结

A2A 协议的核心价值是把"一个超级 Agent"拆解成了"一群专业 Agent"。天气、日程、推荐、健康……每个 Agent 专注自己的领域，通过 A2A 互相协作。这比把所有逻辑塞进一个大 Agent 里，好维护太多了。

从我的实战经验看，多 Agent 架构最难的不是写代码，而是设计 Agent 之间的边界和通信契约。先把每个 Agent 的能力定义清楚，schema 写详细，后面开发会顺畅很多。

下一篇我们来讲 openPangu 2.0 端侧大模型的接入——有了它，你的 Agent 才算真正有了"脑子"。