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

版本变更记录 (CHANGELOG)

版本变更记录 (CHANGELOG)

v1.5.0-SNAPSHOT (当前开发版本)

⚠️ 本版本为开发中(SNAPSHOT)版本，下列 v1.5.0 新增能力（超视距遥操 / 扩展技能）尚未正式上线，接口可能调整。

发布日期: 开发中

🆕 新增能力：超视距遥操（Teleop）

v1.5.0 在既有的被动交互 / 主动交互两条路径之外，正式对外开放第三条交互路径 —— 超视距遥操：远端操作员通过 SDK 建立会话，向指定 agent_id 的机器人推送人工语音接管指令。

  • 新增类：
    • linksoul_agentsdk.TeleopRequest —— 会话请求实体，方法：enter / start_audio(param) / append_audio_delta / done_audio / keepalive / exit
    • linksoul_agentsdk.TeleopEnterCallback —— on_enter_ack(teleop_id, event_id, code, msg)
    • linksoul_agentsdk.TeleopKeepaliveCallback —— on_keepalive_ack(teleop_id, event_id, code, msg)；机器人在线探活，遥操期间建议每 10 秒定时调用一次，code != 0 视为机器人离线
    • linksoul_agentsdk.TeleopExitCallback —— on_exit_ack(teleop_id, event_id, code, msg)
    • linksoul_agentsdk.mgr.AgentSdkTeleopMgr —— 全局 request 索引，7200s 无活动自动清理
  • 新增 AgentSdk 公开方法：
    • register_teleop(TeleopRequest)
    • unregister_teleop(teleop_id: str)
  • 新增策略枚举：AgentPolicy.TELEOP（wire 值 "teleop"）
  • 新增事件类型 9 个：
    • agentsdk.teleop.enter / agentsdk.teleop.enter_ack
    • agentsdk.teleop_audio.start / agentsdk.teleop_audio.delta / agentsdk.teleop_audio.done
    • agentsdk.teleop.keepalive / agentsdk.teleop.keepalive_ack
    • agentsdk.teleop.exit / agentsdk.teleop.exit_ack
  • 新增 ID 生成器：IdGenerator.generate_teleop_id()（前缀 teleop_）
  • 新增文档：超视距遥操指南、Teleop API、Teleop 示例

🆕 新增能力：扩展技能（ExtSkill）

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

  • 新增类：
    • linksoul_agentsdk.ExtSkillRequest —— 技能请求实体，方法：query / invoke
    • linksoul_agentsdk.ExtSkillQueryCallback —— on_query_result(request_id, event_id, code, msg, skills)
    • linksoul_agentsdk.ExtSkillInvokeCallback —— on_invoke_ack(request_id, event_id, code, msg) + on_state(agent_id, request_id, event_id, state_name, state_value) + on_invoke_result(request_id, event_id, code, msg, result)
  • 新增 AgentSdk 公开方法：
    • register_ext_skill(ExtSkillRequest)
    • unregister_ext_skill(request_id: str)
  • 新增策略枚举：AgentPolicy.EXT_SKILL（wire 值 "extskill"）
  • 新增事件类型 6 个：
    • agentsdk.ext_skill.query / agentsdk.ext_skill.query_result
    • agentsdk.ext_skill.invoke / agentsdk.ext_skill.invoke_ack / agentsdk.ext_skill.report_state / agentsdk.ext_skill.invoke_result
  • 新增 ID 生成器：IdGenerator.generate_ext_skill_request_id()（前缀 extskill_）
  • 新增文档：扩展技能指南、ExtSkill API、ExtSkill 示例

⚠️ 破坏性变更：灵心平台「技能调用方式 = Agent 调用」下线（依赖者须升级 v1.5.0）

