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

LinkSoul Agent SDK (Python v1.4.0)

LinkSoul Agent SDK (Python v1.4.0)

← Python hub ｜ → 中文

⚠️ 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 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

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)
python
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

DocumentDescription
Quick Start5-minute setup, pip install + full integration code
ArchitectureSystem architecture, threading model, reconnect
Passive Callbacks Guide8 passive callback types + response methods
Robot-side state modulesAll 22 state_name modules received in on_state, 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 dispatched via response.on_skill or task flow
AgentSdk APIMain entry class full reference
Enums ReferenceEvery enum & value
Passive Callbacks APICallback / Response signatures
Active Requests APITask flow API
Passive ExamplesFull passive-flow code
Active ExamplesFull active-flow code
Troubleshooting & FAQTroubleshooting manual + FAQ (grows over time)
GlossaryBusiness / SDK / model / reject terminology reference
ChangelogPer-version changes

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

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: 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

Distribution downloads

Direct downloads for offline / air-gapped integration:

FileKindSize
linksoul_agentsdk-1.4.0a0-py3-none-any.whlwheel (recommended)36 KB
linksoul_agentsdk-1.4.0a0.tar.gzsdist (source distribution)33 KB
bash
# install the wheel
pip install ./linksoul_agentsdk-1.4.0a0-py3-none-any.whl

# or install from sdist
pip install ./linksoul_agentsdk-1.4.0a0.tar.gz

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