AgentSdk API 参考

← 返回首页

创建与获取

python

from linksoul_agentsdk import AgentSdk

# 创建实例（单例：同一 app_id 多次调用返回同一实例）
sdk = AgentSdk.create(url, app_id, app_key, app_secret)

# 获取已创建的实例
sdk = AgentSdk.get(app_id)

# 获取所有已注册的 app_id 列表
app_ids = AgentSdk.list_app_ids()

方法	返回值	说明
`create(url, app_id, app_key, app_secret)`	`AgentSdk`	创建或获取实例
`get(app_id)`	`AgentSdk \| None`	获取已创建实例
`list_app_ids()`	`list[str]`	所有已注册 app_id

生命周期

python

sdk.initialize()  # 建立 WebSocket 连接
sdk.release()     # 关闭连接，释放所有资源

方法	说明
`initialize()`	建立 WebSocket 连接（触发鉴权、重连）
`release()`	关闭连接、清理回调、清理缓存、停止重连

鉴权回调

python

from linksoul_agentsdk import AgentAuthCallback


class MyAuth(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        # code == 0 表示鉴权成功
        ...


sdk.register_auth(MyAuth())

被动交互回调注册

重要：必须在 initialize() 之前注册。每个 SDK 实例只能注册一种被动回调类型。

方法	回调类型	场景
`register_audio2_llm(cb)`	`Audio2LlmCallback`	音频→ASR+LLM
`register_audio2_tts(cb)`	`Audio2TtsCallback`	音频→ASR+LLM+TTS
`register_asr2_llm(cb)`	`Asr2LlmCallback`	文本→LLM
`register_asr2_tts(cb)`	`Asr2TtsCallback`	文本→LLM+TTS
`register_asr_video2_vlm(cb)`	`AsrVideo2VlmCallback`	文本+视频→VLM
`register_asr_video2_tts(cb)`	`AsrVideo2TtsCallback`	文本+视频→VLM+TTS
`register_audio_video2_vlm(cb)`	`AudioVideo2VlmCallback`	音频+视频→VLM
`register_audio_video2_tts(cb)`	`AudioVideo2TtsCallback`	音频+视频→VLM+TTS

v1.4.0 变更：
原 register_state_listen(...) 已移除，状态推送统一通过 PassiveCallback.on_state(...) 接收。
打招呼信令在 PassiveCallback.on_greet_signal(...) 中重载即可，无需单独注册。
已从 SDK 移除：被动回调 Audio2Asr / Audio2Audio / AudioVideo2Audio / Text2Tts（类已删除），主动接口 query_skill / query_state / register_pull_stream / register_push_listen（注册方法已删除）。
详见被动回调指南。

主动交互

任务流

python

from linksoul_agentsdk.active import TaskFlowRequest

# 注册任务流
sdk.register_task_flow(task_flow_request)

# 取消注册
sdk.unregister_task_flow(flow_id)

任务流的完整生命周期参见主动交互指南 - 任务流。

辅助方法

方法	返回值	说明
`get_agent_callback_type(agent_id)`	`AgentCallbackType \| None`	获取 agent 绑定的回调类型
`get_agent_meta(agent_id)`	`AgentMeta \| None`	获取 agent 元数据
`get_robot_callback(callback_type)`	`PassiveCallback \| None`	获取已注册的回调实例
`bind_agent_callback_type(agent_id, ct)`	`None`	内部使用（消息分发时绑定）
`bind_agent_meta(agent_id, meta)`	`None`	内部使用
`app_id` (property)	`str`	获取当前实例 app_id
`url` (property)	`str`	获取连接地址
`released` (property)	`bool`	是否已 release
`linksky_client` (property)	`LinkskyClient \| None`	已初始化的客户端实例

测试钩子

python

sdk.set_linksky_client_factory(factory)

允许测试时用 FakeLinkskyClient 替换真实 WebSocket。必须在 initialize() 之前调用。更多用法见测试约定。