Active Interaction Examples

Source location: agentsdk_for_java/example/src/main/java/com/agibot/aiem/active/

v1.3.0 first exposed the active surface (alongside task flow it also shipped skill-query, state-query, pull-stream and push-listen) — but those companion entries were never functional at runtime, only task flow worked. v1.4.0 therefore removes the never-enabled entries and narrows the public surface to Task Flow (registerTaskFlow / unregisterTaskFlow); the example directory likewise ships only TaskFlowExample.java.

Active-interaction skeleton

java

String url = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk";
String appId = "<your appId>";
String appKey = "<your appKey>";
String appSecret = "<your appSecret>";
String agentId = "<the target agentId configured on the LinkSoul open platform>";

// Step 1: create the SDK instance
AgentSdk agentSdk = AgentSdk.create(url, appId, appKey, appSecret);

// Step 2: register the auth callback
agentSdk.registerAuth(new AgentAuthCallback() {
    @Override
    public void onAuthState(String appId, int code, String msg) {
        System.out.println("onAuthState => appId: " + appId
            + ", code: " + code + ", msg: " + msg);
    }
});

// Step 3: initialize (opens the WebSocket)
agentSdk.initialize();

Thread.sleep(2000);   // wait for auth to settle

// Step 4: issue active requests (see below)

Note: unlike passive callbacks, active requests must be issued after initialize().

TaskFlowExample — task flow (start / task / end / interrupt)

Source: active/TaskFlowExample.java
TaskFlowRequest models a multi-step robot task as a pipeline: startRequest (required) → taskRequest (optional, repeatable) → endRequest (optional) → interruptRequest (optional). Each call has two-phase acknowledgement: RequestAck = the robot received the request, ExecuteAck = the robot finished that step.
This example uses "[{}]" placeholders for payload to keep the flow simple. Real-world payloads should follow the Task-flow payload protocol — fill in action_group / action_type entries there.

1) Register the task flow

java

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

2) Interrupt (optional, callable at any stage)

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) Start request (required)

java

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

    @Override
    public void onStartRequestAck(String flowId, String eventId, int code, String msg) {
        // The robot acknowledged the start request
        System.out.println("onStartRequestAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

    @Override
    public void onStartExecuteAck(String flowId, String eventId, int code, String msg) {
        // The start phase finished executing on the robot
        System.out.println("onStartExecuteAck => flowId: " + flowId
                + ", eventId: " + eventId + ", code: " + code + ", msg: " + msg);
    }

}, 2000);

4) Task request (optional, repeatable)

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) End request (optional)

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);

Task-flow callbacks at a glance

Callback	Trigger	Meaning
`onStartRequestAck`	Start request reached the robot	`code=0` means the request was accepted
`onStartExecuteAck`	Start phase finished	Ready for `taskRequest` calls
`onTaskRequestAck`	A task step reached the robot	The step request was accepted
`onTaskExecuteAck`	The task step finished	Move on to the next step
`onEndRequestAck`	End request processed	The pipeline is closed
`onInterruptRequestAck`	Interrupt processed	The robot was told to abort

SIMPLE vs COMPLEX

TaskFlowRequest accepts a FlowMode (defaults to COMPLEX):

java

// COMPLEX: start -> task x N -> end (multi-step tasks)
new TaskFlowRequest(agentSdk, agentId, flowId);
new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.COMPLEX);

// SIMPLE: startRequest carries the full payload, no taskRequest needed
new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.SIMPLE);

State listening (received via the passive callback)

State pushes have been folded into PassiveCallback.onState(...). Just override the method on any registered passive callback — see Passive Callbacks Guide - Shared base callbacks.

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);
    }
    // ... other callbacks ...
});