主动交互开发指南 · iOS

主动交互是 SDK 向机器人发起请求的能力。与 Java v1.5.0 一致，公开入口收敛到 任务流——技能查询 / 状态查询 / 拉流 / 推流监听等接口在 v1.4.0 已从公开 API 移除（底层类仍保留在源码里）。

状态推送、打招呼信令、视频帧透传、人脸/声纹 UID 等场景已统一并入被动交互的 PassiveCallback 基类方法。

任务流

任务流用于向机器人下发多步任务序列。支持两种模式：

SIMPLE：单步任务（startRequest 中直接包含 payload，无需 taskRequest）
COMPLEX：多步任务（start → task × N → end）

完整生命周期示例（COMPLEX 模式）

swift

// ① 创建任务流（指定目标机器人和流程 ID）
let flowId = IdGenerator.generateFlowId()
let flow = TaskFlowRequest(agentSdk: agentSdk, agentId: "AGENT_001", flowId: flowId)

// ② 注册到 SDK
agentSdk.registerTaskFlow(flow)

// ③ 启动流程（payload 是 JSON 数组字符串，详见 taskflow_payload.md）
flow.startRequest(payload: "[{\"goal\":\"navigate_to_kitchen\"}]",
                  startCallback: MyFlowStartCallback(), timeout: 10000)

// ④ 下发任务步骤（可多次调用）
flow.taskRequest(payload: "[{\"action\":\"turn_left\",\"angle\":90}]",
                 taskCallback: MyFlowTaskCallback(), timeout: 30000)

// ⑤ 结束流程
flow.endRequest(endCallback: MyFlowEndCallback(), timeout: 10000)

// ⑥ 用完取消注册
agentSdk.unregisterTaskFlow(flowId: flowId)

回调为 open class，继承并重载：

swift

final class MyFlowStartCallback: FlowStartCallback {
    override func onStartRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("启动确认: \(code == 0 ? "成功" : "失败: \(msg ?? "")")")
    }
    override func onStartExecuteAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("开始执行")
    }
}

中断流程

swift

flow.interruptRequest(interruptCallback: MyFlowInterruptCallback(), timeout: 10000)

回调参数说明

参数	说明
`flowId`	流程唯一标识
`eventId`	本次请求的唯一标识
`code`	0=成功，非 0=失败
`msg`	成功时为 "success"，失败时为错误描述

payload 协议（编排技能）

startRequest / taskRequest 的 payload 是 JSON 数组，由若干 action_group 组成，每个 group 包含一组 action（TTS、动作、表情、导航、设置等）。即使只下发一个 action_group，也必须放进数组里（[{...}]），不能直接传单个对象。完整协议参见：

👉 任务流 payload 协议

状态监听

v1.4.0 变更：状态监听已合并到被动交互的 PassiveCallback.onState(...)，无需再单独注册。

swift

final class MyAudio2Tts: Audio2TtsCallback {
    override func onState(agentId: String, eventId: String, stateName: String, stateValue: String) {
        print("状态变化: \(stateName) = \(stateValue)")
    }
}

超时机制

TaskFlowRequest 的每个请求方法都支持 timeout 参数（单位：毫秒），最小 50ms：

操作	建议超时	说明
`startRequest` / `taskRequest` / `endRequest` / `interruptRequest`	业务自定	超时未收到响应后回调不被触发，资源自动清理

技能查询（querySkill）、状态查询（queryState）、拉流（registerPullStream）、推流监听（registerPushListen）的注册方法已在 v1.4.0 从 AgentSdk 移除。 SkillQueryRequest / StateQueryRequest / PullStreamRequest / PushListenCallback 等底层类仍保留在源码中，便于后续重新启用。