主动交互开发指南

主动交互是 SDK 向机器人发起请求的能力。v1.3.0 起在接口层面开放（彼时一并暴露过技能查询 / 状态查询 / 拉流 / 推流监听等接口，但这些接口实际未启用，只有任务流真正可用）。v1.4.0 顺势把这些未启用接口从公开 API 中移除，公开入口收敛到 任务流——底层类仍保留在源码里，但不再通过 AgentSdk.register* 公开。

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

任务流

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

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

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

java

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

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

// ③ 启动流程（payload 是 JSON 数组，详细协议见 taskflow_payload.md）
flow.startRequest("[{\"goal\":\"navigate_to_kitchen\"}]", new FlowStartCallback() {
    @Override
    public void onStartRequestAck(String flowId, String eventId, int code, String msg) {
        // code=0 表示机器人已收到请求
        System.out.println("启动确认: " + (code == 0 ? "成功" : "失败:" + msg));
    }

    @Override
    public void onStartExecuteAck(String flowId, String eventId, int code, String msg) {
        // 机器人开始执行
        System.out.println("开始执行");
    }
}, 10000); // 超时10秒

// ④ 下发任务步骤（可多次调用）
flow.taskRequest("[{\"action\":\"turn_left\",\"angle\":90}]", new FlowTaskCallback() {
    @Override
    public void onTaskRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("任务确认: " + (code == 0 ? "成功" : "失败:" + msg));
    }

    @Override
    public void onTaskExecuteAck(String flowId, String eventId, int code, String msg) {
        System.out.println("任务执行完成");
    }
}, 30000);

// ⑤ 结束流程
flow.endRequest(new FlowEndCallback() {
    @Override
    public void onEndRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("流程结束: " + (code == 0 ? "成功" : "失败:" + msg));
    }
}, 10000);

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

中断流程

java

flow.interruptRequest(new FlowInterruptCallback() {
    @Override
    public void onInterruptRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("中断: " + (code == 0 ? "成功" : "失败:" + msg));
    }
}, 10000);

回调参数说明

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

startRequest / taskRequest 的 payload 是 JSON 数组，由若干 action_group 组成，每个 group 包含一组 action（TTS、动作、表情、导航、设置等）。即使只下发一个 action_group，也必须放进数组里（[{...}]），不能直接传单个对象。完整协议、各 action_type 字段以及 SIMPLE / COMPLEX 两种模式的端到端示例请参见：

👉 任务流 payload 协议

状态监听

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

直接在已注册的被动回调里重载即可：

java

agentSdk.registerAudio2Tts(new Audio2TtsCallback(agentSdk) {
    @Override
    public void onState(String agentId, String eventId, String stateName, String stateValue) {
        System.out.println("状态变化: " + stateName + " = " + stateValue);
        // stateValue 可能是 JSON 字符串，需要自行解析
    }
    // ... 其他回调 ...
});

超时机制

TaskFlowRequest 的每个请求方法都支持 timeout 参数（单位：毫秒），超时未收到响应后回调不会被触发，资源自动清理：

操作	建议超时	自动清理时间
`startRequest` / `taskRequest` / `endRequest` / `interruptRequest`	业务自定	任务流整体 2 小时

不再开放的接口

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