Quick Start

← Home

Requirements

Dependency	Version
Python	3.9+
pip	23+ (or uv / poetry / ...)
websocket-client	≥ 1.7.0 (auto-installed)

Install

pip (recommended)

bash

pip install linksoul-agentsdk
# or install from source:
git clone <repo> && cd linksoul-agentsdk/agentsdk_for_python
pip install -e .

Poetry / PDM

toml

# pyproject.toml
[project]
dependencies = [
    "linksoul-agentsdk>=1.4.0a0",
]

Note: keep app_key and app_secret private — they are used for HMAC-SHA256 gateway signing. Never check them into source code or logs.

The walkthrough below uses the classic Asr2Llm mode (text in → LLM text out). Other passive callbacks integrate the same way — only the register_* call and the on_request signature change (see Passive Examples).

python

import logging

from linksoul_agentsdk import (
    AgentAuthCallback,
    AgentParam,
    AgentSdk,
    IdGenerator,
)
from linksoul_agentsdk.passive import Asr2LlmCallback, Asr2LlmResponse


# Auth callback
class MyAuth(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        if code == 0:
            print(f"Connection authenticated: {app_id}")
        else:
            print(f"Authentication failed: code={code}, msg={msg}")


# Business callback: Asr2Llm (robot already did ASR; SDK runs 语义理解/LLM only)
class MyCallback(Asr2LlmCallback):
    def on_request(
        self,
        agent_id: str,
        event_id: str,
        text: str,
        param: AgentParam,
        response: Asr2LlmResponse,
    ) -> None:
        # 1) Rejected intent → stay silent
        if not text:
            return

        item_id = IdGenerator.generate_item_id()

        # 2) Valid intent must barge in first, then fill in skill / LLM
        response.on_interrupt(event_id, "chat", None)

        # 3) Skill dispatch (optional)
        if "forward" in text.lower():
            skill_param = (
                AgentParam.create()
                .set_string("movement", "move_forward")
                .set_integer("meter", 10)
            )
            response.on_skill(event_id, item_id, "movement", "move_forward", skill_param)

        # 4) LLM streaming reply
        response.on_llm_item_delta(event_id, item_id, "Sure, on it.")
        response.on_llm_item_done(event_id, item_id)
        response.on_llm_done(event_id)


def main() -> None:
    logging.basicConfig(level=logging.INFO)

    # 1) Create the SDK instance (singleton per app_id)
    sdk = AgentSdk.create(
        url="wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk",
        app_id="<your appId>",
        app_key="<your appKey>",
        app_secret="<your appSecret>",
    )

    # 2) Register the auth callback
    sdk.register_auth(MyAuth())

    # 3) Register a passive callback (pick one matching your scenario)
    sdk.register_asr2_llm(MyCallback(sdk))

    # 4) Initialize — opens the WebSocket with auto-reconnect
    sdk.initialize()


if __name__ == "__main__":
    main()

Core concepts cheat-sheet

Concept	Description
`app_id` / `app_key` / `app_secret`	Obtained from the LinkSoul open platform after creating an application; `app_key` + `app_secret` are used for HMAC-SHA256 gateway signing
Passive	Robot initiates → SDK handles → returns result via Response
Active	SDK initiates a task flow (`register_task_flow`)
`agent_id`	The agent ID configured on the LinkSoul platform (e.g. `AGENT_0000001`). The robot binds to that agent on-device; once it comes online the SDK delivers it via `on_robot_online(agent_id, ...)`. It is not a hardware/instance identifier
`event_id`	Unique id for one conversation turn
`item_id`	Identifies intents / response chunks inside a turn
`flag`	Lifecycle flag used by `Audio2` / `AudioVideo2` / `AsrVideo2*` callbacks
`AgentParam`	Key-value container with chained setters
`AgentMeta`	Robot metadata (wakeup, city, name, etc.)

Integration flow

text

AgentSdk.create() → register_auth() → register_*_callback() → initialize()
                                                                      │
                                                                      ▼
                                                              WebSocket connection
                                                                      │
                                                          ┌───────────┴───────────┐
                                                          ▼                       ▼
                                                    on_auth_state()         on_robot_online()
                                                                                  │
                                                                                  ▼
                                                                            on_request()
                                                                                  │
                                                                                  ▼
                                                                        response.on_*()

Next steps

Architecture — threading model & internals
Passive Callbacks Guide — all 8 callback types
Active Operations Guide — task flow (v1.3.0 opened the active surface but only task flow was functional; v1.4.0 removes the never-enabled entries and narrows the public API to this one)
Task-flow payload protocol — action_group / action_type reference
Semantic Skills — full skill catalogue
Examples — runnable code per scenario