LinkSoul Agent SDK (Python v1.5.0-SNAPSHOT)

← Python hub ｜ → 中文

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

A third interaction path on top of passive / active — a remote operator drives the robot via TeleopRequest.enter → start_audio(param) → append_audio_delta* → done_audio → exit.

• New class: TeleopRequest (enter / start_audio(param=None) / append_audio_delta / done_audio / exit)
• New callback bases: TeleopEnterCallback.on_enter_ack / TeleopExitCallback.on_exit_ack
• New AgentSdk methods: register_teleop(...) / unregister_teleop(teleop_id)
• New policy: AgentPolicy.TELEOP (wire value "teleop")
• Seven new event types under AGENTSDK_TELEOP_*; new ID prefix teleop_...
• start_audio(param) accepts role (man / woman), threshold (-14 – 14) for voice / VAD tuning

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.

A new interaction path for querying the robot's available skill list and remotely invoking a specific skill (three-phase acknowledgement: ack → state → result):

• New class: ExtSkillRequest (query / invoke)
• New callback bases: ExtSkillQueryCallback.on_query_result / ExtSkillInvokeCallback (on_invoke_ack + on_invoke_result)
• New AgentSdk methods: register_ext_skill(...) / unregister_ext_skill(request_id)
• New policy: AgentPolicy.EXT_SKILL (wire value "extskill")
• Five new event types under AGENTSDK_EXT_SKILL_*; new ID prefix extskill_...

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

⚠️ 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 app_key alongside app_id / app_secret)
• Factory: AgentSdk.create(url, app_id, app_secret) → AgentSdk.create(url, app_id, app_key, app_secret)
• Gateway URL: wss://agentsdk.agibot.com/v1/agentsdk → wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
• callback_types 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

from linksoul_agentsdk import AgentSdk

agent_sdk = AgentSdk.create(
    url="wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk",
    app_id=app_id,
    app_key="<your appKey>",
    app_secret=app_secret,
)

Quick navigation

Three interaction modes

LinkskyGateway is the LinkSoul open-platform ingress gateway (wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk); it 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       │
│                                                              │
└──────────────────────────────────────────────────────────────┘

• Passive: robot initiates (audio/video/text) → SDK processes → returns ASR/LLM/VLM/TTS
• Active: 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 audio (start_audio → append_audio_delta → done_audio), 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 the robot's available skill list (query) and invokes a specific skill (invoke); invoke uses three-phase acknowledgement (ack → state → result); policy: AgentPolicy.EXT_SKILL

Distribution downloads

Direct downloads for offline / air-gapped integration:

# install the wheel
pip install ./linksoul_agentsdk-1.5.0a1-py3-none-any.whl

# or install from sdist
pip install ./linksoul_agentsdk-1.5.0a1.tar.gz

websocket-client>=1.7.0 is pulled in automatically (declared in the wheel METADATA). The 1.5.0a1 version string is the PEP 440 alpha pre-release identifier and is aligned with the Java SDK's 1.5.0-SNAPSHOT. See Quick Start for the detailed install flow.