AIMA开放平台文档中心Agent SDK (Python)

名词解释 / Glossary

名词解释 / Glossary

本页汇总 LinkSoul AgentSDK（Python）文档中出现的核心术语，分为「业务概念」「被动交互与主动交互详解」「SDK 术语」「模型与音视频」「对话决策与拒识」「JSON 协议字段」六类。 每个词条给出一句话解释 + 在文档中的相关入口。

一、业务概念

名词解释
灵心开放平台智元（agibot）面向开发者的开放平台，提供应用注册、智能体配置、网关接入等能力。app_id / app_key / app_secret 在该平台上申请。
LinkskyGateway灵心开放平台的接入网关，地址为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk，负责承载 SDK 与机器人之间的双向 WebSocket 消息。
智能体（Agent）灵心平台上配置的一个虚拟角色（含人设、技能、知识库等）。机器人在端侧绑定该智能体后即可上线，由 SDK 接管其语义/技能/任务流处理。
二开（二次开发）在灵心默认能力之上，由开发者通过 AgentSDK 自定义 ASR/LLM/技能/任务流等业务逻辑。
机器人（Robot）端侧硬件实体，与一个或多个智能体绑定后上线，作为消息源（音频/视频/文本）和执行端（TTS 播报、技能动作）。
被动交互（Passive）机器人发起请求 → SDK 处理 → SDK 通过 Response 回填结果（ASR/LLM/VLM/TTS/技能/打断）。
主动交互（Active）SDK 主动向机器人发起任务，v1.4.0 公开入口仅 任务流（Task Flow）。
任务流（Task Flow）SDK 主动下发的多步骤任务编排，包含 start / task / end / interrupt 四阶段，payload 为 JSON 数组，支持 SIMPLE / COMPLEX 两种模式。
技能（Skill）机器人可执行的具名动作（如 move_forward、wave_hands），通过 response.on_skill(...) 或任务流下发。技能全集见 语义技能参考。
打招呼（Greet）机器人通过人脸/UID/视频/业务信令触发的"主动招呼"场景，SDK 通过 on_greet_signal + GreetResponse 回填 VLM/TTS。
打断（Interrupt / Barge-in）当用户在机器人播报中再次说话时，SDK 通过 response.on_interrupt(...) 终止当前播报并切换到新意图。

二、被动交互与主动交互详解

二者的根本差别在于消息发起方：

维度被动交互（Passive）主动交互（Active）
发起方机器人（端侧）通过 LinkskyGateway 推送SDK（业务侧）主动下发到机器人
触发时机用户说话 / 看到人脸 / 视频帧 / 端侧上报状态等业务系统判定需要让机器人执行某个流程时（如"打开客厅灯"" 巡检 5 个点位"）
入口 APIregister_audio2_llm / register_asr2_llm / register_asr_video2_vlm 等 8 套 register_* + 对应 on_request 回调agent_sdk.register_task_flow(TaskFlowRequest) + flow.start_request / task_request / end_request / interrupt_request
数据载体回调参数 text / buf / video / param + Response 应答对象TaskFlowRequest 的 payload （JSON 数组）+ 两阶段 RequestAck / ExecuteAck 回执
应答方式在 on_request 中调用 response.on_llm_* / on_tts_* / on_skill / on_interrupt / on_error各阶段挂 FlowStart/Task/End/InterruptCallback，等待网关 / 机器人异步回执
v1.4.0 范围8 种被动回调全部可用仅公开 任务流；其余主动接口（技能查询 / 状态查询 / 拉流 / 推流监听）从公开 API 移除

