Changelog

v1.4.0 (alpha)

Release date: in development

⚠️ Breaking change — auth/signing standardised (NOT compatible with v1.3.0 or earlier)

v1.4.0 standardises the AgentSDK signing scheme to align with the LinkSoul open-platform spec. The Python SDK ships the change together with the Java SDK; v1.3.0 (and earlier) clients cannot upgrade in place:

Item	v1.3.0 and earlier	v1.4.0
Gateway URL	`wss://agentsdk.agibot.com/v1/agentsdk`	`wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk`
Credential source	Legacy custom-agent template	Application on the LinkSoul open platform (adds `app_key`)
Factory	`AgentSdk.create(url, app_id, app_secret)`	`AgentSdk.create(url, app_id, app_key, app_secret)`
Algorithm	JWT (HS256) sent via `AGIBOT_AUTHORIZATION`	HMAC-SHA256(`"GET\n{path}\n{timestamp}\n{nonce}"`), delivered across five signed headers
Auth headers	1 header: `AGIBOT_AUTHORIZATION`	5 headers: `X-App-Id` / `X-App-Key` / `X-Timestamp` / `X-Nonce` / `X-Signature`
`callback_types` transport	JWT payload field	Standalone header `X-Callback-Types` (JSON array string)
Implementation impact	`LinkskyClient` depends on `jwt_util.py`	`LinkskyClient` switches to `hmac` + `hashlib`; `AgentSdk` no longer exposes `app_secret`

Migration checklist:

Re-issue app_id / app_key / app_secret from the open-platform application page; old credentials are not accepted.
Switch the WebSocket gateway URL to wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk.
Replace every AgentSdk.create(url, app_id, app_secret) call with AgentSdk.create(url, app_id, app_key, app_secret).
If you proxy SDK traffic through a custom gateway, parse and propagate the new five-header signature plus X-Callback-Types, and stop relying on AGIBOT_AUTHORIZATION.
Make sure no code still reads AgentSdk.app_secret — the attribute has been removed.

Equivalent to the Java SDK v1.4.0 — refer to the Java CHANGELOG for the complete protocol-level change list. This page only enumerates Python-specific notes.

Python-specific implementation

Package name: linksoul_agentsdk (PEP 8 snake_case), 1-to-1 mapped from the Java packages
Public modules: linksoul_agentsdk.passive / .active / .client / .mgr
WebSocket client: built on websocket-client>=1.7, synchronous blocking, running run_forever in a dedicated daemon thread
Heartbeat: handled by websocket-client (ping_interval=10s, ping_timeout=5s)
Reconnect: automatically scheduled by a threading.Timer 3 s after disconnect
Threading: AgentThreadMgr uses single-thread ThreadPoolExecutor instances, one per agent_id (matching Java AgentThreadMgr)
Auth: built on hmac + hashlib (HMAC-SHA256), matching Java LinkskyClient.hmacSha256. The signature is delivered through five request headers — X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature — and the set of registered callback types travels in X-Callback-Types

Public API naming

Java camelCase is translated to Python snake_case, with full typing annotations:

Java	Python
`AgentSdk.create(url, appId, appKey, appSecret)`	`AgentSdk.create(url, app_id, app_key, app_secret)`
`registerAuth(AgentAuthCallback)`	`register_auth(AgentAuthCallback)`
`registerAsr2Llm(Asr2LlmCallback)`	`register_asr2_llm(Asr2LlmCallback)`
`onRequest(agentId, eventId, ...)`	`on_request(agent_id, event_id, ...)`
`response.onLlmItemDelta(...)`	`response.on_llm_item_delta(...)`
`response.onInterrupt(...)`	`response.on_interrupt(...)`
`response.onSkill(...)`	`response.on_skill(...)`
`IdGenerator.generateEventId()`	`IdGenerator.generate_event_id()`
`AgentParam.create().setString(k, v)`	`AgentParam.create().set_string(k, v)`

Dependencies

Dependency	Version
Python	3.9+
websocket-client	≥ 1.7.0

Tests

73+ unit tests using pytest + a mock LinkskyClient — no real WebSocket server required in CI
Run via pip install -e ".[dev]" && pytest

Historical versions

Java & Python stay version-aligned — see the Java SDK v1.4.0 CHANGELOG for the protocol changes that landed in earlier releases (v1.0.0 / v1.1.0 / v1.3.0).