v1.5.0 引入 Function Call + Arbiter 仲裁器 后，灵心平台二开智能体配置中的「技能调用方式」为 Agent 调用 的转发机制已下线：

  • 旧机制（≤ v1.4.0）：二开智能体配置里「技能调用方式」选择 Agent 调用 后，技能被触发时平台会把技能请求转发给二开应用（SDK）自行处理。
  • 新机制（v1.5.0）：平台不再自动转发技能，而是把待处理的技能请求以 function call 形式透传给 SDK（on_function_call），由二开应用通过 仲裁器接口（response.on_arbiter(...)）显式决定委托策略：ArbiterDecision.DELEGATE（委托智元交互云默认链路处理）或 ArbiterDecision.OVERRIDE（二开应用接管覆盖）。

若你的智能体依赖了「技能调用方式 = Agent 调用」的转发能力，必须升级到 v1.5.0 并基于 Function Call + Arbiter 重写技能委托 / 分流逻辑，否则技能将无法被正确处理。

调用契约

text
register_teleop → enter → (start_audio(param) → append_audio_delta* → done_audio)+ → exit → unregister_teleop

遥操存续期间可任意频次调用 keepalive（推荐每 10 秒一次）；任何一次 on_keepalive_ack 收到 code != 0 都应视为机器人离线，立即 exit + unregister_teleop 释放资源。

  • enter / keepalive / exit 由 SDK 侧回调收 ACK；code == 0 成功，code == 1000 表示 SDK 本地连接已 closed，code == -1 服务端拒绝；
  • start_audio / append_audio_delta / done_audio 是 fire-and-forget（无 ACK）；
  • start_audio(param) 支持在每段音频开始时传递 role（"male" / "female"）、threshold（-14 ~ 14）等音色 / VAD 参数；
  • timeout 参数当前仅做占位（clamp 到 ≥50ms），暂未真正驱动超时回调，后续版本会补齐。

🆕 新增能力：Function Call 分发与 Arbiter 仲裁

v1.5.0 在被动交互链路上开放 Function Call 分发与 Arbiter 仲裁（尚未上线，开发中特性）。

  • 新增回调（8 种被动回调类均有）：on_function_call(agent_id, event_id, function_call, response) —— 网关透传待处理的 function call
  • 新增响应方法（8 种 Response 类均有）：on_arbiter(event_id, decision, arb_param) —— 回传仲裁决策，下发 agentsdk.function_call.arbiter
  • 新增数据类：linksoul_agentsdk.FunctionCallInfo（source / policy / type / value / param）
  • 新增枚举：linksoul_agentsdk.ArbiterDecision（DELEGATE / OVERRIDE / ILLEGAL）
  • 新增事件类型 2 个：agentsdk.function_call.expose / agentsdk.function_call.arbiter

🆕 新增能力：对话历史透传（onHistories）

  • 新增基类共享回调：on_histories(agent_id, event_id, histories)（PassiveCallback 默认日志实现，按需重载）
  • 新增数据类：linksoul_agentsdk.HistoryInfo（timestamp / query / answer / complete / event_id / skill）
  • 新增事件类型 1 个：agentsdk.histories.expose（网关 → SDK）

兼容性

  • 接口层面完全向后兼容 v1.4.0：现有 register_auth / 被动回调 / 任务流接口均无变更；升级方式为 pip 包版本从 1.4.0 → 1.5.0。
  • 若未使用 Teleop / Function Call，运行时行为与 v1.4.0 一致。
  • 但有一处破坏性变更：依赖灵心平台「技能调用方式 = Agent 调用」转发的智能体，须按上文「破坏性变更」章节改造为 Function Call + Arbiter。

依赖

同 v1.4.0（未升级第三方依赖）。

v1.4.0 (alpha)

发布日期: 开发中

⚠️ 破坏性变更 — 验签方式标准化（不兼容 v1.3.0 及更早版本）

v1.4.0 已遵循灵心开放平台规范，对 AgentSDK 的鉴权（验签）方式做了标准化改造。Python SDK 与 Java SDK 同步升级，v1.3.0 及更早版本无法直接平滑升级：

