# 智能体编排

智能体编排把多个已发布的设备智能体组合起来完成一个目标。编排引擎内置在设备智能体网关里，随 `bun run dev:agent` 一起启动，通过 A2A over MQTT 调用所选智能体。编排分为两种方式：**场景** 和 **任务**。

## 前提条件

- 已经开启 A2A 协作并发布了至少两个在线设备智能体。参见 [A2A 协作](a2a.md)。
- 网页控制台开启了 `VITE_FF_A2A_MARKETPLACE_ENABLE=true`，能看到 **A2A 市场** 入口。
- 网关已配置可用的大模型。编排引擎用它生成场景流程图和任务执行计划。参见 [大模型配置](../operate-reference/configuration/model-config.md)。

## 场景

场景是预定义的多智能体流程：先勾选智能体、填写目标，编排引擎用大模型把目标拆成一张有向无环图（DAG），每个节点是一次智能体调用，节点之间的依赖决定执行顺序。

### 创建场景

1. 打开 **A2A 市场**，点击右侧场景面板的 **创建场景**。
2. 填写场景名称和目标描述。目标描述越具体，生成的流程图越准确。
3. 勾选要参与协作的在线智能体。
4. 点击 **创建场景**。

创建后场景状态先显示为“创建中”，编排引擎在后台分析所选智能体的能力并生成流程图，生成完成后变为“就绪”。如果所选智能体离线、目标无法拆解或大模型调用失败，状态会变为“失败”。

生成时模型会反思校验：每个步骤用到的信息是否能从某个智能体或用户输入获得。如果缺少关键参数（例如“温度太高”没有给出阈值），场景会进入“待补充”状态，并列出需要确认的问题；在创建页面回答后，模型会结合你的输入重新生成。如果流程不可行，模型会重新规划后再试。

重要：模型不会把生成时刻的临时事实（比如今天的日期、当前时间）写进任务，因为执行时这些值已经失效。每个条件所需的运行时信息（当前温度、当前时间、门是否开着等）必须由某个已选智能体在执行时提供。如果目标需要某种运行时观测，但已选智能体都没有这个能力（例如“在夜晚”需要当前时间，但没有智能体能报时），场景生成会失败，并说明缺少什么能力、建议补充哪种智能体；你可以加入具备该能力的智能体后重新创建。

### 查看流程图

点击场景卡片可以打开流程图视图。图里每个节点对应一次智能体调用，显示目标智能体和该步骤的指令；节点之间的连线表示执行依赖。标记为 terminal 的节点是最终输出步骤，其结果会拼接到场景的最终回复里。下游步骤的指令里可以用 `{<上游任务 id>}` 引用上游步骤的输出，运行时会被替换成实际结果。

### 启动场景

在场景卡片或流程图视图上点击 **启动**，相当于对场景说一句 `go`。编排引擎按依赖顺序调度智能体：先执行没有依赖的步骤，某一步完成后会触发依赖它的后续步骤；任意一步失败会把失败向下游传播。依赖上游输出的步骤会把上游结果注入到自己的指令里（条件判断也写在下游步骤的指令中），整个过程的进度会实时显示在编排聊天框里，包括每一步发出了什么、收到了上游什么、返回了什么。

## 任务

任务是临时的多智能体指令，不需要预先定义流程图。在编排聊天框里用自然语言描述目标，编排引擎用大模型生成执行计划（选择哪些智能体、对每个智能体说什么），然后依次调用这些智能体，按普通对话方式返回结果。

适合一次性、临时性的跨智能体需求，例如“查一下所有房间的温度，把偏高的房间空调调到 24 度”。

## 实时状态

场景和任务的运行进度都显示在 A2A 市场页面的编排聊天框里：

- 每个步骤开始、完成或失败时会更新一条进度。
- 最终结果以消息形式返回。
- 失败会标明出错步骤和原因。

进度通过 SSE 实时推送到页面，不需要手动刷新。

## 限制

- 运行状态保存在内存里。网关重启时，进行中的运行会中断；场景定义本身会持久化，重启后仍可再次启动。
- 编排引擎调用的是当前在线的智能体。运行过程中某个智能体离线，对应步骤会失败。
- 场景流程图和任务计划都由大模型生成，结果取决于模型能力和目标描述的清晰程度。