@langchain/langsmith-pi-extension
LangChain 官方出品的 Pi 链路追踪扩展,把会话轮次、模型请求、工具调用与 token 用量自动上报至 LangSmith。
安装命令
pi install npm:@langchain/langsmith-pi-extension 临时试用 / 替代安装命令
pi -e npm:@langchain/langsmith-pi-extension 挂接事件钩子与注册入口
session_start / session_shutdownsession_compactbefore_agent_start / agent_end / agent_settledturn_start / turn_endbefore_provider_requestmessage_endtool_execution_start / tool_execution_update / tool_execution_end
pi.registerCommand("langsmith-tracing")ctx.ui.setStatus() / notify() 1. 是什么
@langchain/langsmith-pi-extension 是 LangChain 官方仓库维护的 Pi 可观测扩展。
无需改动现有任何工作流或提示词,只需配置 API Key 与开关变量,即可在 LangSmith 控制台回放 Pi 的完整执行轨迹。
2. 解决什么问题
编码 Agent 在本地跑几十轮工具调用后失败或消耗大量 token 时,终端日志只能看到最终文本输出,很难定位究竟是哪一轮提示词膨胀、哪个工具返回异常,还是哪次模型请求耗时最长。
3. 作用原理(事件钩子与工具注册层)
完整订阅 Pi 从会话起止、轮次、Provider 请求到工具执行的 13 个生命周期钩子,无侵入构建层级化 Trace Span 树。
- 在 session_start 读取环境变量与两级 JSON 配置(~/.pi/langsmith.json → .pi/langsmith.json → 环境变量依次覆盖),决定是否激活追踪并在状态栏告知当前追踪状态。
- 收到用户任务后,在 before_agent_start 到 agent_end/agent_settled 之间创建根 Run;每个推理轮次(turn_start/turn_end)与每次模型发送请求(before_provider_request 到 message_end)形成子 Span,记录输入消息、输出与 token 统计。
- 所有工具调用通过 tool_execution_start/update/end 挂到当前轮次节点之下,形成完整的父子调用树异步写入 LangSmith(默认项目名 pi-coding-agent)。
4. 怎么装与基本配置
- 追踪默认处于关闭状态。启用需设置环境变量:export TRACE_TO_LANGSMITH=true 与 export LANGSMITH_PI_API_KEY=“<你的Key>”。
- 可在 Pi 内输入 /langsmith-tracing 随时检查当前会话的追踪开关、目标项目名与上报健康状态。
5. 和同类怎么选
LangSmith、Braintrust 和 Langfuse 三家官方 Pi 扩展采用了相似的生命周期钩子接入方式,选型主要取决于团队现有的 LLMOps 平台栈。
与同类方案的选型对照
聚焦机制差异与适用边界,结合自身运行环境判断是否引入或保留同类替代包。
| 对比对象 | 机制差异 | 怎么选 |
|---|---|---|
@braintrust/pi-extension | 同样自动采集 session / turn / LLM / tool 轨迹,但后端接入 Braintrust 评估与追踪平台。 | 团队已经在用 Braintrust 做 eval 与提示词实验时选 @braintrust/pi-extension。 |
@langfuse/pi-observability-plugin | 开源架构(支持 OpenTelemetry 与自托管部署),面向 Langfuse 后端上报。 | 需要数据完全留在自建内网服务器或基于 OTEL 管道整合时选 Langfuse 扩展。 |
看完「@langchain/langsmith-pi-extension」后的下一步
可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)
从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频
已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)
说明:此处未向后台提交个人资料或邮件表单。配置单与实机演示视频正在制作中,你的匿名点击已计入站点热度,用于排定优先录制方向。
Coding Agent 实战交付课:如何可控地把想法做成线上产品
由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。
说明:此处未向后台提交报名或收集任何个人信息。课程模块仍在筹备阶段,你的匿名点击将作为模块排期的优先参考。