A2A 多智能体协作

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

协作也可以直接从设备对话或语音发起。例如，将家庭中控与温控器、风扇等设备关联后，可以向主控请求同时查询或调整这些设备。

适用场景

• 其他智能体需要查询设备信息或调用设备操作。
• 多个设备智能体需要协作完成一个目标。
• 外部 A2A 客户端需要发现和复用设备能力。

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

准备工作

开始前请确认：

1. Gateway 可以连接到已启用 A2A 注册表的 EMQX。EMQX 版本需要为 6.2.0 或以上。
2. 被调用的目标设备智能体已启用 A2A，且包含可发布的设备能力。系统会根据当前物模型生成查询、控制等可调用技能。
3. 参与协作的智能体使用相同的 MQTT Broker、A2A 组织和 A2A 单元。
4. Gateway 已配置可用的大模型。参见大模型配置。
5. 执行时需要使用的目标设备处于在线状态。

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

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

配置方法见配置。

为设备智能体启用 A2A

为温控器、风扇等被调用的目标启用 A2A，使其他智能体能够发现并使用它们的能力。仅作为请求发起方的主控设备不必因此发布自己的 A2A 卡片；主控的可协作范围通过后面的设备绑定配置。

1. 创建设备智能体，或打开已有设备智能体的编辑页面。
2. 在预览面板中确认设备规格。
3. 打开 启用 A2A 协作。
4. 保存设备智能体。

启用 A2A 协作 会把智能体发布到实时 A2A 网络并注册卡片。Gateway 保持连接时，该智能体会出现在 A2A 工作区中，并可以接收请求。

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

发布与更新设备能力

A2A 卡片描述其他智能体可以调用的能力。直连设备使用其物模型中的命令；经 IoT 平台接入的设备使用平台物模型提供的服务、可写属性和任务能力。

当前接入提供的能力	协作中的用途
状态与历史查询	在执行时读取状态、事件或操作记录，为后续判断提供依据
命令或服务	执行开关、模式调整等设备操作
可写属性	更新目标温度、运行模式等期望状态
设备任务	调用平台支持的任务创建或更新操作

实际技能以 A2A 工作区展示的列表为准。不同接入方式可提供的能力不同，技能发布和设备绑定仍受已有设备权限约束。

已启用 A2A 的设备智能体，在保存物模型或从 IoT 平台同步模型后，会自动更新已发布卡片的技能列表。新增、删除或修改操作后，重新查看 A2A 列表中的技能名称，并通过对应物模型确认参数要求。已有场景依赖的能力发生变化时，也应重新检查场景并验证执行结果。

在 A2A 工作区中协作

在 A2A 工作区中创建并执行场景，或发起一次性任务，可以验证已发布的设备能力能否协作完成目标。场景和任务每次运行时为每个参与智能体选择一台具体设备。

选择场景或任务

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

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

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

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

创建可重复使用的场景

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

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

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

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

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

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

查看或修改场景

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

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

执行场景

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

我要出门了，请执行离家模式。

Device Agent 会匹配 离家模式；如果有多个场景符合请求，会先让你选择。页面要求选择设备时，为每个参与智能体选择一台在线设备，核对名称和标识后点击 继续执行。同一智能体有多个步骤时，这些步骤共用本次选择的设备。

设备选择通过校验后，系统执行协作流程，并显示每个步骤的状态和最终结果。检查每一步实际使用的设备，以及操作后的状态。

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

编写可稳定执行的目标

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

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

执行一次性任务

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

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

不必提前指定设备，也不需要把目标拆成命令。系统会根据在线智能体发布的技能规划参与者、步骤、参数和执行顺序；如果已通过输入框旁的设备按钮提前选择设备，会优先使用这些设备对应的智能体。

计划需要具体设备时，页面会要求选择并校验设备是否可用。执行轨迹会显示步骤、状态和最终结果。任务不会保存为场景，再次执行时会重新规划。

从主控设备控制多个设备

