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

LinkSoul Agent SDK (Java)

LinkSoul Agent SDK (Java)

⚠️ v1.4.0 breaking auth change — NOT compatible with v1.3.0 or earlier

v1.4.0 standardises the AgentSDK signing scheme to align with the LinkSoul open-platform spec. Existing v1.3.0 (and earlier) clients cannot upgrade in place:

  • Auth: JWT (one AGIBOT_AUTHORIZATION header) → HMAC-SHA256 with five signed headers (X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature)
  • Credentials: legacy custom-agent template → application on the LinkSoul open platform (issues a new appKey alongside appId / appSecret)
  • Factory: AgentSdk.create(url, appId, appSecret) → AgentSdk.create(url, appId, appKey, appSecret)
  • Gateway URL: wss://agentsdk.agibot.com/v1/agentsdk → wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
  • callbackTypes moves out of the JWT payload into a standalone X-Callback-Types header (JSON array string)

Upgrading requires rotating credentials, switching the gateway URL, updating the create() call, and rewriting any custom auth-header handling. See the CHANGELOG for the full migration path.

Connection Info

ItemValue
WebSocket URLwss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
appIdObtained from the LinkSoul open platform when creating an application
appKeyObtained from the LinkSoul open platform when creating an application
appSecretObtained from the LinkSoul open platform when creating an application (HMAC-SHA256 signing key)
java
AgentSdk agentSdk = AgentSdk.create("wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk", appId, appKey, appSecret);

Quick Navigation

DocumentDescription
Quick Start5-minute setup with Maven + complete integration code
ArchitectureSystem architecture, threading model, reconnection mechanism
Passive Callbacks Guide8 passive callback types explained + response methods
Robot-side state modulesAll 22 stateName modules received in onState, field schemas + frequency conventions
Active Operations GuideTask flow (v1.3.0 first opened the active surface but only task flow was ever functional; v1.4.0 removes the never-enabled entries — skill / state query, pull / push stream — and narrows the public API to task flow)
Task-flow payload protocolSkill orchestration — action_group / action_type JSON reference + SIMPLE/COMPLEX examples
Semantic SkillsFull catalogue of skills that can be dispatched via response.onSkill / task flow
Error HandlingError codes, reconnection mechanism, resource release
AgentSdk APIMain entry class complete API reference
Enums ReferenceAll enum types and values
Passive Callbacks APICallback/Response class method signature reference
Active Requests APITask flow API signatures
Passive ExamplesComplete passive interaction example code
Active ExamplesComplete active interaction example code
Troubleshooting & FAQTroubleshooting manual + FAQ (grows over time)
GlossaryBusiness / SDK / model / reject terminology reference

Two Interaction Modes

LinkskyGateway is the LinkSoul open-platform ingress gateway (wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk), which relays bidirectional messages between the SDK and robots.

text
┌─────────────────────────────────────────────────────────┐
│                   LinkSoul Platform                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Robot ──Audio/Video/Text──→ LinkskyGateway ──→ SDK CB  │  Passive
│  Robot ←──ASR/LLM/TTS────── LinkskyGateway ←── SDK Resp │
│                                                         │
│  SDK Request ──→ LinkskyGateway ──→ Robot               │  Active
│  SDK Result  ←── LinkskyGateway ←── Robot               │
│                                                         │
└─────────────────────────────────────────────────────────┘
  • Passive Interaction: Robot initiates (audio/video/text) -> SDK processes -> Returns result (ASR/LLM/VLM/TTS)
  • Active Interaction: SDK initiates -> v1.3.0 first opened skill / state query, pull / push stream and task flow at the API level, but only task flow was ever functional; v1.4.0 removes those never-enabled entries and narrows the public surface to task flow

Distribution downloads

Direct downloads for offline / air-gapped integration:

FileKindSize
linksoul-agentsdk-1.4.0-SNAPSHOT.jarBinary jar (Java 17+)133 KB

Install it into your local Maven repo first, then resolve via Maven / Gradle normally:

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>

Note: the jar contains only the SDK's own bytecode; third-party dependencies (Netty / fastjson2 / jjwt / SLF4J / Logback / commons-lang3, etc.) must still be resolved through Maven / Gradle. See the full list in Quick Start - Build dependencies.