Active Requests API Reference

← Home

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 — task flow. Skill query, state query, pull stream and push listen are not exposed. State push has been merged into PassiveCallback.on_state(...); see the Passive callbacks guide.

TaskFlowRequest

Lives in linksoul_agentsdk.active.

Construction

python

from linksoul_agentsdk.active import TaskFlowRequest
from linksoul_agentsdk.enums import FlowMode

# COMPLEX mode (default)
flow = TaskFlowRequest(agent_sdk, agent_id, flow_id)

# Specify mode
flow = TaskFlowRequest(agent_sdk, agent_id, flow_id, FlowMode.SIMPLE)

Methods

Method	Returns	Description
`start_request(payload, callback, timeout)`	`str` (event_id)	Start the flow
`task_request(payload, callback, timeout)`	`str` (event_id)	Send a task step
`end_request(callback, timeout)`	`str` (event_id)	End the flow
`interrupt_request(callback, timeout)`	`str` (event_id)	Interrupt the flow
`flow_id` (property)	`str`	Flow id
`agent_id` (property)	`str`	Target agent id (the agent ID configured on the LinkSoul platform)
`flow_mode` (property)	`FlowMode`	Current mode

payload: JSON string (the protocol requires a JSON array, e.g. '[{...}]'; see Task-flow payload protocol)
timeout: milliseconds; values below 50 are clamped to 50

Flow callbacks

python

from linksoul_agentsdk.active import (
    FlowEndCallback,
    FlowInterruptCallback,
    FlowStartCallback,
    FlowTaskCallback,
)


class _Start(FlowStartCallback):
    def on_start_request_ack(self, flow_id, event_id, code, msg): ...
    def on_start_execute_ack(self, flow_id, event_id, code, msg): ...


class _Task(FlowTaskCallback):
    def on_task_request_ack(self, flow_id, event_id, code, msg): ...
    def on_task_execute_ack(self, flow_id, event_id, code, msg): ...


class _End(FlowEndCallback):
    def on_end_request_ack(self, flow_id, event_id, code, msg): ...


class _Interrupt(FlowInterruptCallback):
    def on_interrupt_request_ack(self, flow_id, event_id, code, msg): ...

Two-phase acknowledgement: RequestAck = the robot received the request; ExecuteAck = the robot finished executing. code == 0 means success. For one task_request, the request_ack and execute_ack share the same event_id.

Utility classes

`AgentParam`

Chained setters:

python

from linksoul_agentsdk import AgentParam
import time

param = (
    AgentParam.create()
    .set_string("action", "navigate")
    .set_integer("step", 3)
    .set_double("speed", 1.5)
    .set_boolean("safe", True)
    .set_long("timestamp", int(time.time() * 1000))
)

action = param.get_string("action")    # → "navigate"
step = param.get_integer("step")       # → 3

Method	Type
`get_string` / `set_string`	`str`
`get_integer` / `set_integer`	`int` (also `get_long` / `get_short`)
`get_double` / `set_double`	`float`
`get_boolean` / `set_boolean`	`bool` (accepts `"true"` / `"false"` strings on read)
`get_object` / `set_object`	`Any`
`get_list` / `set_list`	`list`
`get_ext_param()`	underlying `dict`

Note: bool is a subclass of int in Python — get_integer deliberately returns None for values stored via set_boolean to avoid silent 0/1 reads.

`AgentMeta`

Read-only metadata received via on_robot_online(agent_id, agent_meta):

python

def on_robot_online(self, agent_id: str, agent_meta: AgentMeta) -> None:
    wakeup = agent_meta.get_wakeup_word()
    city = agent_meta.get_city()
    name = agent_meta.get_robot_name()
    buzz_word = agent_meta.get_buzz_word()
    custom = agent_meta.get_string("your_key")

`IdGenerator`

python

from linksoul_agentsdk import IdGenerator

flow_id = IdGenerator.generate_flow_id()       # "flow_xxxxx..."
event_id = IdGenerator.generate_event_id()     # "event_xxxxx..."
item_id = IdGenerator.generate_item_id()       # "item_xxxxx..."
signal_id = IdGenerator.generate_signal_id()   # "signal_xxxxx..."

All IDs are <prefix>_ + 21 random characters (letters + digits) drawn from secrets.choice(...).