超视距遥操(Teleop)示例

超视距遥操(Teleop)示例

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

v1.5.0 新增。完整的 Python 端最小示例,展示 enter → start_audio → append_audio_delta → done_audio → exit 全流程。

最小示例

python
import time

from linksoul_agentsdk import (
    AgentAuthCallback,
    AgentParam,
    AgentSdk,
    IdGenerator,
    TeleopEnterCallback,
    TeleopExitCallback,
    TeleopKeepaliveCallback,
    TeleopRequest,
)

url        = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk"
app_id     = "您通过灵心开放平台创建的应用获取的appId"
app_key    = "您通过灵心开放平台创建的应用获取的appKey"
app_secret = "您通过灵心开放平台创建的应用获取的appSecret"
agent_id   = "您通过灵心平台创建的二开智能体获取的agentId"

# 第一步:创建 SDK 实例
agent_sdk = AgentSdk.create(url, app_id, app_key, app_secret)


# 第二步:注册验签回调
class MyAuthCallback(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        print(f"on_auth_state => app_id: {app_id}, code: {code}, msg: {msg}")


agent_sdk.register_auth(MyAuthCallback())

# 第三步:初始化
agent_sdk.initialize()
time.sleep(2)

# 注册遥操请求实例
teleop_id = IdGenerator.generate_teleop_id()
teleop_request = TeleopRequest(agent_sdk, agent_id, teleop_id)
agent_sdk.register_teleop(teleop_request)


# 进入遥操
class MyEnterCallback(TeleopEnterCallback):
    def on_enter_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
        print(f"on_enter_ack => teleop_id={teleop_id}, event_id={event_id}, code={code}, msg={msg}")


enter_param = AgentParam.create()
teleop_request.enter(enter_param, MyEnterCallback(), 2000)

# 开始说话
start_param = (
    AgentParam.create()
    .set_string("role", "male")       # male / female
    .set_integer("threshold", 0)      # -14 ~ 14
)
event_id = teleop_request.start_audio(start_param)
# 持续说话(这里以空字符串占位,实际传 base64 编码后的 PCM/Opus 分片)
teleop_request.append_audio_delta(event_id, "")
# 结束说话
teleop_request.done_audio(event_id)


# 检查机器人是否在线(详见「定时探活」小节,遥操期间应每 10s 探活一次)
class MyKeepaliveCallback(TeleopKeepaliveCallback):
    def on_keepalive_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
        print(f"on_keepalive_ack => teleop_id={teleop_id}, event_id={event_id}, code={code}, msg={msg}")


teleop_request.keepalive(MyKeepaliveCallback(), 2000)


# 退出遥操
class MyExitCallback(TeleopExitCallback):
    def on_exit_ack(self, teleop_id: str, event_id: str, code: int, msg: str) -> None:
        print(f"on_exit_ack => teleop_id={teleop_id}, event_id={event_id}, code={code}, msg={msg}")


teleop_request.exit(MyExitCallback(), 2000)

# 注销并释放(示例省略)
# agent_sdk.unregister_teleop(teleop_id)
# agent_sdk.release()

定时探活(keepalive)

enter 拿到 code == 0 之后,业务侧应每 10 秒发起一次 keepalive 探活;on_keepalive_ack 收到 code != 0 即视为机器人离线,需停止定时、退出遥操、注销资源。

python
import threading
from linksoul_agentsdk import TeleopKeepaliveCallback, TeleopExitCallback


def start_keepalive(teleop_request, agent_sdk, interval_sec: int = 10):
    """enter 成功后调用;每 interval_sec 秒探活一次"""
    state = {"online": True}

    def tick():
        if not state["online"]:
            return

        class _Cb(TeleopKeepaliveCallback):
            def on_keepalive_ack(self, teleop_id, event_id, code, msg):
                if code != 0 and state["online"]:
                    state["online"] = False
                    print(f"robot offline => code={code}, msg={msg}")

                    class _ExitCb(TeleopExitCallback):
                        def on_exit_ack(self, teleop_id, event_id, code, msg):
                            agent_sdk.unregister_teleop(teleop_id)
                    teleop_request.exit(_ExitCb(), 2000)

        teleop_request.keepalive(_Cb(), 2000)
        if state["online"]:
            threading.Timer(interval_sec, tick).start()

    threading.Timer(interval_sec, tick).start()
    return state  # 业务侧可通过 state["online"] = False 主动停止

业务侧主动 exit 后,也应 state["online"] = False 停止发送探活。

常见改写要点

想做改哪里
一次遥操中间多次讲话每次讲话都重新 start_audio(start_param) 拿到新的 event_id,append_audio_delta / done_audio 使用该 event_id,无需 exit 再 enter
切换音色 / 灵敏度每一段 start_audio 时重新填 AgentParam.role / threshold;不影响前一段音频
中途取消遥操直接 exit(...),不再补发 done_audio
感知 SDK 鉴权 / 断连在 AgentAuthCallback.on_auth_state 里维护一个 authed 标志,enter 前 double check;或在 on_enter_ack 收到 code == 1000 后触发重连
多机器人同时遥操每个 agent_id 建一个 TeleopRequest;SDK 按 teleop_id 索引,互不冲突