主动请求 API 参考 · iOS

v1.4.0：当前 AgentSdk 仅公开 任务流 一个主动入口。技能查询、状态查询、拉流、推流监听暂未开放。状态推送已合并到 PassiveCallback.onState(...)。

TaskFlowRequest

构造

swift

// COMPLEX 模式（默认）
let flow = TaskFlowRequest(agentSdk: agentSdk, agentId: agentId, flowId: flowId)

// 指定模式
let flow = TaskFlowRequest(agentSdk: agentSdk, agentId: agentId, flowId: flowId, flowMode: .simple)

方法

方法	返回值	说明
`startRequest(payload:startCallback:timeout:)`	`String` (eventId)	启动流程
`taskRequest(payload:taskCallback:timeout:)`	`String` (eventId)	发送任务步骤
`endRequest(endCallback:timeout:)`	`String` (eventId)	结束流程
`interruptRequest(interruptCallback:timeout:)`	`String` (eventId)	中断流程
`getTaskCallback(eventId:)` / `removeTaskCallback(eventId:)`	—	任务回调索引管理（内部使用）

payload: JSON 字符串（任务流协议要求为 JSON 数组，如 "[{...}]"，详见任务流 payload 协议）
timeout: 超时时间（毫秒），最小 50ms

流程回调

swift

open class FlowStartCallback: ActiveCallback {
    open func onStartRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {}
    open func onStartExecuteAck(flowId: String, eventId: String, code: Int, msg: String?) {}
}

open class FlowTaskCallback: ActiveCallback {
    open func onTaskRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {}
    open func onTaskExecuteAck(flowId: String, eventId: String, code: Int, msg: String?) {}
}

open class FlowEndCallback: ActiveCallback {
    open func onEndRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {}
}

open class FlowInterruptCallback: ActiveCallback {
    open func onInterruptRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {}
}

两阶段确认：RequestAck = 机器人收到请求，ExecuteAck = 机器人执行完成。code=0 表示成功。

工具类

AgentParam（扩展参数）

支持链式调用的键值对容器：

swift

let param = AgentParam.create()
    .setString("action", "navigate")
    .setInt("step", 3)
    .setDouble("speed", 1.5)
    .setBool("safe", true)
    .setInt64("timestamp", Int64(Date().timeIntervalSince1970 * 1000))

let action = param.getString("action")   // String?
let step = param.getInt("step")          // Int?

方法列表：

getter / setter	类型
`getString` / `setString(_:_:)`	String
`getInt` / `setInt(_:_:)`	Int
`getInt64` / `setInt64(_:_:)`	Int64
`getDouble` / `setDouble(_:_:)`	Double
`getBool` / `setBool(_:_:)`	Bool
`getObject` / `setObject(_:_:)`	Any
`getArray` / `setArray(_:_:)`	Any
`dictionary`	`[String: Any]`（获取底层字典）

AgentMeta（机器人元数据）

机器人上线时通过 onRobotOnline(agentId:agentMeta:) 获取：

swift

override func onRobotOnline(agentId: String, agentMeta: AgentMeta) {
    let wakeup = agentMeta.wakeupWord    // 唤醒词
    let city = agentMeta.city            // 所在城市
    let name = agentMeta.robotName       // 机器人名字
    let buzz = agentMeta.buzzWord        // 热词
    let custom = agentMeta.getString("yourKey")  // 自定义字段
}

IdGenerator（ID 生成器）

swift

let flowId = IdGenerator.generateFlowId()          // "flow_xxxxx..."
let eventId = IdGenerator.generateEventId()        // "event_xxxxx..."
let itemId = IdGenerator.generateItemId()          // "item_xxxxx..."
let pullId = IdGenerator.generatePullId()          // "pull_xxxxx..."
let signalId = IdGenerator.generateSignalId()      // "signal_xxxxx..."
let teleopId = IdGenerator.generateTeleopId()      // "teleop_xxxxx..."（v1.5.0）
let extSkillId = IdGenerator.generateExtSkillRequestId()  // "extskill_xxxxx..."（v1.5.0）

所有 ID 为 前缀 + 21 位随机字符串（大小写字母 + 数字）。