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

LinkSoul 智能体二开 SDK (Java)

LinkSoul 智能体二开 SDK (Java)

⚠️ 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）
  • 凭证来源：灵心平台「二开智能体模板」→ 灵心开放平台「应用」（多发一个 appKey）
  • 创建签名：AgentSdk.create(url, appId, appSecret) → AgentSdk.create(url, appId, appKey, appSecret)
  • 网关地址：wss://agentsdk.agibot.com/v1/agentsdk → wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
  • callbackTypes 由 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 签名密钥）
java
AgentSdk agentSdk = AgentSdk.create("wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk", appId, appKey, appSecret);

快速导航

文档说明
快速开始5分钟上手，Maven引入 + 完整接入代码
架构概述系统架构、线程模型、重连机制
被动交互指南8种被动回调类型详解 + 响应方法
机器人端侧状态参考onState 收到的 22 个 stateName 模块定义、字段表与频率约定
主动交互指南任务流（v1.3.0 即开放主动交互接口；v1.4.0 任务流是真正可用的，其余接口未启用故移除）
任务流 payload 协议编排技能 — action_group / action_type JSON 字段详解 + SIMPLE/COMPLEX 示例
语义技能参考response.onSkill / 任务流可下发的技能全集
错误处理错误码、重连机制、资源释放
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.0-SNAPSHOT.jar二进制 jar（Java 17+）133 KB

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

bash
mvn install:install-file \
    -Dfile=linksoul-agentsdk-1.4.0-SNAPSHOT.jar \
    -DgroupId=com.agibot.aiem \
    -DartifactId=linksoul-agentsdk \
    -Dversion=1.4.0-SNAPSHOT \
    -Dpackaging=jar
xml
<!-- pom.xml -->
<dependency>
    <groupId>com.agibot.aiem</groupId>
    <artifactId>linksoul-agentsdk</artifactId>
    <version>1.4.0-SNAPSHOT</version>
</dependency>

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