LinkSoul 智能体二开 SDK (Python v1.5.0-SNAPSHOT)

← Python 总入口 ｜ → English

🆕 v1.5.0 新增：超视距遥操（Teleop）

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

v1.5.0 在既有的被动交互 / 主动交互两条路径之外，新增第三条交互路径 —— 超视距遥操（远端操作员在线接管机器人交互）：

• 新增请求类：TeleopRequest（enter / start_audio(param=None) / append_audio_delta / done_audio / exit）
• 新增回调基类：TeleopEnterCallback / TeleopExitCallback（on_enter_ack / on_exit_ack）
• 新增注册接口：AgentSdk.register_teleop(TeleopRequest) / unregister_teleop(teleop_id)
• 新增策略：AgentPolicy.TELEOP（wire 值 "teleop"）
• 新增事件类型 7 个：agentsdk.teleop.enter / agentsdk.teleop.enter_ack / agentsdk.teleop_audio.start|delta|done / agentsdk.teleop.exit / agentsdk.teleop.exit_ack
• 新增 ID 前缀 teleop_...：IdGenerator.generate_teleop_id()
• start_audio(param) 可携带 role（man / woman）、threshold（-14 ~ 14）等音色 / VAD 参数

详见 超视距遥操指南、Teleop API 参考、Teleop 示例。

🆕 v1.5.0 新增：扩展技能（ExtSkill）

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

v1.5.0 同时新增扩展技能交互路径 —— 通过 SDK 查询机器人可用技能清单，并远程触发指定技能执行（三段回执：ack + state + result）：

• 新增请求类：ExtSkillRequest（query / invoke）
• 新增回调基类：ExtSkillQueryCallback（on_query_result）/ ExtSkillInvokeCallback（on_invoke_ack + on_invoke_result）
• 新增注册接口：AgentSdk.register_ext_skill(ExtSkillRequest) / unregister_ext_skill(request_id)
• 新增策略：AgentPolicy.EXT_SKILL（wire 值 "extskill"）
• 新增事件类型 5 个：agentsdk.ext_skill.query / agentsdk.ext_skill.query_result / agentsdk.ext_skill.invoke / agentsdk.ext_skill.invoke_ack / agentsdk.ext_skill.invoke_result
• 新增 ID 前缀 extskill_...：IdGenerator.generate_ext_skill_request_id()

详见 扩展技能指南、ExtSkill API 参考、ExtSkill 示例。

⚠️ v1.4.0 验签方式标准化（不兼容 v1.3.0 及更早版本）

v1.4.0 已遵循灵心开放平台规范，对 SDK 的鉴权（验签）方式做了标准化改造，与 v1.3.0 及更早版本不兼容（v1.5.0 沿用同一套鉴权体系）：

• 鉴权机制：JWT（AGIBOT_AUTHORIZATION 请求头）→ HMAC-SHA256 五元组请求头 （X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature）
• 凭证来源：灵心平台「二开智能体模板」→ 灵心开放平台「应用」（多发一个 app_key）
• 创建签名：AgentSdk.create(url, app_id, app_secret) → AgentSdk.create(url, app_id, app_key, app_secret)
• 网关地址：wss://agentsdk.agibot.com/v1/agentsdk → wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
• callback_types 由 JWT payload 字段迁移为独立请求头 X-Callback-Types（JSON 数组字符串）

升级须同时更换凭证、网关、create() 调用与请求头处理逻辑。完整迁移要点见 CHANGELOG。

连接信息

from linksoul_agentsdk import AgentSdk

agent_sdk = AgentSdk.create(
    url="wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk",
    app_id=app_id,
    app_key="<your appKey>",
    app_secret=app_secret,
)

快速导航

三种交互模式

LinkskyGateway 指灵心开放平台的接入网关（即 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk），负责承载 SDK 与机器人之间的双向消息。

┌──────────────────────────────────────────────────────────────┐
│                       灵心平台                                 │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  机器人 ──音频/视频/文本──→ LinkskyGateway ──→ SDK回调        │  被动交互
│  机器人 ←──ASR/LLM/TTS──── LinkskyGateway ←── SDK响应         │
│                                                              │
│  SDK主动请求 ──→ LinkskyGateway ──→ 机器人                    │  主动交互
│  SDK接收结果 ←── LinkskyGateway ←── 机器人                    │
│                                                              │
│  操作员音频 ──→ LinkskyGateway ──→ 机器人执行                  │  超视距遥操（v1.5.0 新增）
│  操作员 ←──enter/exit ack── LinkskyGateway ←── 机器人         │
│                                                              │
└──────────────────────────────────────────────────────────────┘

• 被动交互：机器人发起（音频/视频/文本） → SDK 处理 → 返回结果（ASR/LLM/VLM/TTS）
• 主动交互：SDK 主动发起 → v1.3.0 起在接口层面开放（一并暴露过技能查询 / 状态查询 / 拉流 / 推流监听等，实际未启用），v1.4.0 把这些未启用接口从公开 API 移除，公开入口收敛到 任务流（唯一真正可用的主动交互）
• 超视距遥操（v1.5.0 新增）：远端操作员通过 SDK 建立遥操会话（enter），持续下发音频块（start_audio → append_audio_delta → done_audio），最终 exit 结束；enter / exit 由回调收 ACK，音频事件为 fire-and-forget
• 扩展技能（v1.5.0 新增）：SDK 通过 query 拉取机器人可用技能清单，通过 invoke 触发指定技能执行；invoke 为三段回执（ack → state → result）；策略标识 AgentPolicy.EXT_SKILL

开发包下载

供开发者直接下载（离线接入场景）：

# wheel 安装
pip install ./linksoul_agentsdk-1.5.0a1-py3-none-any.whl

# 或源码包
pip install ./linksoul_agentsdk-1.5.0a1.tar.gz

依赖 websocket-client>=1.7.0 会随安装自动拉取（已写入 wheel 的 METADATA）。版本号 1.5.0a1 是 PEP 440 alpha 预发布标识，与 Java SDK 的 1.5.0-SNAPSHOT 对齐。详细安装步骤参见 快速开始。