被动交互（Passive）

  • 谁来发起：机器人端侧。用户在机器人前说话、出现人脸、设备状态变更等，由端侧封装为协议事件，经 LinkskyGateway 推到 SDK。
  • SDK 内部流转：SDK 根据事件类型路由到对应的 *Callback.on_request(...)。8 种被动回调按"输入 → 输出"组合命名：
    输入输出回调类
    音频LLM 文本Audio2LlmCallback
    音频LLM + TTSAudio2TtsCallback
    ASR 文本LLM 文本Asr2LlmCallback
    ASR 文本LLM + TTSAsr2TtsCallback
    ASR 文本 + 视频VLM 文本AsrVideo2VlmCallback
    ASR 文本 + 视频VLM + TTSAsrVideo2TtsCallback
    音频 + 视频VLM 文本AudioVideo2VlmCallback
    音频 + 视频VLM + TTSAudioVideo2TtsCallback
  • 每个 SDK 实例只能注册一种被动回调类型——这一约束由 AgentSdk 强制。
  • 共享基类 PassiveCallback 上定义了和具体输入/输出无关的事件：on_robot_online / on_robot_offline / on_face_info / on_video_frame / on_greet_signal / on_state，它们独立于 on_request，覆盖机器人级别的生命周期与状态推送。
  • 应答必须显式回填——拒识时直接 return；正常应答必须按顺序触发 on_interrupt → on_skill?(可选) → on_llm_*/on_tts_*/on_vlm_* → on_llm_done/on_tts_done。
  • 详见 被动交互指南。

主动交互（Active）—— v1.4.0 仅任务流

  • 谁来发起：业务系统（你的代码）。当上层业务（外部触发、调度系统、其他模型）判定需要让机器人主动执行任务时，SDK 通过 LinkskyGateway 把任务下发到机器人。
  • 唯一公开入口：register_task_flow(TaskFlowRequest)。技能查询 / 状态查询 / 拉流 / 推流监听这些 v1.3.0 时露出过、但 从未真正可用 的入口在 v1.4.0 已从公开 API 移除。
  • 任务流四阶段：
    1. start_request(payload, callback, timeout) — 启动一次任务流。
    2. task_request(payload, callback, timeout) — 下发任务步骤，可多次。
    3. end_request(callback, timeout) — 正常结束。
    4. interrupt_request(callback, timeout) — 中断当前流程。
  • 两阶段回执：每次 *_request 都有 RequestAck（机器人收到）和 ExecuteAck（机器人执行完成）两次异步回调，code=0 即该阶段成功。
  • payload 结构：JSON 数组（COMPLEX）/ 单步对象（SIMPLE），由 action_group / action_type 等字段描述要执行的技能编排。详见 任务流 payload 协议。
  • 状态反馈：任务流执行过程中机器人的端侧状态变化（导航进度、播报状态等）通过被动通道里的 on_state(...) 推回，主被动通道在状态层面打通。
  • 详见 主动交互指南。

被动 vs 主动 协作模式

实际项目里两条通道经常配合：

  • 被动响应触发主动任务流：用户说"带我去会议室"→ Asr2LlmCallback.on_request 收到 → 业务侧解析为导航意图 → 通过 TaskFlowRequest 下发任务流让机器人去导航。
  • 主动任务流期间监听被动事件：任务流执行中用户喊话打断 → 被动通道收到新 event_id 的 on_request → 业务侧调用 flow.interrupt_request(...) 中断当前任务流。
  • 状态打通：被动 on_state 收到 task_status 更新可以驱动主动侧的下一步决策。

三、SDK 术语

名词解释
app_id灵心开放平台为应用分配的唯一标识。
app_keyv1.4.0 引入，HMAC-SHA256 签名所需的访问 key，配合 app_secret 使用。
app_secretHMAC-SHA256 签名密钥，严禁泄漏到客户端、日志、Git 仓库。
agent_id灵心平台上配置的智能体 ID（如 AGENT_0000001），机器人在端侧绑定后通过 on_robot_online(agent_id, ...) 回传。不是机器人硬件标识。
event_id一次完整对话/事件的唯一标识，所有响应都需带回该 ID 以归属同一事件。
item_id同一 event_id 中多个意图/响应片段（如多段 LLM 输出、多个 TTS 段）的标识。
flow_id任务流实例的唯一标识，由 IdGenerator.generate_flow_id() 生成。
signal_id业务信令（如打招呼）的唯一标识。
flag仅在音视频回调中出现的生命周期标志，标记当前帧是 START / APPEND / COMMIT 等阶段。
AgentSdkSDK 主入口类，单例（同一 app_id 多次 create() 返回同一实例），负责连接/认证/回调注册/任务流分发。
AgentParam类型安全的 KV 扩展参数容器，支持链式调用（set_string / set_integer / set_double / set_boolean / set_long / set_object / set_list）。
AgentMeta机器人上线时 on_robot_online 回调返回的元数据：唤醒词、所在城市、机器人名、热词、自定义字段。
PassiveCallback所有被动回调（Audio2LlmCallback / Asr2LlmCallback / AudioVideo2VlmCallback …）的基类，提供 on_robot_online / on_robot_offline / on_face_info / on_video_frame / on_greet_signal / on_state 共享方法。
Response 对象每个 on_request 回调中传入的应答对象，按场景提供 on_asr_* / on_llm_* / on_vlm_* / on_tts_* / on_skill / on_interrupt / on_error 等方法。
on_state(state_name, state_value)机器人端侧状态推送，22 个 state_name 模块及字段定义见 机器人端侧状态参考。
RequestAck / ExecuteAck任务流两阶段确认：前者代表机器人收到请求，后者代表执行完成；code=0 即成功。

