LinkSoul 智能体二开 SDK (Java)

🚀 快速上手指南（产品向 · 非技术）：https://agirobot.feishu.cn/wiki/ADMwwEO4XiJP6okZxQKczizxnoe 首次接入、想先了解产品能力与流程，从这里开始；本页及子文档为面向开发者的技术参考。

连接信息

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

java

AgentSdk agentSdk = AgentSdk.create("wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk", appId, appKey, appSecret);

快速导航

按能力查阅（指南 / API / 示例）

想接入某条交互路径，横向看这一行即可拿齐它的开发指南、API 参考与可运行示例：

能力	指南	API	示例
被动交互（机器人发起）^①	指南	API	示例
主动交互（任务流）	指南	API	示例
超视距遥操 🆕^②	指南	API	示例
扩展技能 🆕^②	指南	API	示例

^① 被动交互指南 / API 内含 v1.5.0 新增的 Function Call 开放与 Arbiter 仲裁。 ^② 🆕 为 v1.5.0 新增能力，当前为 SNAPSHOT 开发版，尚未正式上线。

入门与参考

分类	文档
上手	快速开始 · 架构概述
核心 API	AgentSdk API · 枚举参考
任务流进阶	任务流 payload 协议 · 语义技能参考
运行时	机器人端侧状态参考 · 错误处理
排障 & 速查	常见问题排除 & QA · 名词解释 · 更新日志

四种交互模式

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 ←── 机器人                    │
│                                                              │
│  操作员音频 ──→ LinkskyGateway ──→ 机器人执行                  │  超视距遥操（v1.5.0 新增）
│  操作员 ←──enter/exit ack── LinkskyGateway ←── 机器人         │
│                                                              │
│  SDK query/invoke ──→ LinkskyGateway ──→ 机器人               │  扩展技能（v1.5.0 新增）
│  SDK ←── ack + result ── LinkskyGateway ←── 机器人            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

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

开发包下载

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

文件	类型	大小
`linksoul-agentsdk-1.5.0-SNAPSHOT.jar`	二进制 jar（Java 17+）	149 KB

安装到本地 Maven 仓库后再走 Maven / Gradle 解析：

bash

mvn install:install-file \
    -Dfile=linksoul-agentsdk-1.5.0-SNAPSHOT.jar \
    -DgroupId=com.agibot.aiem \
    -DartifactId=linksoul-agentsdk \
    -Dversion=1.5.0-SNAPSHOT \
    -Dpackaging=jar

xml

<!-- pom.xml -->
<dependency>
    <groupId>com.agibot.aiem</groupId>
    <artifactId>linksoul-agentsdk</artifactId>
    <version>1.5.0-SNAPSHOT</version>
</dependency>

注意：jar 只包含 SDK 自身字节码，第三方依赖（Netty / fastjson2 / jjwt / SLF4J / Logback / commons-lang3 等）需要由 Maven / Gradle 解析。完整依赖清单见快速开始 - 接入依赖。