主控设备是接收协作请求的具体设备，目标设备是它获准查询或控制的设备。一台主控可以关联多个目标，也可以关联同一设备智能体下的多台设备。绑定按主控设备分别保存，同一设备智能体下的另一台主控不会自动继承。

主控绑定是设备对话和语音的持续协作范围，与 A2A 工作区中场景或任务的设备选择相互独立，不会被其改写。

为家庭中控关联多个设备

以一台已完成语音接入的 家庭中控为例，主控标识为 home-controller-01，关联以下三台设备：

目标设备智能体	目标设备	设备标识
温控器	客厅温控器	living-thermostat-01
温控器	卧室温控器	bedroom-thermostat-01
智能风扇	卧室风扇	fan-01

1. 在首页找到主控所属的 家庭中控卡片，从更多操作菜单打开 配置总览。
2. 切换到 A2A 设备绑定，点击 配置设备绑定。

3. 在 主控设备 中选择 home-controller-01。
4. 在 设备智能体 中选择温控器，在 设备标识 中选择客厅温控器，点击 确认添加。
5. 重复选择并添加卧室温控器和卧室风扇。添加第二台温控器时，设备智能体保持为温控器，改选另一台具体设备即可。
6. 检查列表中的三条关联，再点击 保存。确认添加 只修改当前编辑内容，最终保存后绑定才会生效。

保存后，绑定图应显示同一主控连接到三台目标设备。点击图中的主控节点可以查看或编辑这台主控的绑定；从 配置设备绑定 入口可以切换到其他主控。

目标设备智能体下拉列表只显示已启用 A2A 的智能体。绑定范围仍受目标设备的物模型和访问权限限制；目标设备需要在实际查询或操作时在线。

从主控设备对话或语音发起协作

打开 家庭中控的设备对话，在左侧设备列表中选中对应主控，并在设备状态中确认设备 ID 为 home-controller-01，然后输入：

查看客厅和卧室温控器的当前温度，并查看卧室风扇的运行状态。

设备智能体会使用当前主控的绑定范围查找目标，并分别查询两台温控器和风扇。检查工具调用及回复中的设备名称，确认使用的是预期设备。

也可以在同一次请求中指定不同设备的操作，例如：

把客厅温控器的目标温度设为 24 度；开启卧室风扇，风速设为 1 档并关闭摇头。完成后分别确认设备状态。

使用家庭中控的语音入口时，说出同样的请求即可。主控需已完成语音接入；如果在 配置总览 → 设备智能体配置 → 语音工具 中限定了工具范围，需要加入 use_a2a（调用协作设备），并建议同时加入 inspect_a2a（查看可协作的设备与场景）。语音工具范围的操作见语音工具。

仅开放 inspect_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，然后刷新智能体列表。
无法发布设备能力	检查当前物模型是否提供可发布的查询、命令、服务、可写属性或任务能力；平台设备先确认模型已同步，再保存并检查错误提示。
智能体显示离线，或智能体之间无法互相发现	确认 Gateway 正在运行，并且所有智能体使用相同的 Broker、A2A_ORG_ID 和 A2A_UNIT_ID。
无法继续选择设备	为列出的每个智能体选择一台在线设备，并替换已失效或离线的选择。
主控对话提示没有可协作设备	确认当前选中的具体主控与绑定配置中的主控一致，并确认已点击 保存。同一智能体下其他主控的绑定不会自动应用。
目标没有出现在绑定选择器中	为目标设备智能体开启并保存 启用 A2A 协作，确认目标可发现；主控自身无需仅为发起协作而发布卡片。
文字协作可用，家庭中控语音协作不可用	检查主控的语音连接和语音工具范围。限定范围时需要开放 use_a2a，仅开放 inspect_a2a 不足以执行协作。
一个智能体有两台设备，但场景只允许选一台	场景和任务按参与智能体各选一台。需要从主控同时操作同一智能体下的多台设备时，将它们分别绑定到主控，再从该主控的设备对话或语音发起请求。