--- name: latentx description: 在现有项目中接入 LatenTX Realtime API、构建 IM 或网页语音客服、设计和调优业务 Prompt/Skill/知识/MCP 配置。使用一个入口按任务读取相关模块。 --- # LatenTX Agent Skill 帮助用户在自己的项目中接入 LatenTX。先识别用户要交付的功能、现有技术栈与已接通部分,再只读取相关模块;已有有效配置优先做局部修改,不重建整个项目。 ## 按任务读取 | 用户要做的事 | 先读取 | 需要时再读取 | | --- | --- | --- | | 直接调用 API、核对转写与响应用量、排查鉴权或事件错误 | [API 接入](references/api-integration.md) | [事件与工具协议](references/protocol.md) | | 编写或调优业务 Prompt、Skill、知识、MCP/function 配置 | [业务配置设计](references/agent-design.md) | 模块内的流程方法、评测与配置样例;需要接 API 时再读 API 模块 | | 配置知识、流程 Skill 或挂载已有资源 | [知识与流程配置](references/knowledge.md) | [管理与发布](references/management.md) | | 发布自定义模型、接入电话或查询通话与录音 | [管理与发布](references/management.md) | 对应的官方 Admin API;开发网页通话界面时再读网页语音模块 | | 做文本聊天页面 | [IM 应用](references/im-app.md) | [API 接入](references/api-integration.md);复杂业务再读业务配置设计 | | 做网页麦克风多轮对话 | [网页语音应用](references/voice-app.md) | [业务配置设计](references/agent-design.md);不要改走原生 OpenAI SDP | | 使用或改造完整客服参考工程 | [Studio Partner](https://github.com/aibpo-labs/studio-partner) 的 README 与工程内 Skill | 只读取本 Skill 中涉及的 API、IM、网页语音或业务配置模块 | 不要默认加载全部模块。任务同时需要两种能力时组合对应模块,例如“按救援流程做语音客服”需要业务配置设计和网页语音。 ## 选择接入方式 - 已有应用:在现有项目内完成接入,保留技术栈、登录和业务结构,无需下载参考工程。 - 需要完整参考工程:使用公开的 [Studio Partner 仓库](https://github.com/aibpo-labs/studio-partner)。安装、运行、版本和工程扩展方式以该仓库 README 及工程内 Skill 为准;不要套用其他示例的目录、启动命令或应用接口。 - LatenTX 公共 API、模型配置和鉴权以当前官方文档为准。工程自己的后端接口不属于平台 API。自定义模型使用 `base_model` 选择基础模型,语言和音色来自该模型的目录能力。 - 使用 Studio Partner 时,先读取工程 README、适用的项目指引和工程内 Skill,再按当前任务读取本 Skill 的对应模块。工程文档负责安装、目录和应用实现;本 Skill 与官方协议负责平台接入。发现工程示例与当前公开协议不一致时,明确差异,按用户任务范围处理,不把工程接口推断为平台接口。 ## 两条接入路径 - 临时对话:直接选择预定义 LatenTX 模型,在 `session.update` 配置 `instructions`、`tools`、`tool_choice` 和支持的音频参数。不要先创建独立 Agent 或型号绑定。配置仅属于当前连接。 - 可复用业务配置:沿用 `/voice/v1/custom-models` 的草稿 → 校验 → 发布流程,使用实际返回的 `custom-…-vN`。业务 Skill 先用 `PUT /voice/v1/skills/{id}/versions/{version}` 保存,`config.skills` 只填 `{id,version,preload}`;内联 `markdown` 只用于临时会话,放进自定义模型会在校验时返回 400。保持用户现有模型版本、知识与电话绑定;不要迁移成另一套 Agent 接口。 - 挂载流程或知识时读取 [知识与流程配置](references/knowledge.md);编排发布或读取通话时读取 [管理 API](references/management.md)。 ## 共同约定 - 当前 API 真相入口:https://api.latenth.com/llms.txt。实现前只读与任务相关的官方文档,协议细节以当前文档为准。 - 基础调用只需平台 Key、模型与 instructions;通过 `GET /v1/models` 确认权限和实际型号,不要求先创建 Agent。保存和发布自定义模型只用于需要复用配置的场景。 - 长期 `LATENTX_API_KEY` 留在后端;浏览器用自己的后端或 SDK 短期凭证。沿用项目现有登录、模型授权和会话归属,不把演示后端直接公开。 - 本 Skill 安装在 Codex/Claude 等编程助手中。通话业务 Skill 是通过 `session.latentx.skills` 或自定义模型传入的业务内容;不要把本开发手册挂载给客服模型。 - Realtime WS 是 OpenAI GA 风格事件子集;网页语音使用官方 SIP/WebRTC SDK。只使用已发布的接口,不虚构执行结果。 - 安装、读取文档和本地 demo 不调用模型。真实 API 与网页通话正常计费,按用户已授权范围测试,不因安装 Skill 自动发起付费调用或发布配置。 - 按实际结果报告:代码实现、模拟测试、真实文本、工具执行、人工音频验收分别说明。缺少 Key 时仍可完成代码与模拟验证,不宣称云端已验收。 ## 示例与验证资源 - [参考工程与验证示例](https://api.latenth.com/docs/ai-skills.html#examples):按需选择 Studio Partner 或独立 API 验证脚本。安装本 Skill 不会下载或启动工程;组件演示与真实服务调用按工程说明分别验证。 - [单轮 WS 验证脚本](scripts/realtime-smoke.mjs):后端 Node 20+ 和 `ws`;仅单轮文本,禁用工具,不验证录音与历史保存,运行会产生正常 API 费用。 - [业务配置样例](assets/session.example.json)、[评测样例](assets/eval-cases.json):虚构无工具场景,按真实业务材料改写。 交付时给出可运行的改动、配置位置和验证结果;保留用户原有版本与未涉及配置,不输出 Key、客户录音或私有业务材料。 历史会话与关键事件查询参阅 references/management.md;Realtime 新会话自动记录,勿要求用户额外发送保存指令。 ## 会话过程与录音查询 - 新会话默认记录事件。电话、网页和 Realtime 统一查询 `GET /voice/v1/conversations/{id}/events`;Realtime 使用 `session.created` 的会话 ID。 - 完整 Realtime 历史条目的 `data` 与实时服务端事件使用同一披露映射,保留 event_id、类型与内容,音频 Base64 分片除外。发送记录不代表客户端收到或用户已听到。电话和网页保留原生语义。 - 原样传递不透明 `next_cursor`,即使 items 为空也继续,直到没有下一游标。检查 `capture_state`;legacy、partial、unavailable、expired 均不能声称完整。活跃会话结束后重新查询。 - `GET /voice/v1/conversations/{id}/recordings` 查询 Realtime 录音轨道;电话和网页优先从详情 recording 取整通录音;开通分段录音时也可查询 /recordings。整通文件与分段分别判断状态。录音独立开通,链接过期重新查询。没有录音不能重建音频,不承诺逐字或逐音频事件回放。 - 已开通电话计费的账号,电话按四类实际用量扣钱包,日志为 phone / Voice Phone;结束后结算并释放预留额度,不含运营商费用。客户不需要调用计费回调。 - 自定义模型使用方式保持不变。历史查询使用同账号 API Key,不输出凭据、内部成本、供应商或执行配置。 For single-call phone outbound, read [management.md](references/management.md#atomic-phone-outbound); use a model ID and owned phone ID with a stable request_id.