LinkSoul Agent SDK (Java)

🆕 v1.5.0 new capability: beyond-line-of-sight Teleop

⚠️ Not yet released: in-development v1.5.0-SNAPSHOT capability; interface and protocol may change. Do not use in production before the official release.

v1.5.0 adds a third interaction path on top of passive / active — remote-operator teleop. A remote operator drives the robot via TeleopRequest.enter → startAudio(AgentParam) → appendAudioDelta* → doneAudio → exit; enter / exit are ack'd through TeleopEnterCallback / TeleopExitCallback, audio.* messages are fire-and-forget.

• New request class: TeleopRequest (enter / startAudio(AgentParam) / appendAudioDelta / doneAudio / exit)
• New callback bases: TeleopEnterCallback.onEnterAck / TeleopExitCallback.onExitAck
• New AgentSdk methods: registerTeleop(TeleopRequest) / unregisterTeleop(String)
• New policy enum: AgentPolicy.TELEOP (wire value "teleop")
• Seven new event types under AGENTSDK_TELEOP_*
• New ID prefix teleop_... via IdGenerator.generateTeleopId()
• startAudio(AgentParam) can carry teleop voice / VAD parameters such as role (man / woman) and threshold (-14 ~ 14)

See the Teleop guide, Teleop API, and Teleop example.

🆕 v1.5.0 new capability: ExtSkill (extended skills)

⚠️ Not yet released: in-development v1.5.0-SNAPSHOT capability; interface and protocol may change. Do not use in production before the official release.

v1.5.0 also introduces ExtSkill — query a robot's available extended-skill catalogue and invoke skills remotely. Invocations return results asynchronously via a three-phase receipt (invoke_ack → report_state → invoke_result).

• New request class: ExtSkillRequest (query / invoke)
• New callback bases: ExtSkillQueryCallback (onQueryResult) / ExtSkillInvokeCallback (onInvokeAck + onInvokeResult)
• New AgentSdk methods: registerExtSkill(ExtSkillRequest) / unregisterExtSkill(String requestId)
• New policy enum: AgentPolicy.EXT_SKILL (wire value "extskill")
• Five new event types: agentsdk.ext_skill.query / agentsdk.ext_skill.query_result / agentsdk.ext_skill.invoke / agentsdk.ext_skill.invoke_ack / agentsdk.ext_skill.invoke_result
• New ID prefix extskill_... via IdGenerator.generateExtSkillRequestId()

See the ExtSkill guide, ExtSkill API, and ExtSkill example.

🆕 New in v1.5.0: Function Call exposure & Arbiter

⚠️ Not yet released: in-development v1.5.0-SNAPSHOT capability; interface and protocol may change. Do not use in production before the official release.

v1.5.0 opens up Function Call dispatch and Arbiter arbitration on the passive interaction path: the gateway forwards a pending function call to the SDK (onFunctionCall, on all 8 passive callback classes), and the application makes an arbitration decision returned via response.onArbiter(...), deciding whether the function call is handled by the agent's default pipeline (DELEGATE) or taken over by the application (OVERRIDE).

• New callback method: onFunctionCall(agentId, eventId, FunctionCallInfo, response) on each passive callback class
• New response method: onArbiter(eventId, decision, arbParam) on each Response
• New entity: FunctionCallInfo; new enum: ArbiterDecision (DELEGATE / OVERRIDE)
• New events: agentsdk.function_call.expose / agentsdk.function_call.arbiter

See the Passive Callbacks Guide · Function Call exposure & Arbiter.

⚠️ 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. v1.5.0 inherits the same signing scheme, so v1.3.0 (and earlier) clients still 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

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

Quick Navigation

Four 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.

┌──────────────────────────────────────────────────────────────┐
│                    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                    │
│                                                              │
│  Operator audio ──→ LinkskyGateway ──→ Robot                 │  Teleop (new in v1.5.0)
│  Operator ←──enter/exit ack── LinkskyGateway ←── Robot       │
│                                                              │
│  SDK query/invoke ──→ LinkskyGateway ──→ Robot               │  ExtSkill (new in v1.5.0)
│  SDK ←── ack + 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
• Teleop (new in v1.5.0): A remote operator opens a session (enter), streams PCM/Opus audio chunks (startAudio → appendAudioDelta → doneAudio), then closes with exit. enter / exit are ack'd via callback; audio events are fire-and-forget.
• ExtSkill (new in v1.5.0): The SDK queries a robot's available extended-skill catalogue (query) and triggers execution (invoke). Invoke uses a three-phase receipt (invoke_ack confirms acceptance → report_state reports progress → invoke_result returns execution outcome). Routed via AgentPolicy.EXT_SKILL.

Distribution downloads

Direct downloads for offline / air-gapped integration:

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

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

<!-- pom.xml -->
<dependency>
    <groupId>com.agibot.aiem</groupId>
    <artifactId>linksoul-agentsdk</artifactId>
    <version>1.5.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.