主动交互示例 · iOS

源码位置：agentsdk_for_ios/Examples/TaskFlowExample/main.swift

主动交互在 v1.4.0 起公开入口收敛为 任务流（registerTaskFlow / unregisterTaskFlow），对应示例文件只有 TaskFlowExample。

主动交互的通用骨架

swift

import Foundation
import LinksoulAgentSDK

let url = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk"
let appId = "<灵心开放平台应用 appId>"
let appKey = "<灵心开放平台应用 appKey>"
let appSecret = "<灵心开放平台应用 appSecret>"
let agentId = "<灵心开放平台配置的智能体 agentId>"

// ① 创建 SDK 实例
let agentSdk = AgentSdk.create(url: url, appId: appId, appKey: appKey, appSecret: appSecret)

// ② 注册鉴权回调
final class AuthCallback: AgentAuthCallback {
    func onAuthState(appId: String, code: Int, msg: String) {
        print("onAuthState => code=\(code), msg=\(msg)")
    }
}
agentSdk.registerAuth(AuthCallback())

// ③ 初始化（建立 WebSocket 连接）
agentSdk.initialize()

// ④ 发起主动交互（见下文示例）
RunLoop.main.run()

注意：与被动交互不同，主动交互在 initialize() 之后才能发起。

TaskFlowExample — 任务流（启动 / 任务 / 结束 / 打断）

TaskFlowRequest 把"机器人执行多步任务"抽象成一条流水线： startRequest（必须） → taskRequest（可选，可多次） → endRequest（可选） → interruptRequest（可选）。每个方法都有两阶段确认：RequestAck 表示请求被机器人收到，ExecuteAck 表示该步已执行完成。

1) 注册任务流

swift

let flowId = IdGenerator.generateFlowId()
let taskFlowRequest = TaskFlowRequest(agentSdk: agentSdk, agentId: agentId, flowId: flowId)
agentSdk.registerTaskFlow(taskFlowRequest)

2) 打断请求（可选，可在任意阶段调用）

swift

final class InterruptCb: FlowInterruptCallback {
    override func onInterruptRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onInterruptRequestAck => flowId: \(flowId), code: \(code)")
    }
}
taskFlowRequest.interruptRequest(interruptCallback: InterruptCb(), timeout: 2000)

3) 启动请求（必须）

swift

final class StartCb: FlowStartCallback {
    override func onStartRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onStartRequestAck => flowId: \(flowId), code: \(code)")
    }
    override func onStartExecuteAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onStartExecuteAck => flowId: \(flowId), code: \(code)")
    }
}
taskFlowRequest.startRequest(payload: "[{}]", startCallback: StartCb(), timeout: 2000)

4) 任务请求（可选，可多次调用）

swift

final class TaskCb: FlowTaskCallback {
    override func onTaskRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onTaskRequestAck => flowId: \(flowId), code: \(code)")
    }
    override func onTaskExecuteAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onTaskExecuteAck => flowId: \(flowId), code: \(code)")
    }
}
taskFlowRequest.taskRequest(payload: "[{}]", taskCallback: TaskCb(), timeout: 2000)

5) 结束请求（可选）

swift

final class EndCb: FlowEndCallback {
    override func onEndRequestAck(flowId: String, eventId: String, code: Int, msg: String?) {
        print("onEndRequestAck => flowId: \(flowId), code: \(code)")
    }
}
taskFlowRequest.endRequest(endCallback: EndCb(), timeout: 2000)

任务流回调一览

回调	触发时机	含义
`onStartRequestAck`	启动请求到达机器人	`code=0` 表示请求被接受
`onStartExecuteAck`	启动阶段执行完成	多步任务可以开始下发
`onTaskRequestAck`	任务步骤到达机器人	单步请求被接受
`onTaskExecuteAck`	任务步骤执行完成	可以继续下一步
`onEndRequestAck`	结束请求被处理	整条流水线已收口
`onInterruptRequestAck`	打断请求被处理	已通知机器人中断当前流程

TaskFlow 选择 SIMPLE 还是 COMPLEX？

swift

// COMPLEX：start → task × N → end（适合多步任务，默认）
TaskFlowRequest(agentSdk: agentSdk, agentId: agentId, flowId: flowId)

// SIMPLE：startRequest 自带完整 payload，不需要 taskRequest
TaskFlowRequest(agentSdk: agentSdk, agentId: agentId, flowId: flowId, flowMode: .simple)

状态监听（通过被动回调接收）

状态变化推送已合并到 PassiveCallback.onState(...)，直接在已注册的被动回调里重载即可：

swift

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