项目v1.3.0 及更早v1.4.0
网关 URLwss://agentsdk.agibot.com/v1/agentsdkwss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
凭证来源灵心平台「二开智能体模板」灵心开放平台「应用」（多发一个 app_key）
工厂方法AgentSdk.create(url, app_id, app_secret)AgentSdk.create(url, app_id, app_key, app_secret)
鉴权算法JWT（HS256 签名 + AGIBOT_AUTHORIZATION 请求头）HMAC-SHA256("GET\n{path}\n{timestamp}\n{nonce}")，签名经五个请求头下发
鉴权请求头1 个：AGIBOT_AUTHORIZATION5 个：X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature
callback_types 传递方式JWT payload 字段独立请求头 X-Callback-Types（JSON 数组字符串）
实现影响LinkskyClient 依赖 jwt_util.pyLinkskyClient 改用 hmac + hashlib；AgentSdk 不再对外暴露 app_secret

升级步骤：

  1. 在灵心开放平台「应用」页面重新申领 app_id / app_key / app_secret（旧凭证不可继续使用）。
  2. 将 WebSocket 网关 URL 切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk。
  3. 调用方升级 AgentSdk.create(url, app_id, app_secret) → AgentSdk.create(url, app_id, app_key, app_secret)。
  4. 若有自定义代理 / 网关在转发 SDK 请求，须解析并透传新的 5 个鉴权头 + X-Callback-Types，并停用旧 AGIBOT_AUTHORIZATION。
  5. 确认调用方未再读取 AgentSdk.app_secret（属性已下线）。

与 Java SDK v1.4.0 等价，参考 Java CHANGELOG 获取完整变更点。 本节仅列出 Python 端的差异点。

Python 端实现特性

  • 包名：linksoul_agentsdk（PEP 8 蛇形命名），与 Java 包路径 com.agibot.aiem.sdk.* 一一对应
  • 公开模块：linksoul_agentsdk.passive / linksoul_agentsdk.active / linksoul_agentsdk.client / linksoul_agentsdk.mgr
  • WebSocket 客户端：基于 websocket-client>=1.7，同步阻塞模式，在独立 daemon 线程跑 run_forever
  • 心跳：由 websocket-client 内置（ping_interval=10s, ping_timeout=5s）
  • 重连：连接断开自动通过 threading.Timer 延迟 3 秒重连
  • 线程模型：AgentThreadMgr 用一组单线程 ThreadPoolExecutor，每个 agent_id 绑定一个串行 worker（与 Java AgentThreadMgr 等价）
  • 鉴权：基于 hmac + hashlib（HMAC-SHA256），与 Java LinkskyClient.hmacSha256 对齐，签名字段经 X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature 五个请求头下发；回调类型集合经 X-Callback-Types 请求头下发

公开 API 命名映射

Java SDK 的 camelCase 全部转为 Python 的 snake_case，并加上类型注解：

JavaPython
AgentSdk.create(url, appId, appKey, appSecret)AgentSdk.create(url, app_id, app_key, app_secret)
registerAuth(AgentAuthCallback)register_auth(AgentAuthCallback)
registerAsr2Llm(Asr2LlmCallback)register_asr2_llm(Asr2LlmCallback)
onRequest(agentId, eventId, ...)on_request(agent_id, event_id, ...)
response.onLlmItemDelta(...)response.on_llm_item_delta(...)
response.onInterrupt(...)response.on_interrupt(...)
response.onSkill(...)response.on_skill(...)
IdGenerator.generateEventId()IdGenerator.generate_event_id()
AgentParam.create().setString(k, v)AgentParam.create().set_string(k, v)

依赖

依赖版本
Python3.9+
websocket-client≥ 1.7.0

测试

  • 73+ 单元测试，基于 pytest + mock LinkskyClient，CI 无需真实 WebSocket 服务器
  • pip install -e ".[dev]" && pytest 即可一键运行

历史版本

Java/Python 始终保持版本号对齐——历史版本（v1.0.0 / v1.1.0 / v1.3.0）的协议层变更详见 Java SDK v1.4.0 CHANGELOG。