Teleop API
Teleop API
⚠️ Not yet released: in-development v1.5.0-SNAPSHOT capability; interface and protocol may change. Do not use in production before the official release.
New in v1.5.0. All classes are re-exported from the top-level package:
from linksoul_agentsdk import TeleopRequest, TeleopEnterCallback, TeleopKeepaliveCallback, TeleopExitCallback. See the Teleop guide for semantics.
Class diagram
text
AgentSdk
├── register_teleop(TeleopRequest) # binds LinkskyClient
└── unregister_teleop(teleop_id: str) -> None
TeleopRequest
├── __init__(agent_sdk, agent_id, teleop_id)
├── enter(param: AgentParam | None, cb: TeleopEnterCallback, timeout: int) -> str
├── start_audio(param: AgentParam | None = None) -> str
├── append_audio_delta(event_id: str, audio_delta: str, gain: float = 1.0) -> None
├── done_audio(event_id: str) -> None
├── keepalive(cb: TeleopKeepaliveCallback, timeout: int) -> str
└── exit(cb: TeleopExitCallback, timeout: int) -> str
TeleopEnterCallback # abstract base
└── on_enter_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None
TeleopKeepaliveCallback # abstract base
└── on_keepalive_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None
TeleopExitCallback # abstract base
└── on_exit_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None
IdGenerator
└── generate_teleop_id() -> str # "teleop_<21 random chars>"
AgentSdk (new methods)
| Method | Notes |
|---|---|
register_teleop(request: TeleopRequest) -> None | Binds the request to this SDK's LinkskyClient and inserts it into the global AgentSdkTeleopMgr. Must be called before request.enter(...). |
unregister_teleop(teleop_id: str) -> None | Removes the request from the index. Call after exit, or when abandoning the session. |
TeleopRequest
python
TeleopRequest(agent_sdk: AgentSdk, agent_id: str, teleop_id: str)
| Method | Semantics |
|---|---|
enter(param, cb, timeout) -> str | Open the teleop session. param may be None. timeout < 50 is clamped to 50 (currently a placeholder — no timeout callback yet). Returns this message's event_id. |
start_audio(param=None) -> str | Fire-and-forget audio-segment start. param may be None; common keys: role ("male" / "female"), threshold (-14 ~ 14). Returns the event_id you must reuse for subsequent append_audio_delta / done_audio. |
append_audio_delta(event_id, audio_delta, gain=1.0) -> None | Fire-and-forget audio delta. audio_delta is a base64 string; sample rate / encoding match the passive audioData path. Optional gain is an amplification factor, default 1.0, valid range (0, 10]; gain <= 0 is normalized to 1.0, gain > 10 is clamped to 10.0, sent on the message's gain field. |
done_audio(event_id) -> None | Fire-and-forget audio-segment end. You may start_audio again to open a new segment. |
keepalive(cb, timeout) -> str | Robot online probe. Fire-and-forget request whose result is delivered via on_keepalive_ack; code == 0 = robot online, code == -1 = robot offline. Recommend calling every 10 seconds during the session. timeout handled the same way as enter. Returns this message's event_id. |
exit(cb, timeout) -> str | Close the session. Timeout handling identical to enter. |
update_ts (property) | Last-send timestamp in ms. Idle > 7200 s gets swept. |
agent_id / teleop_id (property) | Session identity. |
enter_callback / exit_callback (property) | Most recent callback objects. |
Ack codes
code | Meaning |
|---|---|
0 | Success (gateway-level business ack) |
-1 | Server rejected; msg carries errorMsg |
1000 | Local failure: SDK's LinkskyClient was closed at send time. The callback is invoked synchronously on the caller thread; stop pushing audio. |
TeleopEnterCallback / TeleopKeepaliveCallback / TeleopExitCallback
Abstract bases; subclass and override on_enter_ack / on_keepalive_ack / on_exit_ack:
python
from linksoul_agentsdk import TeleopEnterCallback, TeleopKeepaliveCallback
class MyEnterCallback(TeleopEnterCallback):
def on_enter_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
# code == 0 success; -1 server reject; 1000 local closed
...
class MyKeepaliveCallback(TeleopKeepaliveCallback):
def on_keepalive_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
# code == 0 robot online; -1 robot offline (msg carries errorMsg); 1000 local closed
...
Base class also carries a timeout: int field (SDK-injected via set_timeout(...), clamped placeholder ≥50 ms).
IdGenerator.generate_teleop_id()
Returns "teleop_<21 secrets chars>". Distinct from other prefixes (flow_, event_, item_, pull_, signal_).
Event types
See the AGENTSDK_TELEOP_* block in Enums.