Active Interaction Development Guide

Active interaction lets the SDK issue requests to the robot. v1.3.0 first exposed the active surface — alongside task flow it also shipped skill-query, state-query, pull-stream and push-listen interfaces, but those were never enabled at runtime; only task flow was ever functional. v1.4.0 therefore removes the never-enabled entries from the public API and narrows the surface to Task Flow. The corresponding classes remain in the source tree but are no longer exposed via AgentSdk.register*.

State push, greeting signals, video passthrough and face/voiceprint UID have all been folded into Passive Callback base methods.

Task Flow

Task flow dispatches a multi-step task sequence to a robot. Two modes are supported:

SIMPLE: Single-step task (startRequest directly contains the payload, no taskRequest needed)
COMPLEX: Multi-step task (start -> task x N -> end)

Complete Lifecycle Example (COMPLEX Mode)

java

// Step 1: Create task flow (specify target robot and flow ID)
String flowId = IdGenerator.generateFlowId();
TaskFlowRequest flow = new TaskFlowRequest(agentSdk, "AGENT_001", flowId, FlowMode.COMPLEX);

// Step 2: Register with SDK
agentSdk.registerTaskFlow(flow);

// Step 3: Start flow (payload is a JSON array; see taskflow_payload.md for the full protocol)
flow.startRequest("[{\"goal\":\"navigate_to_kitchen\"}]", new FlowStartCallback() {
    @Override
    public void onStartRequestAck(String flowId, String eventId, int code, String msg) {
        // code=0 means the robot has received the request
        System.out.println("Start confirmed: " + (code == 0 ? "success" : "failed:" + msg));
    }

    @Override
    public void onStartExecuteAck(String flowId, String eventId, int code, String msg) {
        // Robot begins execution
        System.out.println("Execution started");
    }
}, 10000); // 10-second timeout

// Step 4: Dispatch task steps (can be called multiple times)
flow.taskRequest("[{\"action\":\"turn_left\",\"angle\":90}]", new FlowTaskCallback() {
    @Override
    public void onTaskRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("Task confirmed: " + (code == 0 ? "success" : "failed:" + msg));
    }

    @Override
    public void onTaskExecuteAck(String flowId, String eventId, int code, String msg) {
        System.out.println("Task execution complete");
    }
}, 30000);

// Step 5: End flow
flow.endRequest(new FlowEndCallback() {
    @Override
    public void onEndRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("Flow ended: " + (code == 0 ? "success" : "failed:" + msg));
    }
}, 10000);

// Step 6: Unregister when done
agentSdk.unregisterTaskFlow(flowId);

Interrupt Flow

java

flow.interruptRequest(new FlowInterruptCallback() {
    @Override
    public void onInterruptRequestAck(String flowId, String eventId, int code, String msg) {
        System.out.println("Interrupt: " + (code == 0 ? "success" : "failed:" + msg));
    }
}, 10000);

Callback Parameters

Parameter	Description
`flowId`	Unique flow identifier
`eventId`	Unique identifier for this specific request
`code`	0=success, non-zero=failure
`msg`	"success" on success, error description on failure

Payload protocol (skill orchestration)

The payload argument of startRequest / taskRequest is a JSON array of one or more action_group items, each containing a list of action entries (TTS, motion, expression, navigation, settings, …). Even when you dispatch a single action_group, wrap it in an array ([{...}]); a bare object is not accepted. For the full protocol, every action_type's fields, and end-to-end SIMPLE / COMPLEX examples see:

👉 Task-flow payload protocol

State Listen

v1.4.0 change: state listening has been folded into PassiveCallback.onState(...); there is no separate registration anymore.

Just override the method on whichever passive callback you already register:

java

agentSdk.registerAudio2Tts(new Audio2TtsCallback(agentSdk) {
    @Override
    public void onState(String agentId, String eventId, String stateName, String stateValue) {
        System.out.println("State change: " + stateName + " = " + stateValue);
        // stateValue may be a JSON string that needs to be parsed manually
    }
    // ... other callbacks ...
});

Timeout

Each TaskFlowRequest method takes a timeout parameter in milliseconds; if no response arrives before the timeout, the callback is not invoked and resources are cleaned up automatically:

Operation	Recommended timeout	Overall lifecycle
`startRequest` / `taskRequest` / `endRequest` / `interruptRequest`	application-defined	flow auto-cleaned after 2 hours

APIs not exposed in this release

Skill query (querySkill), state query (queryState), pull stream (registerPullStream) and push listen (registerPushListen) had their registration methods removed from AgentSdk in v1.4.0, and this guide no longer documents them. The underlying SkillQueryRequest / StateQueryRequest / PullStreamRequest / PushListenCallback classes are still on disk for potential future re-enablement.