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

版本变更记录 (CHANGELOG)

版本变更记录 (CHANGELOG)

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

发布日期: 开发中

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

v1.4.0 已遵循灵心开放平台规范，对 AgentSDK 的鉴权（验签）方式做了标准化改造。该改动同时影响网关、凭证、AgentSdk.create() 签名与协议头，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
凭证来源灵心平台「二开智能体模板」灵心开放平台「应用」（多发一个 appKey）
工厂方法AgentSdk.create(url, appId, appSecret)AgentSdk.create(url, appId, appKey, appSecret)
鉴权算法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
callbackTypes 传递方式JWT payload 字段独立请求头 X-Callback-Types（JSON 数组字符串）
内部模块影响LinkskyClient 依赖 JwtUtilLinkskyClient 移除 JwtUtil，内置 hmacSha256()；AgentSdk 不再暴露 appSecret 的 Getter

升级步骤：

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

新增

  • 主动打招呼三合一：被动回调基类 PassiveCallback 新增 onGreetSignal(agentId, eventId, param, GreetResponse)， 通过 GreetResponse.onGreetVlmDelta/Done（VLM 流式文本）与 onGreetTtsDelta/Done （TTS 音频字节的 base64 字符串流）两路输出打招呼内容
  • 新增协议事件 agentsdk.greet_response.tts.delta / agentsdk.greet_response.tts.done （配合既有的 agentsdk.greet_response.vlm.delta/done）
  • UID（人脸 / 声纹）开放：被动回调基类新增 onFaceInfo(agentId, eventId, param) 和 onVideoFrame(agentId, eventId, flag, buf, isKeyFrame, localTs, param)
  • 状态推送统一并入被动回调：PassiveCallback.onState(agentId, eventId, stateName, stateValue)
  • 新增协议事件 agentsdk.state_request.meta（机器人状态推送）

变更

  • 打招呼能力收敛：删除独立的 Greet2VlmCallback、Greet2VlmResponse， 打招呼信令统一通过 PassiveCallback.onGreetSignal 接收，VLM/TTS 两路应答合并到 GreetResponse； 并且不再使用独立的 AgentCallbackType，由任意已注册的被动回调接收
  • 状态监听能力收敛：删除独立的 StateListenCallback 和 AgentSdk.registerStateListen(...)， 状态变化推送改由所有 PassiveCallback 子类共享的 onState(...) 接收
  • 修复 GreetResponse.onGreetTtsDelta/Done 误用 VLM 事件类型的 Bug

移除

  • Greet2VlmCallback / Greet2VlmResponse / StateListenCallback（合并到 PassiveCallback 基类）
  • AgentSdk.registerStateListen(...)（功能合并到被动回调注册流程）
  • 删除以下被动回调类（含对应 Response）： Audio2Asr / Audio2Audio / AudioVideo2Audio / Text2Tts
  • 删除以下 AgentSdk 公开方法（底层 Callback/Request 类暂保留）：
    • 被动回调注册：registerPushListen
    • 主动接口：querySkill、queryState、registerPullStream / unregisterPullStream
  • AgentCallbackType 枚举同步删除 AUDIO_2_ASR、AUDIO_2_AUDIO、AUDIO_VIDEO_2_AUDIO、TEXT_2_TTS、STATE_LISTEN、GEET_2_VLM、GEET_2_TTS（PUSH_LISTEN 仍保留但未对外开放）
  • 公开被动回调收敛为 8 种：Audio2Llm / Audio2Tts / Asr2Llm / Asr2Tts / AsrVideo2Vlm / AsrVideo2Tts / AudioVideo2Vlm / AudioVideo2Tts
  • 公开主动接口收敛为 registerTaskFlow / unregisterTaskFlow

v1.3.0

