被动回调 & 响应 API

← 返回首页

所有 *Callback 都在 linksoul_agentsdk.passive 子包内，可统一从那里 import。

回调/响应对照表

回调类	响应类	`on_request` 签名
`Audio2LlmCallback`	`Audio2LlmResponse`	`(agent_id, event_id, flag, buf, param, response)`
`Audio2TtsCallback`	`Audio2TtsResponse`	`(agent_id, event_id, item_id, flag, buf, param, response)`
`Asr2LlmCallback`	`Asr2LlmResponse`	`(agent_id, event_id, text, param, response)`
`Asr2TtsCallback`	`Asr2TtsResponse`	`(agent_id, event_id, text, param, response)`
`AsrVideo2VlmCallback`	`AsrVideo2VlmResponse`	`(agent_id, event_id, flag, text, buf, param, response)`
`AsrVideo2TtsCallback`	`AsrVideo2TtsResponse`	`(agent_id, event_id, flag, text, buf, param, response)`
`AudioVideo2VlmCallback`	`AudioVideo2VlmResponse`	`(agent_id, event_id, flag, buf, param, response)`
`AudioVideo2TtsCallback`	`AudioVideo2TtsResponse`	`(agent_id, event_id, flag, buf, param, response)`

各 Response 可用方法

Response	ASR	LLM	VLM	TTS	Skill	Interrupt
`Audio2LlmResponse`	✓	✓			✓	✓
`Audio2TtsResponse`	✓	✓		✓	✓	✓
`Asr2LlmResponse`		✓			✓	✓
`Asr2TtsResponse`		✓		✓	✓	✓
`AsrVideo2VlmResponse`			✓		✓	✓
`AsrVideo2TtsResponse`			✓	✓	✓	✓
`AudioVideo2VlmResponse`	✓		✓		✓	✓
`AudioVideo2TtsResponse`	✓		✓	✓	✓	✓

所有 Response 均支持 on_error(event_id, error_code, error_msg)。

基类共享方法（PassiveCallback）

所有被动回调类继承自 linksoul_agentsdk.passive.PassiveCallback。下列方法可按需重载（不重载使用默认日志实现）：

方法	触发时机
`on_robot_online(agent_id, agent_meta)`	机器人上线
`on_robot_offline(agent_id)`	机器人下线
`on_face_info(agent_id, event_id, param)`	识别到人脸 / 声纹 UID（v1.4.0 开放）
`on_video_frame(agent_id, event_id, flag, buf, is_key_frame, local_ts, param)`	透传视频帧（`flag=2` H264，`flag=3` 图片）
`on_greet_signal(agent_id, event_id, param, response)`	打招呼信令（v1.4.0 合并）
`on_state(agent_id, event_id, state_name, state_value)`	机器人状态推送（v1.4.0 合并）；模块全集见机器人端侧状态参考

GreetResponse 方法

方法	说明
`on_greet_vlm_delta(event_id, text)`	VLM 流式片段
`on_greet_vlm_done(event_id)`	VLM 流式结束
`on_greet_tts_delta(event_id, audio_base64)`	TTS 音频流式片段——`audio_base64` 是合成音频字节经 base64 编码后的字符串
`on_greet_tts_done(event_id)`	TTS 音频输出结束
`on_error(event_id, code, msg)`	应答异常

类型提示与异步

所有公开类都带有完整的 typing 注解。on_request 同步调用—— WebSocket I/O 在内部独立线程跑，业务侧无需感知。多个 agent_id 的请求并行处理（一个 agent 一个 worker），同一 agent_id 的请求串行处理。

如果你的语义理解 / LLM 调用是阻塞 I/O，可直接同步调用；如果是 asyncio 协程，可在 on_request 内用 asyncio.run_coroutine_threadsafe(...) 桥接，但要注意：response.on_* 必须在协程完成后才调用，以满足"先 on_interrupt 再其他"的顺序约束。