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

任务流通过 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 字段

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

action 字段

json

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

action_type（必填，字符串）
config（必填，对象）：每个 action_type 的具体配置
continue_on_failure（可选）：sequential 模式下某 action 失败时，true 则继续后续 action

多个 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`	当前不建议使用（未实现）

各类 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。等待完成：

json

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

TTS（tts）

json

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

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

表情（emoticon）

json

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

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

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

定点导航（pilot_task）

json

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

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

设置（setting）

json

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

active_wakeup: true：主动唤醒收音
quit_voice: true：退出全双工对话

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

turn_left / turn_right 当前视为未真正实现；平移可用 move_left / move_right。

端到端示例

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" }
          }
        }
      ]
    }
  ]
}

Swift 侧通过 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": "pilot_task",
        "config": {
          "control_type": "pilot_start_task",
          "title": "固定线路讲解",
          "play_tts": true
        }
      }
    ]
  }]
}

④ 继续任务 / ⑤ 取消任务：control_type 分别用 pilot_resume_task / pilot_stop_task。

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