AgentSdk API Reference

← Home

Creation

python

from linksoul_agentsdk import AgentSdk

# Create instance (singleton per app_id)
sdk = AgentSdk.create(url, app_id, app_key, app_secret)

# Get an existing instance
sdk = AgentSdk.get(app_id)

# List all registered app_ids
app_ids = AgentSdk.list_app_ids()

Method	Returns	Description
`create(url, app_id, app_key, app_secret)`	`AgentSdk`	Create or fetch
`get(app_id)`	`AgentSdk \| None`	Existing instance
`list_app_ids()`	`list[str]`	All registered app_ids

Lifecycle

python

sdk.initialize()   # open WebSocket
sdk.release()      # close & cleanup

Method	Description
`initialize()`	Open WebSocket (triggers auth + reconnect)
`release()`	Close connection, drop callbacks, stop reconnect

Auth callback

python

from linksoul_agentsdk import AgentAuthCallback


class MyAuth(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        ...   # code == 0 means success


sdk.register_auth(MyAuth())

Passive callback registration

Must be called before initialize(). Each SDK instance may register only one passive type.

Method	Callback type	Scenario
`register_audio2_llm(cb)`	`Audio2LlmCallback`	Audio → ASR + LLM
`register_audio2_tts(cb)`	`Audio2TtsCallback`	Audio → ASR + LLM + TTS
`register_asr2_llm(cb)`	`Asr2LlmCallback`	Text → LLM
`register_asr2_tts(cb)`	`Asr2TtsCallback`	Text → LLM + TTS
`register_asr_video2_vlm(cb)`	`AsrVideo2VlmCallback`	Text + video → VLM
`register_asr_video2_tts(cb)`	`AsrVideo2TtsCallback`	Text + video → VLM + TTS
`register_audio_video2_vlm(cb)`	`AudioVideo2VlmCallback`	Audio + video → VLM
`register_audio_video2_tts(cb)`	`AudioVideo2TtsCallback`	Audio + video → VLM + TTS

v1.4.0 changes:
register_state_listen(...) removed; state pushes arrive via PassiveCallback.on_state(...).
Greeting signal is handled by overriding PassiveCallback.on_greet_signal(...).
Removed from the SDK: passive callbacks Audio2Asr / Audio2Audio / AudioVideo2Audio / Text2Tts (classes deleted); active APIs query_skill / query_state / register_pull_stream / register_push_listen (registration methods deleted).

Active interaction

Task flow

python

from linksoul_agentsdk.active import TaskFlowRequest

sdk.register_task_flow(task_flow_request)
sdk.unregister_task_flow(flow_id)

Full lifecycle: Active Operations Guide - Task Flow.

Helpers

Method	Returns	Description
`get_agent_callback_type(agent_id)`	`AgentCallbackType \| None`	The callback bound to an agent
`get_agent_meta(agent_id)`	`AgentMeta \| None`	The agent's metadata
`get_robot_callback(callback_type)`	`PassiveCallback \| None`	Registered callback instance
`app_id` (property)	`str`	Current `app_id`
`url` (property)	`str`	Connection URL
`released` (property)	`bool`	Whether `release()` has been called
`linksky_client` (property)	`LinkskyClient \| None`	The initialised client instance

Test hook

python

sdk.set_linksky_client_factory(factory)

Allows tests to inject a FakeLinkskyClient. Must be called before initialize(). See the test conventions.