07 可观测与用量

Agent 从黑盒变可追踪、可计量;主流观测厂商直接下场

1. 这个方向的插件试图解决什么问题

随着编码 Agent 进入日常工程与团队生产,单看终端输出无法还原某次复杂任务的完整调用链、耗时瓶颈与失败原因;同时多模型切换与订阅配额混用,也让开发团队迫切需要精确查看实时配额、重置时间与 API 余额。

LangSmith、Datadog、Braintrust、Langfuse 等可观测与运维厂商陆续发布官方 Pi 插件,是生态成熟度最直观的信号。这类扩展既负责把 Agent 执行链条往外推(Tracing),也负责把线上生产日志与监控数据拉进 Agent 对话里(Querying)。

2. 在 Pi 里怎么体现

Trace 类扩展(@langchain/langsmith-pi-extension、@braintrust/pi-extension、@langfuse/pi-observability-plugin)通过订阅 Pi 完整生命周期事件(session_start、turn_start、before_provider_request、message_end、tool_execution_start/update/end、turn_end、agent_end),把每一轮推理与工具调用无侵入地组装为 Span 树并上报。

用量与运维接入类扩展则分两条路:@narumitw/pi-usage 监听模型请求并查询各厂商官方配额/余额接口;@datadog/pi-plugin 与 @agimon-ai/po-logsink 则把观测平台本身注册成可查询工具或 MCP 服务。

涉及的 Pi 事件钩子与注册接口

turn_start / turn_endbefore_provider_requestmessage_endtool_execution_start / endagent_endsession_compactpi.registerCommand()ctx.ui.setStatus()

3. 代表包与生态实例

下表包名均核实自 npm、GitHub 与 pi.dev/packages(核对日期 2026-11-22)。前 3 项已上线独立机制详评页,正文不展示容易过期的静态下载量快照。

包名 分发形态 主要作用 详情 / 源码
@langchain/langsmith-pi-extension npm LangChain 官方发布的 Pi 扩展,将轮次、工具调用、token 用量与单次 LLM 请求追踪至 LangSmith。
@datadog/pi-plugin npm Datadog 官方插件,通过预配置的 Datadog MCP Server 让用户在 Pi 对话中查询日志、指标、链路和监控面板。
@narumitw/pi-usage npm 在 Pi 中查看各模型服务商的用量、限额、重置时间与 API 余额,支持切换 Codex Fast 模式。
@braintrust/pi-extension npm Braintrust 官方 Pi 扩展,自动采集会话、轮次、LLM 调用与工具执行轨迹。
@langfuse/pi-observability-plugin npm Langfuse 官方开源观测扩展,面向 Pi 采集提示词、轮次、生成与工具调用链路。
pi-claude-bridge npm 通过 Claude Agent SDK 把 Claude Code 包装为 Pi 的可用模型 Provider。
@agimon-ai/po-logsink npm 带 HTTP 日志摄入与 AI 分析能力的 MCP 日志汇扩展,属于 Po 工具套件成员。

4. 怎么装

代表包安装命令示例
pi install npm:@langchain/langsmith-pi-extension
  • Tracing 类扩展通常默认关闭,需配置对应平台的 API Key 与开关环境变量(如 TRACE_TO_LANGSMITH=true 与 LANGSMITH_PI_API_KEY)后才会外发链路数据。
  • 开启全量链路追踪会把用户提示词、工具输入输出与模型响应发往配置的观测平台,在涉及敏感仓库时需先评估平台数据驻留策略。
  • @narumitw/pi-usage 需要 Pi 0.81.0+ 以校验生效中的 Provider Base URL 再发送认证凭据。

5. 和同类怎么选

包名厂商/作者数据流向核心用途
@langchain/langsmith-pi-extension LangChain 官方 Pi → LangSmith 追踪会话轮次、工具调用、LLM 请求参数与 token 用量
@braintrust/pi-extension Braintrust 官方 Pi → Braintrust 自动追踪 Pi 会话、轮次、模型调用与工具执行链路
@langfuse/pi-observability-plugin Langfuse 官方 Pi → Langfuse(支持 OTEL) 采集提示词、轮次、生成与工具调用 Span 上报 Langfuse
@datadog/pi-plugin Datadog 官方 Datadog MCP → Pi 通过预配置 Datadog MCP 在对话中直接查询日志、指标、Trace 与看板
@narumitw/pi-usage 社区(narumiruna) Provider 用量接口 → Pi 状态栏 查看多厂商订阅配额、API 余额、重置时间并管理 Codex Fast 模式
pi-claude-bridge 社区(elidickinson) Claude Agent SDK 桥接 将 Claude Code(通过 Agent SDK)注册为 Pi 的模型 Provider
@agimon-ai/po-logsink AgiFlow(Po 套件) HTTP 日志汇 → Pi MCP 本地接收 HTTP 日志流并通过 MCP 与 AI 分析能力暴露给 Agent

看完「07 可观测与用量」后的下一步

可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)

从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频

已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)

出口 1(配置单与实机演示制作中)

Coding Agent 实战交付课:如何可控地把想法做成线上产品

由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。

出口 2(实战交付课筹备中)