主动交互示例

源码位置：agentsdk_for_java/example/src/main/java/com/agibot/aiem/active/

主动交互在 v1.3.0 起就开放了接口（一并暴露过技能查询 / 状态查询 / 拉流 / 推流监听，但这些接口实际未启用，只有任务流真正可用）。v1.4.0 把这些未启用接口从公开 API 移除，对外公开入口收敛为 任务流（registerTaskFlow / unregisterTaskFlow），对应的 example 文件也只有 TaskFlowExample.java。

主动交互的通用骨架

java

String url = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk";
String appId = "您通过灵心开放平台创建的应用获取的appId";
String appKey = "您通过灵心开放平台创建的应用获取的appKey";
String appSecret = "您通过灵心开放平台创建的应用获取的appSecret";
String agentId = "您通过灵心开放平台配置的智能体 agentId";

// 第一步：创建 SDK 实例
AgentSdk agentSdk = AgentSdk.create(url, appId, appKey, appSecret);

// 第二步：注册验签回调
agentSdk.registerAuth(new AgentAuthCallback() {
    @Override
    public void onAuthState(String appId, int code, String msg) {
        System.out.println("onAuthState => appId: " + appId
            + ", code: " + code + ", msg: " + msg);
    }
});

// 第三步：初始化（建立 WebSocket 连接）
agentSdk.initialize();

Thread.sleep(2000);   // 等待鉴权完成

// 第四步：发起主动交互（见下文示例）

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

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

源码：active/TaskFlowExample.java
TaskFlowRequest 把"机器人执行多步任务"抽象成一条流水线： startRequest（必须） → taskRequest（可选，可多次） → endRequest（可选） → interruptRequest（可选）。每个方法都有两阶段确认：RequestAck 表示请求被机器人收到，ExecuteAck 表示该步已执行完成。
本示例的 payload 用占位 "[{}]" 演示流程；真实业务请按任务流 payload 协议填写 action_group / action_type。

1) 注册任务流

java

String flowId = IdGenerator.generateFlowId();
TaskFlowRequest taskFlowRequest = new TaskFlowRequest(agentSdk, agentId, flowId);
agentSdk.registerTaskFlow(taskFlowRequest);

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

java

taskFlowRequest.interruptRequest(new FlowInterruptCallback() {
    @Override
    public void onInterruptRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("onInterruptRequestAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }
}, 2000);

3) 启动请求（必须）

java

String startRequestPayload = "[{}]";
taskFlowRequest.startRequest(startRequestPayload, new FlowStartCallback() {

    @Override
    public void onStartRequestAck(String flowId, String eventId, int code, String msg) {
        // 机器人已收到 start 请求
        System.out.println("onStartRequestAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

    @Override
    public void onStartExecuteAck(String flowId, String eventId, int code, String msg) {
        // 机器人 start 阶段执行完成
        System.out.println("onStartExecuteAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

}, 2000);

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

java

String taskRequestPayload = "[{}]";
taskFlowRequest.taskRequest(taskRequestPayload, new FlowTaskCallback() {

    @Override
    public void onTaskRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("onTaskRequestAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

    @Override
    public void onTaskExecuteAck(String flowId, String eventId, int code, String msg) {
        System.out.println("onTaskExecuteAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

}, 2000);

5) 结束请求（可选）

java

taskFlowRequest.endRequest(new FlowEndCallback() {

    @Override
    public void onEndRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("onEndRequestAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

}, 2000);

任务流回调一览

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

TaskFlow 选择 SIMPLE 还是 COMPLEX？

TaskFlowRequest 的构造函数支持两种模式（不传则默认 COMPLEX）：

java

// COMPLEX：start → task × N → end（适合多步任务）
new TaskFlowRequest(agentSdk, agentId, flowId);
new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.COMPLEX);

// SIMPLE：startRequest 自带完整 payload，不需要 taskRequest
new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.SIMPLE);

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

状态变化推送已合并到 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);
    }
    // ... 其他回调 ...
});