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

Teleop（超视距遥操）API

Teleop（超视距遥操）API

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

v1.5.0 新增。类均位于包 com.agibot.aiem.sdk.teleop / com.agibot.aiem.sdk。使用流程见 Teleop 指南。

类图

text
AgentSdk
  ├── registerTeleop(TeleopRequest)              // 关联 LinkskyClient
  └── unregisterTeleop(String teleopId)

TeleopRequest
  ├── constructor(AgentSdk, agentId, teleopId)
  ├── enter(AgentParam param, TeleopEnterCallback cb, long timeoutMs) → String eventId
  ├── startAudio(AgentParam param)                                    → String eventId
  ├── appendAudioDelta(String eventId, String audioDeltaBase64)
  ├── appendAudioDelta(String eventId, String audioDeltaBase64, double gain)
  ├── doneAudio(String eventId)
  ├── keepalive(TeleopKeepaliveCallback cb, long timeoutMs)           → String eventId
  └── exit(TeleopExitCallback cb, long timeoutMs)                     → String eventId

TeleopEnterCallback (abstract)
  └── onEnterAck(String teleopId, String eventId, int code, String msg)

TeleopKeepaliveCallback (abstract)
  └── onKeepaliveAck(String teleopId, String eventId, int code, String msg)

TeleopExitCallback (abstract)
  └── onExitAck(String teleopId, String eventId, int code, String msg)

IdGenerator
  └── generateTeleopId()  → "teleop_<21 位随机字符>"

AgentSdk（新增方法）

方法说明
void registerTeleop(TeleopRequest request)将 request 与当前 SDK 的 LinkskyClient 绑定，并加入全局 AgentSdkTeleopMgr 索引。必须在调用 request.enter(...) 之前调用。
void unregisterTeleop(String teleopId)从索引中移除。exit 完成或不再需要该会话时调用，避免依赖 7200s 后台清理。

TeleopRequest

java
public TeleopRequest(AgentSdk agentSdk, String agentId, String teleopId)
  • agentId：目标机器人的 agentId（由灵心开放平台颁发）；
  • teleopId：会话 ID，一般用 IdGenerator.generateTeleopId() 生成。同一次遥操生命周期内固定。
方法语义
String enter(AgentParam param, TeleopEnterCallback cb, long timeoutMs)进入遥操会话。param 可为 null；timeoutMs < 50 会被 clamp 到 50（当前仅存储不生效，用于未来触发超时回调）。返回本次消息 eventId。
String startAudio(AgentParam param)声明本段音频开始（fire-and-forget）。param 可为 null；常用键：role（man / woman）、threshold（-14 ~ 14）。返回 eventId；后续 appendAudioDelta / doneAudio 必须使用同一个 eventId。
void appendAudioDelta(String eventId, String audioDeltaBase64)追加音频块。audioDeltaBase64 是 base64 字符串，采样率 / 编码与被动交互 audioData 一致。等价于 gain = 1.0。fire-and-forget。
void appendAudioDelta(String eventId, String audioDeltaBase64, double gain)带音频增益的追加。gain 为增益倍数，默认 1.0，有效范围 (0, 10]；gain <= 0 归一为 1.0，gain > 10 截断为 10.0。增益随消息 gain 字段一起下发，由服务端应用。
void doneAudio(String eventId)声明本段音频结束（fire-and-forget）。可再次 startAudio 开新一段。
String keepalive(TeleopKeepaliveCallback cb, long timeoutMs)机器人在线探活。fire-and-forget 的探活请求，通过 onKeepaliveAck 回传结果；code == 0 表示机器人在线，code == -1 表示机器人离线。建议每 10 秒定时调用一次；timeoutMs 处理规则同 enter。返回本次消息 eventId。
String exit(TeleopExitCallback cb, long timeoutMs)退出遥操。timeoutMs 处理规则同 enter。返回本次消息 eventId。
long getUpdateTs()最近一次消息发送时间（毫秒）。7200s 无活动会被后台清理。

回调错误码

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

TeleopEnterCallback / TeleopKeepaliveCallback / TeleopExitCallback

抽象类，业务侧继承并覆盖 onEnterAck / onKeepaliveAck / onExitAck：

java
TeleopEnterCallback cb = new TeleopEnterCallback() {
    @Override
    public void onEnterAck(String teleopId, String eventId, int code, String msg) {
        // code == 0 成功；-1 服务端拒绝；1000 本地连接关闭
    }
};

TeleopKeepaliveCallback keepaliveCb = new TeleopKeepaliveCallback() {
    @Override
    public void onKeepaliveAck(String teleopId, String eventId, int code, String msg) {
        // code == 0 机器人在线；-1 机器人离线（msg 含 errorMsg）；1000 本地连接关闭
    }
};

三者都通过 Lombok @Getter/@Setter 暴露 agentId（SDK 内部注入）和 timeout（enter/keepalive/exit 时的 clamp 值）字段。

IdGenerator.generateTeleopId()

生成形如 teleop_ABCDEFGHIJKLMNOPQRSTU 的会话 ID（前缀 + 21 位 SecureRandom 字符）。与 flowId / eventId 等其他前缀互不冲突。

事件类型（AgentEventType）

见 Enums 参考 中的 AGENTSDK_TELEOP_* 段。