任务流 payload 协议（编排技能）

任务流通过 startRequest(payload, ...) 与 taskRequest(payload, ...) 的 payload 字符串，向机器人下发一组可编排的动作。本页详细描述该 JSON 的结构、字段语义、执行规则，以及 SIMPLE / COMPLEX 两种模式的端到端示例。

与 response.onSkill 的区别：onSkill 是被动回调中针对单条 ASR 文本的"一次性技能下发" （字段语义见语义技能参考）；任务流是主动交互，可以按顺序 / 并行 / 随机编排多个动作，还能流式追加新动作组，更适合"讲解任务""定点导航""多步动作脚本"等场景。

payload 整体格式

⚠️ payload 必须是 JSON 数组——startRequest 和 taskRequest 下发的 payload 都是一个 action_group 数组。即使只下发一个 action_group，也必须把它放进数组里（[{...}]）， 不能直接传单个对象（{...}）。

json

[
  {
    "type": "action_group",
    "execution_mode": "parallel",
    "continue_on_failure": false,
    "actions": [
      {
        "action_type": "tts",
        "config": { "tts": "hello" }
      }
    ]
  }
]

数组里可以放多个 action_group：

json

[
  { "type": "action_group", "actions": [ ... ] },
  { "type": "action_group", "actions": [ ... ] }
]

action_group 字段

字段	必填	默认	说明
`type`	否	`action_group`	传了就必须是 `action_group`
`actions`	是	—	`action` 数组
`execution_mode`	否	`parallel`	`parallel` / `sequential` / `random`
`continue_on_failure`	否	`false`	group 级字段，当前会被保留，但真正决定单个 action 失败后是否继续的是 action 自身的 `continue_on_failure`

action 字段

每个 action 的结构如下：

json

{
  "action_type": "tts",
  "config": {},
  "continue_on_failure": false
}

action_type（必填，字符串）：见下文「当前支持的 action_type」
config（必填，对象）：每个 action_type 的具体配置，见下文「各类 action 字段」
continue_on_failure（可选）：
- 在 sequential 模式下生效——某个 action 失败时，配 true 则继续执行后续 action
- 在 parallel 模式下，所有 action 已同时发出，group 结果会汇总失败状态

多个 action_group 的排队语义

这一段是接入侧最容易误解的点。

同一个 request 里如果带了多个 action_group，当前实现会把它们排队串行执行。
对应的 *.execute_ack 会在该 request 里所有 action_group 全部结束后再返回。

也就是说：

group 内是否并行，由 execution_mode 决定。
request 内多个 group 不会并行执行。

当前支持的 action_type

场景	推荐 `action_type`	是否支持等待
动作	`motion`	支持
TTS	`tts`	支持
表情	`emoticon`	不支持完成等待
定点导航任务开启 / 继续 / 取消	`pilot_task`（旧名 `fixed_line_intro` 仍兼容）	不支持完成等待
主动唤醒收音 / 退出全双工对话	`setting`	不支持完成等待
转弯	`move`	当前不建议使用（未实现）

显式写法：motion / move / emoticon / tts / fixed_line_intro / setting。

各类 action 详细字段

动作（motion）— 支持"不等待 / 等待完成"

json

{
  "action_type": "motion",
  "config": {
    "id": 59
  }
}

常用字段：

字段	说明
`id`	单个动作 ID，或动作 ID 数组（数组时随机选一个）
`motion_name`	按名字执行动作
`motion_type`	动作类型，常见取值 `0~3`
`ani_path`	直接按动画路径执行
`interrupt`	是否打断前一个动作
`dont_repeat`	数组随机时尽量不重复
`wait_only`	只等待，不下发动作
`execution_scenarios.time`	等待超时时间（ms）
`execution_scenarios.wait_status` / `wait_statuses`	等待状态，默认 `kCompleted`

不等待——不传 execution_scenarios，下发成功后立即返回 SUCCESS：

json

{
  "action_type": "motion",
  "config": { "id": 59 }
}

等待完成：

json

{
  "action_type": "motion",
  "config": {
    "id": 59,
    "execution_scenarios": { "time": 5000 }
  }
}

补充：

失败状态 kFailed 会自动纳入等待结果判断。
如果超时，当前实现会按成功处理。

TTS（tts）— 支持"不等待 / 等待完成"

json

{
  "action_type": "tts",
  "config": {
    "tts": "你好，我开始播报了"
  }
}

常用字段：

字段	说明
`tts`	直接播报文本
`nlg`	NLG 场景 ID
`params`	NLG 模板参数
`priority`	优先级
`interrupt`	是否先打断当前播报
`interrupted`	新 TTS 是否允许被打断
`execution_scenarios.time`	等待超时时间（ms）

不等待：

json

{
  "action_type": "tts",
  "config": { "tts": "这句播报不等完成" }
}

等待完成：

json

{
  "action_type": "tts",
  "config": {
    "tts": "这句播报需要等播完",
    "execution_scenarios": { "time": 10000 }
  }
}

补充：

TTS 等待不需要传 wait_status。
当前实现等待 kCompleted / kCanncelled / kFailed。
如果超时，当前实现也按成功处理。

表情（emoticon）— 不支持完成等待

json

{
  "action_type": "emoticon",
  "config": { "id": 5 }
}

常用字段：

字段	说明
`id`	表情 ID，支持单个数值或数组随机
`times`	播放次数
`interval_ms`	多次播放间隔
`priority`	表情优先级
`video_path` / `video_path_list`	按视频路径播放
`mode`	视频播放模式：`1/ONCE` 或 `2/LOOP`
`video_priority`	视频播放优先级

