AIMA开放平台文档中心Agent SDK (Python)

Teleop（超视距遥操）API

Teleop（超视距遥操）API

⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。

v1.5.0 新增。所有类均从 linksoul_agentsdk 顶层重新导出：from linksoul_agentsdk import TeleopRequest, TeleopEnterCallback, TeleopKeepaliveCallback, TeleopExitCallback。使用流程见 Teleop 指南。

类图

text
AgentSdk
  ├── register_teleop(TeleopRequest)                # 关联 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           # 抽象基类
  └── on_enter_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None

TeleopKeepaliveCallback       # 抽象基类
  └── on_keepalive_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None

TeleopExitCallback            # 抽象基类
  └── on_exit_ack(teleop_id: str, event_id: str, code: int, msg: str) -> None

IdGenerator
  └── generate_teleop_id() -> str    # "teleop_<21 位随机字符>"

AgentSdk（新增方法）

方法说明
register_teleop(request: TeleopRequest) -> None将 request 与当前 SDK 的 LinkskyClient 绑定，并加入全局 AgentSdkTeleopMgr 索引。必须在调用 request.enter(...) 之前调用。
unregister_teleop(teleop_id: str) -> None从索引中移除。exit 完成或不再需要该会话时调用。

TeleopRequest

python
TeleopRequest(agent_sdk: AgentSdk, agent_id: str, teleop_id: str)
方法语义
enter(param, cb, timeout) -> str进入遥操会话。param 可为 None；timeout < 50 会被 clamp 到 50（当前仅存储不生效）。返回本次消息 event_id。
start_audio(param=None) -> str声明本段音频开始（fire-and-forget）。param 可为 None；常用键：role（"male" / "female"）、threshold（-14 ~ 14）。返回 event_id；后续 append_audio_delta / done_audio 必须使用同一个 event_id。
append_audio_delta(event_id, audio_delta, gain=1.0) -> None追加音频块。audio_delta 是 base64 字符串，采样率 / 编码与被动交互 audioData 一致。fire-and-forget。可选 gain 为音频增益倍数，默认 1.0，有效范围 (0, 10]；gain <= 0 归一为 1.0，gain > 10 截断为 10.0，随消息 gain 字段下发。
done_audio(event_id) -> None声明本段音频结束（fire-and-forget）。可再次 start_audio 开新一段。
keepalive(cb, timeout) -> str机器人在线探活。fire-and-forget 的探活请求，通过 on_keepalive_ack 回传结果；code == 0 表示机器人在线，code == -1 表示机器人离线。建议每 10 秒定时调用一次；timeout 处理规则同 enter。返回本次消息 event_id。
exit(cb, timeout) -> str退出遥操。timeout 处理规则同 enter。返回本次消息 event_id。
update_ts (property)最近一次消息发送时间（毫秒）。7200s 无活动会被后台清理。
agent_id / teleop_id (property)会话身份
enter_callback / exit_callback (property)最近一次绑定的回调对象

回调错误码

code含义
0成功（网关业务层 ACK）
-1服务端返回失败，msg 携带 errorMsg 详情
1000本地失败：发送时 SDK 侧 LinkskyClient 已 closed；SDK 会同步在原线程回调该 code，业务侧应视为发送失败，避免继续下发音频

TeleopEnterCallback / TeleopKeepaliveCallback / TeleopExitCallback

抽象基类，继承并覆盖 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 成功；-1 服务端拒绝；1000 本地连接关闭
        ...

class MyKeepaliveCallback(TeleopKeepaliveCallback):
    def on_keepalive_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
        # code == 0 机器人在线；-1 机器人离线（msg 含 errorMsg）；1000 本地连接关闭
        ...

基类还包含 timeout: int 字段（由 set_timeout(...) 由 SDK 内部注入，clamp 到 ≥50ms 的占位值）。

IdGenerator.generate_teleop_id()

生成形如 teleop_ABCDEFGHIJKLMNOPQRSTU 的会话 ID（前缀 + 21 位 secrets 随机字符）。与 flow_ / event_ / item_ / pull_ / signal_ 等其他前缀互不冲突。

事件类型（AgentEventType）

见 枚举参考 中的 AGENTSDK_TELEOP_* 段。