A2A 多智能体协作

A2A 让其他智能体可以发现和调用设备智能体。在 A2A 工作区中，可以保存可重复使用的场景，也可以发起一次性任务，协调多个智能体和设备完成同一目标。

以下场景适合使用 A2A：

• 其他智能体需要调用当前设备智能体的命令。
• 多个设备智能体需要协作完成一个目标。
• 外部 A2A 客户端需要发现和复用设备能力。

如果只需要和单台设备对话、调试或控制，请使用设备智能体对话、MQTT 或 SDK。

准备工作

开始前请确认：

1. Gateway 可以连接到已启用 A2A 注册表的 EMQX。EMQX 版本需要为 6.2.0 或以上。
2. 参与协作的设备智能体至少包含一个 commands 命令。命令会生成可调用技能。
3. 参与协作的智能体使用相同的 MQTT Broker、A2A 组织和 A2A 单元。
4. Gateway 已配置可用的大模型。参见大模型配置。
5. 执行时需要使用的设备处于在线状态。

运行配置提供共享的 A2A 身份：

配置	作用	默认值
A2A_ORG_ID	注册和发现使用的组织	default
A2A_UNIT_ID	注册和发现使用的单元	default
MQTT Broker 配置	智能体卡片中的通信地址	当前 MQTT 运行配置

配置方法见配置。

为设备智能体启用 A2A

1. 创建设备智能体，或打开已有设备智能体的编辑页面。
2. 在预览面板中确认设备规格。
3. 打开 启用 A2A 协作。
4. 如果还需要把卡片注册到共享注册表，请打开 发布 A2A 卡片。
5. 保存设备智能体。

两个选项的作用不同：

• 启用 A2A 协作 会把智能体发布到实时 A2A 网络。Gateway 保持连接时，该智能体会出现在 A2A 工作区中，并可以接收请求。
• 发布 A2A 卡片 会额外把卡片加入 A2A 注册表。需要在实时发现之外保留注册记录时，请开启此项。

关闭 启用 A2A 协作 并保存后，系统会取消发布该智能体，并移除它的注册卡片。

选择场景或任务

打开 A2A，通过对话区顶部的选项选择使用方式：

需求	使用方式
保存并重复使用生成后的协作流程	场景
完成一次性请求	任务

在场景中，左侧会显示已保存场景，右侧会显示当前选中场景的协作流程。在任务中，左侧会显示可用智能体、技能和在线状态。

所有已就绪场景共用中间的对话区。选择场景只会打开流程供查看，不会把对话绑定到该场景。需要执行时，请写明场景名称，或用没有歧义的方式描述它，并明确要求系统执行。

创建可重复使用的场景

场景会保存目标和生成后的协作流程。以下示例使用 A2A 列表中的加湿器、智能风扇和智能门锁：

1. 打开 A2A，选择 场景。
2. 点击场景列表旁的 + 按钮。
3. 按下表填写场景名称和目标。
4. 选择三个 A2A 智能体。
5. 点击 创建。

配置	内容
场景名称	离家模式
目标	离家前锁门，并关闭风扇和加湿器。
A2A 智能体	加湿器、智能风扇、智能门锁

Device Agent 会根据三个智能体发布的技能拆分操作并生成协作流程。目标缺少必须确定的信息时，系统会先要求补充，再继续生成。

查看生成状态

创建后，场景会显示以下状态：

状态	操作
生成中	等待系统完成准备、规划和校验。
待补充	打开场景，根据列出的问题补充信息，然后点击 提交回答。
就绪	检查协作流程，然后从共享对话区执行。
失败	查看失败原因。编辑目标或智能体，然后保存并重新生成。
更新中	等待编辑后的场景重新生成。

查看或修改场景

在左侧选择场景，即可打开它的协作流程。

• 每个节点会显示负责执行的智能体和步骤指令。
• 节点连线用于概括规划后的流程。实际运行时，互不依赖的步骤可以并行执行。
• 使用全屏按钮可以查看更大的流程图。
• 对于已就绪或失败的场景，点击 编辑 可以修改名称、目标或智能体。点击 保存并重新生成 后会重建流程。
• 如果要移除场景，请在场景列表中点击 删除。删除后无法恢复。

执行场景

离家模式 就绪后，在 A2A → 场景 的对话中输入：

我要出门了

Device Agent 会匹配 离家模式；如果有多个场景符合请求，会先让你选择。为本次运行选择设备后，系统会执行协作流程，并显示每个步骤的状态和最终结果。

停止会终止编排等待，并阻止尚未下发的步骤；它不会撤销已经发送给智能体或设备的动作，必要时请检查设备状态。清空对话也会清除已选设备，但不会删除场景。

编写可稳定执行的目标

• 写明最终结果，不要只描述第一个动作。
• 提供阈值、位置等固定条件。
• 说明需要返回什么报告或确认信息。
• 选择能够在运行时获取所有必要数据的智能体。

不要依赖创建场景时观察到的临时值。当前温度、时间、设备状态等信息必须由智能体在场景运行时读取。

执行一次性任务

多个智能体需要立即协作、但流程不需要保存为场景时，打开 A2A → 任务，输入：

准备睡觉——让家里保持安全、安静和舒适。

不必提前指定设备，也不需要把目标拆成命令。提前选择设备时，任务智能体会优先考虑这些设备对应的在线智能体；未提前选择时，系统会先根据在线智能体发布的技能规划参与者、步骤、参数和执行顺序。

计划需要具体设备时，页面会要求选择并校验设备是否可用；也可以通过输入框旁的设备按钮提前选择。执行轨迹会显示步骤、状态和最终结果。任务不会保存为场景，再次执行时会根据当时在线智能体的能力和本次设备选择重新规划。

验证注册表发布

如果开启了 发布 A2A 卡片，请打开 EMQX Dashboard，确认已注册卡片存在且处于在线状态。

生成的卡片包含设备智能体名称、说明、MQTT 接口，以及设备规格中每个命令对应的技能。请把 A2A 智能体标识当作不透明值使用，从发现数据或注册表中读取，不要手动拼接。

Gateway 重启后，已保存且启用 A2A 的设备智能体会重新发布。

连接外部 A2A 客户端

外部客户端通过 MQTT v5 进行发现和请求/回复。主题、SendMessage 请求体、回复状态和设备指定方法见 API 参考：A2A over MQTT。

业务系统如果要通过 HTTP 创建或执行场景、发起一次性任务，参见 API 参考：多智能体编排。

持久化和限制

• 场景定义会在 Gateway 重启后保留。
• Gateway 重启时仍在生成或更新的场景会被标记为失败。Gateway 恢复后，请编辑并重新生成。
• 正在执行的场景或任务会在 Gateway 重启时中断。尚未完成的设备选择也需要重新开始。
• 对话记录只保留在当前页面会话中。刷新页面或在场景和任务之间切换会将其清除。
• 智能体和已选设备必须在对应步骤运行时保持在线。

常见问题

现象	排查方法
A2A > 任务 中没有该智能体	确认保存前已经打开 启用 A2A 协作。确认 Gateway 正在运行并已连接 MQTT Broker，然后刷新智能体列表。
发布失败并提示至少需要一个命令	在设备规格中添加至少一个 commands 命令，然后重新保存。
智能体显示离线，或智能体之间无法互相发现	确认 Gateway 正在运行，并且所有智能体使用相同的 Broker、A2A_ORG_ID 和 A2A_UNIT_ID。
无法继续选择设备	为列出的每个智能体选择一台在线设备，并替换已失效或离线的选择。