LinkSoul 智能体二开 SDK (Python v1.4.0)

← Python 总入口｜ → English

⚠️ v1.4.0 验签方式标准化（不兼容 v1.3.0 及更早版本）
v1.4.0 已遵循灵心开放平台规范，对 SDK 的鉴权（验签）方式做了标准化改造，与 v1.3.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。

连接信息

项目	值
WebSocket 地址	`wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk`
appId	通过灵心开放平台创建应用获取
appKey	通过灵心开放平台创建应用获取
appSecret	通过灵心开放平台创建应用获取（HMAC-SHA256 签名密钥）

python

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,
)

快速导航

文档	说明
快速开始	5 分钟上手，pip 安装 + 完整接入代码
架构概述	系统架构、线程模型、重连机制
被动交互指南	8 种被动回调类型详解 + 响应方法
机器人端侧状态参考	`on_state` 收到的 22 个 `state_name` 模块定义、字段表与频率约定
主动交互指南	任务流（v1.3.0 即开放主动交互接口；v1.4.0 任务流是真正可用的，其余接口未启用故移除）
任务流 payload 协议	编排技能 — `action_group` / `action_type` JSON 字段详解 + SIMPLE/COMPLEX 示例
语义技能参考	`response.on_skill` / 任务流可下发的技能全集
AgentSdk API	主入口类完整 API 参考
枚举参考	所有枚举类型及取值
被动回调 API	回调/响应类方法签名对照
主动请求 API	任务流 API 签名
被动示例	完整被动交互示例代码
主动示例	完整主动交互示例代码
常见问题排除 & QA	故障排除手册 + FAQ（持续补充）
名词解释	业务/SDK/模型/拒识等术语速查
更新日志	各版本变更记录

两种交互模式

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

text

┌─────────────────────────────────────────────────────────┐
│                     灵心平台                              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  机器人 ──音频/视频/文本──→ LinkskyGateway ──→ SDK回调   │  被动交互
│  机器人 ←──ASR/LLM/TTS──── LinkskyGateway ←── SDK响应    │
│                                                         │
│  SDK主动请求 ──→ LinkskyGateway ──→ 机器人               │  主动交互
│  SDK接收结果 ←── LinkskyGateway ←── 机器人               │
│                                                         │
└─────────────────────────────────────────────────────────┘

被动交互：机器人发起（音频/视频/文本） → SDK 处理 → 返回结果（ASR/LLM/VLM/TTS）
主动交互：SDK 主动发起 → v1.3.0 起在接口层面开放（一并暴露过技能查询 / 状态查询 / 拉流 / 推流监听等，实际未启用），v1.4.0 把这些未启用接口从公开 API 移除，公开入口收敛到 任务流（唯一真正可用的主动交互）

开发包下载

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

文件	类型	大小
`linksoul_agentsdk-1.4.0a0-py3-none-any.whl`	wheel（推荐）	36 KB
`linksoul_agentsdk-1.4.0a0.tar.gz`	sdist（源码包）	33 KB

bash

# wheel 安装
pip install ./linksoul_agentsdk-1.4.0a0-py3-none-any.whl

# 或源码包
pip install ./linksoul_agentsdk-1.4.0a0.tar.gz

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