Active Requests API Reference

v1.3.0 → v1.4.0: v1.3.0 first exposed the active surface (task flow plus skill-query, state-query, pull-stream and push-listen). The companion entries were never functional at runtime; only task flow worked. v1.4.0 therefore removes those never-enabled entries and narrows the public surface to a single entry — the task flow. Skill query, state query, pull stream and push listen are not exposed in this release. State push has been merged into PassiveCallback.onState(...); see the Passive callbacks guide.

TaskFlowRequest

Construction

java

// COMPLEX mode (default)
TaskFlowRequest flow = new TaskFlowRequest(agentSdk, agentId, flowId);

// Specify mode
TaskFlowRequest flow = new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.SIMPLE);

Methods

Method	Return Type	Description
`startRequest(payload, callback, timeout)`	`String` (eventId)	Start the flow
`taskRequest(payload, callback, timeout)`	`String` (eventId)	Send a task step
`endRequest(callback, timeout)`	`String` (eventId)	End the flow
`interruptRequest(callback, timeout)`	`String` (eventId)	Interrupt the flow
`getFlowId()`	`String`	Get the flow ID
`getAgentId()`	`String`	Get the target agent ID (the agent ID configured on the LinkSoul platform)

payload: JSON string (the protocol requires a JSON array, e.g. "[{...}]"; see Task-flow payload protocol)
timeout: Timeout in milliseconds, minimum 50ms

Flow Callbacks

java

public abstract class FlowStartCallback {
    public abstract void onStartRequestAck(String flowId, String eventId, int code, String msg);
    public abstract void onStartExecuteAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowTaskCallback {
    public abstract void onTaskRequestAck(String flowId, String eventId, int code, String msg);
    public abstract void onTaskExecuteAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowEndCallback {
    public abstract void onEndRequestAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowInterruptCallback {
    public abstract void onInterruptRequestAck(String flowId, String eventId, int code, String msg);
}

Two-phase acknowledgment: RequestAck = robot received the request, ExecuteAck = robot finished execution. code=0 indicates success.

Utility Classes

AgentParam (Extension Parameters)

A key-value container supporting chained calls:

java

// Create and set parameters
AgentParam param = AgentParam.create()
    .setString("action", "navigate")
    .setInteger("step", 3)
    .setDouble("speed", 1.5)
    .setBoolean("safe", true)
    .setLong("timestamp", System.currentTimeMillis());

// Read parameters
String action = param.getString("action");
Integer step = param.getInteger("step");

Complete method list:

Method	Type
`getString/setString`	String
`getInteger/setInteger`	Integer
`getLong/setLong`	Long
`getDouble/setDouble`	Double
`getShort/setShort`	Short
`getBoolean/setBoolean`	Boolean
`getObject/setObject`	Object
`getList/setList`	List<?>
`getExtParam()`	Map (get underlying JSON object)

AgentMeta (Robot Metadata)

Obtained via onRobotOnline(agentId, agentMeta) when a robot comes online:

java

@Override
public void onRobotOnline(String agentId, AgentMeta agentMeta) {
    String wakeup = agentMeta.getWakeupWord();    // Wakeup word
    String city = agentMeta.getCity();            // City location
    String name = agentMeta.getRobotName();       // Robot name
    String buzzWord = agentMeta.getBuzzWord();    // Buzz word
    String custom = agentMeta.getString("yourKey"); // Custom field
}

IdGenerator (ID Generator)

java

String flowId = IdGenerator.generateFlowId();     // "flow_xxxxx..."
String eventId = IdGenerator.generateEventId();   // "event_xxxxx..."
String itemId = IdGenerator.generateItemId();     // "item_xxxxx..."
String signalId = IdGenerator.generateSignalId(); // "signal_xxxxx..."

All IDs consist of prefix + 21-character random string (uppercase/lowercase letters + digits), using SecureRandom to ensure uniqueness.