编码代理、语音与专用追踪

一、编码代理 metadata 权威契约

所有 coding agent run 的全局身份块：

where-known 字段：

• <code>ls_agent_version</code>。
• <code>git_branch</code>、<code>git_commit_sha</code>、<code>git_repo_url</code>。
• <code>working_directory</code>。
• LLM run 的 <code>ls_model_name</code>、<code>ls_provider</code>。

专用字段：

• tool 必须有 <code>ls_tool_name</code>。
• subagent 必须有 <code>ls_subagent_id</code>、<code>ls_subagent_type</code>。
• interrupted 使用 root 字段，run type 表达异常终止。

这是权威 schema。Cursor 页面列出的 <code>repository_url</code>、<code>cwd</code> 等名称与它不一致时，应以 coding-agent-v1 为准。

二、编码代理接入差异

共同风险：

• 编码代理 trace 可能包含源码、终端输出、绝对路径、Git remote、用户提示和 secret。
• 安装前应确定 project、采样、脱敏、保留和访问控制。
• 不要把用户可控 metadata 当授权依据。
• hooks/plugin 的完成事件不等于进程一定 flush；要覆盖退出、崩溃、取消和 subagent 未完成。

VS Code Copilot 通过环境变量传 OTel headers；标准 trace 已会抑制辅助标题/摘要调用并修正重复 token，但仍应在版本升级后复验。

三、语音 Agent 的两种架构

Cascade

conversation root ├─ STT ├─ LLM ├─ tool / middleware └─ TTS

各阶段有明确请求/响应，像普通 Agent trace。

Speech-to-speech

持久 WebSocket 交换事件，没有稳定 STT/LLM/TTS 分解。子 span 应表达真实事件：转录片段、模型响应、function call/result、turn complete、interrupted、error。

语音没有可靠的人工“轮次”边界；用户会重叠、插话和拖尾。不要人为合成 turns 取代真实事件。OpenAI Realtime 页面称事件“按 turn 分组”，应理解为 Provider 报告的 turn 边界，而不是客户端重新发明边界。

四、统一语音约定

1. 一次完整 conversation 是一条 trace。
2. root metadata 设 <code>ls_modality=audio</code>。
3. root 附一个双声道合成录音：用户左、Agent 右。
4. Agent 侧记录实际扬声器播放的音频；barge-in 丢弃的生成音频不能进入录音。
5. 多次独立会话如需关联，用 thread，不把长期用户生命周期做成一条永不结束的 trace。

高流量时对完整录音降采样、压缩或抽样；转录和音频都属于敏感数据，必须有同等级权限与保留策略。

五、OpenAI Realtime

• beta。
• 安装 <code>langsmith[openai-realtime]>=0.9.7</code>。
• 原生 realtime client 用 <code>wrap_realtime</code>。
• OpenAI Agents SDK 用 <code>wrap_realtime_session</code>。
• 开启 input audio transcription 和 Agent transcript 才能在 trace 看文字。
• traceable tool 在处理事件时可自动嵌套。
• 若用 Agents SDK，应关闭其内置 OpenAI tracing，避免第二条上传链路。
• 通过 <code>record_user_audio</code> 与 <code>record_agent_audio</code> 建立真实播放录音。

六、Gemini Live

• beta。
• raw google-genai 用 <code>langsmith[gemini-live]</code> 和 <code>wrap_gemini_live</code>。
• Google ADK Live 用独立 <code>langsmith[google-adk-live]>=0.9.7</code> 与 plugin。
• 输入/输出 transcription 都是 opt-in。
• wrapper 每条连接拥有独立 transcript/state；并发会话不要共享 wrapper。
• ADK 取消时可能不触发 after_run，应在 teardown 调用幂等 <code>plugin.finalize</code>。
• 默认录音 24 kHz PCM16，两声道采样率必须一致。

七、LiveKit

• beta；基础要求 <code>langsmith[livekit]>=0.9.7</code>。
• <code>configure_livekit</code> 接管 LiveKit 已发出的 OTel spans，保留 latency/token metrics。
• 自管 TracerProvider 时必须把 processor 加到 LiveKit 实际绑定的 provider。
• realtime 模型的用户 transcript 需 <code>instrument_session</code>，要求 0.10.4+；cascade 不要调用，否则重复。

录音：

• 本地可读取 session directory 的 audio.ogg。
• 生产不可依赖临时目录，应用 LiveKit Egress 写对象存储。
• 调 <code>expect_recording</code> 后 root span 会保持打开；成功或失败都必须调 <code>complete_recording</code>，否则 trace 悬挂。

八、Pipecat

• beta；基础要求 <code>langsmith[pipecat]>=0.9.7</code>。
• task 同时开启 tracing、turn tracking、metrics。
• 内嵌 LangGraph/LangChain 作为 LLM 时，设置 <code>llm_span_kind=chain</code>，并用 <code>LANGSMITH_TRACING_MODE=otel</code>，否则内部 runs 形成另一条 trace。
• realtime 用户 transcript 要 instrument aggregator，要求 0.10.6+；cascade 不要重复 instrument。
• AudioBufferProcessor 放在 transport output 后，才能记录实际播放结果。

九、验收场景

• 正常多轮、工具调用、subagent。
• 用户 barge-in，录音中 Agent 音频确实被截断。
• WebSocket 断线/重连。
• 客户端取消、Ctrl-C、worker shutdown。
• 转录关闭时 UI 的预期退化。
• 同时 100 个会话不串 thread、audio 或 transcript。
• secret、源码、路径和附件脱敏抽检。