四、模型与音视频

名词解释
ASR（Automatic Speech Recognition）语音识别，把音频转为文本。SDK 中由网关或上游模块完成，常以 text 字段回传。
NLU（Natural Language Understanding）自然语言理解，对 ASR 文本做意图识别 / 槽位抽取 / 实体识别等结构化解析；二开侧通常在 on_request 拿到 text 后接入自有 NLU 模块，再决定是回 LLM 闲聊、下发技能，还是按拒识处理。
LLM（Large Language Model）大语言模型，处理文本理解 + 文本生成，SDK 通过 on_llm_item_delta/done 流式输出。
VLM（Vision-Language Model）多模态视觉语言模型，接收图像/视频 + 文本，输出语义结果，对应 on_vlm_* 系列方法。
TTS（Text-To-Speech）文本转语音，SDK 通过 on_tts_delta/done（音频 base64）流式回填。
VAD（Voice Activity Detection）语音活动检测，识别用户说话起止；对应协议事件 agentsdk.audio_request.start / commit。
RAG 知识库（Retrieval-Augmented Generation）检索增强生成：先用用户问题检索向量/关键词知识库，将命中片段作为上下文喂给 LLM，再产出答案。常用于把私域知识/FAQ/手册接入二开 LLM 流程，避免幻觉。在 SDK 中通常嵌在 on_request 收到 text 之后、on_llm_item_delta 流式输出之前。
关键帧 / is_key_frame视频帧回调中标记当前帧是否 H264 IDR 关键帧。
base64 音频片段TTS / 打招呼 TTS 流式输出的音频数据以 base64 字符串形式封装在协议字段中。

五、对话决策与拒识

名词解释
拒识（Reject）对话系统在 ASR/NLU/LLM 链路中识别到"无法/不应处理"的输入后选择静默不应答或返回兜底话术的行为。SDK 侧体现为 on_request 收到 text 后直接 return（不调用任何 response.on_*）或仅返回错误。
通用拒识（General Reject）与具体业务场景无关的拒识，典型触发：空文本 / ASR 置信度过低 / 噪声 / 闲聊中夹带的无意义短语 / 命中通用敏感词。一般在所有业务垂类前先做一道过滤。
垂类拒识（Domain Reject）在某一业务领域内（如医疗、金融、家政、儿童陪伴）专门定义的"不在本垂类服务范围"或"本垂类禁止回答"的输入。通常基于垂类意图分类器的置信度、领域白名单/黑名单、垂类敏感词表来判断；命中后或静默或回兜底话术。
兜底话术（Fallback）拒识或 LLM 失败后给出的固定应答，例如"这个问题我暂时没法回答"。

六、JSON 协议字段（任务流 / 状态）

字段解释
action_group任务流 payload 中的动作分组，定义一组并行/串行的子动作。
action_type动作类型（如 target_poi、tts_speak），由灵心平台技能定义；详见 任务流 payload 协议。
state_name（22 模块）机器人端侧状态名，包括 robot_pose、tts_status、robot_form、task_status 等；字段表见 机器人端侧状态参考。
SIMPLE / COMPLEX 模式任务流的两种编排模式：SIMPLE 单步直发；COMPLEX 完整三阶段（start → task* → end），可中途 interrupt。

相关入口