新增

  • 里程碑版本，功能全量开放
  • 主动交互：技能查询 (querySkill) — 查询机器人支持的技能及参数
  • 主动交互：状态查询 (queryState) — 查询机器人当前状态
  • 主动交互：任务流 (TaskFlowRequest) — 编排多步骤任务（startRequest/taskRequest/endRequest/interruptRequest）
  • 主动交互：拉流 (PullStreamRequest) — startRequest/keepaliveRequest/endRequest
  • 主动交互：推流监听 (PushListenCallback) — 接收机器人推送的视频流
  • 主动交互：状态监听 (StateListenCallback) — 实时接收状态变化
  • 被动交互支持技能返回：response.onSkill(eventId, itemId, skillType, skillName, skillParam)
  • 被动交互支持打断接口：response.onInterrupt(eventId, interruptType, interruptTips)
  • AgentParam 支持泛型参数（getObject/setObject、getList/setList）
  • 被动交互回调增加 AgentParam param 扩展参数
  • 协议新增 policy 字段标识交互模式
  • 响应中返回 eventId 字段，方便调用方追踪会话
  • FlowStartCallback/FlowTaskCallback 区分 RequestAck 与 ExecuteAck 两阶段确认
  • 接口超时自动清理机制
  • AgentThreadPool 线程池管理（per-agent 线程绑定，保证消息顺序）
  • AgentDelayedPool 延迟任务框架（心跳超时检测）
  • 主动交互示例程序
  • 打断及技能返回示例程序

变更

  • 网关地址变更 (2026-06-25)：WebSocket 地址从 wss://agentsdk.agibot.com/v1/agentsdk 切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk；凭证来源也从"灵心平台二开智能体模版"调整为灵心开放平台创建的应用（appId / appKey / appSecret 一并由应用页面获取）
  • 认证方式升级 (2026-06-24)：AgentSdk.create() 新增 appKey 参数，签名从 JWT 改为 HMAC-SHA256 网关鉴权
    • 旧签名：AgentSdk.create(url, appId, appSecret) — 生成 JWT token 并写入 AGIBOT_AUTHORIZATION 请求头
    • 新签名：AgentSdk.create(url, appId, appKey, appSecret) — 通过 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature 五个请求头完成鉴权，签名算法为 HMAC-SHA256("GET\n{path}\n{timestamp}\n{nonce}")
    • LinkskyClient 移除对 JwtUtil 的依赖，内置 hmacSha256 工具方法
    • AgentSdk 移除 appSecret 字段的 Getter，认证参数由 LinkskyClient 内部持有
    • callbackTypes 从 JWT payload 字段迁移为独立请求头 X-Callback-Types（JSON 数组字符串）
  • timeout 参数类型从 int 升级为 long，支持更大超时范围
  • 所有 onRequest 回调方法签名新增 AgentParam param 参数
  • 日志输出优化，减少冗余日志

v1.1.0

新增

  • 多模态被动回调: AsrVideo2Vlm、AsrVideo2Tts、AudioVideo2Vlm、AudioVideo2Tts、AudioVideo2Audio
  • AgentMeta 封装替代原始 JSONObject
  • 视频流透传支持（H264 + Image）
  • 图片帧大小限制

变更

  • 重构项目结构，独立迁移为独立仓库
  • 配置化自定义智能体的 appId 及 appSecret

v1.0.0

发布日期: 2025-02-27

初始版本

  • SDK 核心框架：AgentSdk 单例工厂模式
  • WebSocket 客户端：LinkskyClient（Netty, 自动重连, JWT认证）
  • 基础被动回调：Audio2Asr、Audio2Llm、Audio2Tts、Asr2Llm、Asr2Tts、Audio2Audio、Text2Tts
  • AgentParam 类型安全参数包装
  • IdGenerator 唯一ID生成
  • JwtUtil JWT签名工具
  • 示例程序

依赖版本

依赖版本
Java17+
Netty4.1.116.Final
fastjson22.0.53
jjwt0.11.5
Lombok1.18.36
commons-lang33.14.0
SLF4J2.0.16
Logback1.5.13