---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - langchain
  - langsmith
  - coding-agent
  - voice-agent
topic: LangSmith 编码代理、语音与专用追踪
sources:
  - https://docs.langchain.com/langsmith/coding-agent-metadata-contract
  - https://docs.langchain.com/langsmith/trace-claude-code
  - https://docs.langchain.com/langsmith/trace-gemini-live
  - https://docs.langchain.com/langsmith/trace-openai-realtime
  - https://docs.langchain.com/langsmith/trace-voice-fundamentals
  - https://docs.langchain.com/langsmith/trace-with-codex
  - https://docs.langchain.com/langsmith/trace-with-cursor
  - https://docs.langchain.com/langsmith/trace-with-livekit
  - https://docs.langchain.com/langsmith/trace-with-opencode
  - https://docs.langchain.com/langsmith/trace-with-pi
  - https://docs.langchain.com/langsmith/trace-with-pipecat
  - https://docs.langchain.com/langsmith/trace-with-vscode-copilot
last_verified: 2026-08-11
---

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

## 一、编码代理 metadata 权威契约

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

| 字段 | 约束 |
|---|---|
| ls_agent_type | root、subagent、middleware、compaction |
| ls_agent_purpose | 例如 coding |
| ls_integration | claude-code、openai-codex、deepagents-code、cursor、pi、opencode、copilot |
| ls_agent_runtime | 可读运行时名称 |
| thread_id | 稳定对话线程 |
| ls_trace_schema_version | 当前为 coding-agent-v1 |

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 为准。

## 二、编码代理接入差异

| 集成 | 方式 | 当前边界 |
|---|---|---|
| Claude Code | LangSmith plugin/hooks | 完整 transcript 通常不含 system；未完整/中断会话 flush 有差异；subagent 可能只在完成时完整 |
| Codex CLI | plugin/hooks | 要求 CLI 0.128+；记录 transcript、tools、subagents |
| Cursor | hooks | Node 22.13+；附件可能来自本地 SQLite；auto mode 成本和 subagent token 有限制 |
| OpenCode | plugin | 主要记录完成的 turns；中断路径需单测 |
| Pi | extension | 配置有多层优先级，部署时固定唯一来源 |
| VS Code Copilot | OTel | 内容捕获需 opt-in；仍可能含 source、system、tool 细节 |

共同风险：

- 编码代理 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、源码、路径和附件脱敏抽检。