注意：emoticon 是"下发即返回"，不支持在 action_group 里等待表情真正播完。

定点导航（pilot_task）— 不支持任务完成等待

走的是 pilot_task 插件，适用于"动线讲解 / 定点讲解"任务控制。

开启任务：

json

{
  "action_type": "pilot_task",
  "config": {
    "control_type": "pilot_start_task",
    "cmd": "target_poi",
    "target_name": "{{target}}",
    "play_tts": true
  }
}

继续任务：

json

{
  "action_type": "pilot_task",
  "config": {
    "control_type": "pilot_resume_task",
    "play_tts": true
  }
}

取消任务：

json

{
  "action_type": "pilot_task",
  "config": {
    "control_type": "pilot_stop_task",
    "play_tts": true
  }
}

常用字段：

字段	说明
`control_type`	必填，操作类型
`title`	必填（开启任务时）
`play_tts`	是否播报结果提示

补充：

pilot_task 返回的是"控制命令已下发"，不是 "导航任务真正完成"。
当前不支持通过 execution_scenarios 等待任务真正执行结束。
如果场景是「前往下一讲解点」可用 fixed_line_intro_go_to_next_point，「返回起点并结束」可用 fixed_line_intro_go_to_init_point。

设置（setting）— 不支持完成等待

主动唤醒收音：

json

{
  "action_type": "setting",
  "config": { "active_wakeup": true }
}

当前行为：

触发 ProcessWakeUpResult({ .wakeup_type = kCustomTriggered })
随后显式调用 StartDialog()
用于开启主动收音 / 对话链路
仅支持"触发开启"，不支持在 action_group 里等待 ASR 首包、VAD 完成等后续状态

退出全双工对话：

json

{
  "action_type": "setting",
  "config": { "quit_voice": true }
}

用于结束对话收音 / 退出对话链路。

转弯（move）— 当前不建议使用

turn_left / turn_right 当前视为未真正实现，流式 action_group 里不建议使用。
如果只是平移，可继续使用 move_left / move_right。
如果确实需要原地转向，建议先补齐 MoveDirection 与执行映射，再对外开放。

端到端示例

SIMPLE 模式：一次性下发

适用于"一句问候 + 一个表情 + 一个动作"等无需后续追加的场景。

json

{
  "type": "agentsdk.flow.start.request",
  "flow_id": "flow_demo_001",
  "event_id": "event_flow_start_001",
  "mode": "simple",
  "payload": [
    {
      "type": "action_group",
      "execution_mode": "parallel",
      "continue_on_failure": false,
      "actions": [
        {
          "action_type": "tts",
          "config": { "tts": "开始执行 simple flow" }
        },
        {
          "action_type": "emoticon",
          "config": { "id": 5 }
        },
        {
          "action_type": "motion",
          "config": {
            "id": 59,
            "execution_scenarios": {
              "time": 5000,
              "wait_status": "kCompleted"
            }
          }
        }
      ]
    }
  ]
}

在 Java 侧通过 TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.SIMPLE) 构造，然后把上面这段 JSON 作为 payload 传给 startRequest。

COMPLEX 模式：流式追加 action_group

适用于"先开启唤醒收音 → 启动定点讲解任务 → 中途追加继续 / 取消"这类多阶段编排。

① 开流（仅 mode 字段，暂不下发动作）

json

{
  "type": "agentsdk.flow.start.request",
  "flow_id": "flow_demo_nav_001",
  "event_id": "event_flow_start_001",
  "mode": "complex"
}

② 追加"主动唤醒收音"

json

{
  "type": "agentsdk.flow.task.request",
  "flow_id": "flow_demo_nav_001",
  "event_id": "event_flow_task_001",
  "payload": [{
    "type": "action_group",
    "execution_mode": "sequential",
    "actions": [
      {
        "action_type": "setting",
        "config": { "active_wakeup": true }
      }
    ]
  }]
}

③ 追加"开启定点讲解任务"

json

{
  "type": "agentsdk.flow.task.request",
  "flow_id": "flow_demo_nav_001",
  "event_id": "event_flow_task_002",
  "payload": [{
    "type": "action_group",
    "execution_mode": "sequential",
    "actions": [
      {
        "action_type": "tts",
        "config": { "tts": "开始执行定点讲解任务" }
      },
      {
        "action_type": "fixed_line_intro",
        "config": {
          "control_type": "fixed_line_intro_start_task",
          "title": "固定线路讲解",
          "play_tts": true
        }
      }
    ]
  }]
}

④ 继续任务

json

{
  "type": "agentsdk.flow.task.request",
  "flow_id": "flow_demo_nav_001",
  "event_id": "event_flow_task_003",
  "payload": [{
    "type": "action_group",
    "execution_mode": "sequential",
    "actions": [
      {
        "action_type": "fixed_line_intro",
        "config": {
          "control_type": "fixed_line_intro_resume_task",
          "play_tts": true
        }
      }
    ]
  }]
}

⑤ 取消任务

json

{
  "type": "agentsdk.flow.task.request",
  "flow_id": "flow_demo_nav_001",
  "event_id": "event_flow_task_004",
  "payload": [{
    "type": "action_group",
    "execution_mode": "sequential",
    "actions": [
      {
        "action_type": "fixed_line_intro",
        "config": {
          "control_type": "fixed_line_intro_stop_task",
          "play_tts": true
        }
      }
    ]
  }]
}

Java 侧 SDK 接入步骤参见主动交互指南 - 任务流和主动示例 - TaskFlowExample。