被动回调 & 响应 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)。

Function Call 与 Arbiter（v1.5.0）

⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。

v1.5.0 在被动交互链路上新增 Function Call 分发与 Arbiter 仲裁，接口织入既有的 8 组回调 / 响应类。使用流程见被动交互指南 · Function Call 开放与 Arbiter 仲裁。

回调方法（8 种回调类均有）

python

def on_function_call(
    self,
    agent_id: str,
    event_id: str,
    function_call: FunctionCallInfo,
    response: <XxxResponse>,
) -> None

默认空实现，重载后可接收网关透传的 function call；<XxxResponse> 为该回调类对应的响应类型。

`FunctionCallInfo`（`linksoul_agentsdk.FunctionCallInfo`）

字段	类型	说明
`source`	`str`	function call 来源
`policy`	`str`	处理策略标识
`type`	`str`	function call 类型
`value`	`str`	主体取值
`param`	`dict`	附带参数

响应方法（8 种 Response 类均有）

python

def on_arbiter(self, event_id: str, decision: str, arb_param: AgentParam | None) -> None

回传仲裁决策，SDK 下发 agentsdk.function_call.arbiter。decision 取自 ArbiterDecision（可传 ArbiterDecision.DELEGATE.value 或字面量字符串）：

枚举（`linksoul_agentsdk.ArbiterDecision`）	wire 值	语义
`DELEGATE`	`delegate`	委派智能体默认链路处理
`OVERRIDE`	`override`	二开应用接管、覆盖默认行为
`ILLEGAL`	`illegal`	非法 / 兜底值

事件类型

agentsdk.function_call.expose（网关 → SDK，触发 on_function_call）/ agentsdk.function_call.arbiter（SDK → 网关，由 on_arbiter 发出）。见枚举参考。

基类共享方法（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 合并）；模块全集见机器人端侧状态参考
`on_function_call(agent_id, event_id, function_call, response)`	Function Call 透传（v1.5.0 新增）；`function_call` 为 `FunctionCallInfo`
`on_histories(agent_id, event_id, histories)`	对话历史透传（v1.5.0 新增）；`histories` 为 `list[HistoryInfo]`

`HistoryInfo`（`linksoul_agentsdk.HistoryInfo`，v1.5.0）

字段	类型	说明
`timestamp`	`int`	时间戳，用于排序
`query`	`str`	用户侧输入
`answer`	`str`	智能体侧回复
`complete`	`bool`	该轮是否完整结束
`event_id`	`str`	对应会话事件 ID，用于去重
`skill`	`HistoryInfo.SkillInfo`	该轮历史携带的技能信息（`type` / `value`），可为空

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 再其他"的顺序约束。