追踪 Pi coding agent 会话

将 Pi coding agent 的调用追踪到 LangSmith，以观察轮次、调试工具调用、跟踪 token 用量，并检查单次 LLM 调用。

本指南展示如何使用 @langchain/langsmith-pi-extension 扩展将 Pi coding agent 会话追踪到 LangSmith。

配置完成后，每个 Pi 会话都会向 LangSmith 发送追踪。每条追踪包含用户消息、助手响应、工具调用和单次 LLM 调用，让你对 Pi coding agent 的运行拥有完整的可观测性。

前置条件

在设置追踪之前，请确保你具备：

• 已安装 Pi。
• 一个 LangSmith API key。

安装

通过 Pi 安装该扩展：

pi install npm:@langchain/langsmith-pi-extension

快速开始

追踪默认处于禁用状态。设置以下环境变量以启用追踪并连接到你的 LangSmith 账号：

export TRACE_TO_LANGSMITH=true
export LANGSMITH_PI_API_KEY="<your-langsmith-api-key>"

照常运行 Pi。当会话启动时，扩展会报告 LangSmith 追踪是否已启用。你也可以随时在 Pi 中检查当前追踪状态：

/langsmith-tracing

默认情况下，追踪会写入 pi-coding-agent LangSmith 项目。

配置

配置可以来自环境变量或 JSON 配置文件。数值按以下顺序合并，靠后的来源优先：

1. 默认值
2. ~/.pi/langsmith.json（全局配置）
3. <current-working-directory>/.pi/langsmith.json（项目配置）
4. 环境变量

环境变量

变量	说明
TRACE_TO_LANGSMITH	设为 true、1、yes 或 on 时启用追踪。设为 false、0、no 或 off 时禁用追踪。
LANGSMITH_PI_API_KEY	LangSmith API key。回退到 LANGSMITH_API_KEY。
LANGSMITH_PI_ENDPOINT	用于自托管或自定义部署的 LangSmith API URL。回退到 LANGSMITH_ENDPOINT。
LANGSMITH_PI_PROJECT	LangSmith 项目名称。回退到 LANGSMITH_PROJECT。默认为 pi-coding-agent。
LANGSMITH_PI_METADATA	添加到根 run 元数据的 JSON 对象。回退到 LANGSMITH_METADATA。
LANGSMITH_PI_RUNS_ENDPOINTS	副本 run 目的地的 JSON 数组。回退到 LANGSMITH_RUNS_ENDPOINTS。

示例：

export TRACE_TO_LANGSMITH=true
export LANGSMITH_PI_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_PI_PROJECT="pi-coding-agent-dev"
export LANGSMITH_PI_METADATA='{"team":"infra","environment":"local"}'

配置文件

创建 ~/.pi/langsmith.json 作为全局设置，或在项目目录中创建 .pi/langsmith.json 作为本地覆盖：

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "pi-coding-agent",
  "metadata": { "environment": "local" }
}

配置文件字段：

字段	必需	默认值	说明
enabled	是	false	设为 true 以从配置文件启用追踪。
api_key	否*	—	LangSmith API key。除非由环境变量或副本提供，否则必需。
api_url	否	LangSmith SDK 默认值	LangSmith API URL，通常为 https://api.smith.langchain.com。
project	否	pi-coding-agent	LangSmith 项目名称。
metadata	否	—	合并到根追踪元数据的对象。
replicas	否	—	要将追踪复制到的其他 LangSmith 目的地的数组。

副本（Replicas）

使用 replicas 可以同时将追踪发送到多个 LangSmith 目的地。这适用于将追踪同时转发到个人工作区和共享团队项目，或同时发送到自托管 LangSmith 实例和云端。

{
  "enabled": true,
  "api_key": "<primary-api-key>",
  "project": "pi-coding-agent",
  "replicas": [
    {
      "api_key": "<replica-api-key>",
      "api_url": "https://replica-langsmith.example.com",
      "project": "pi-coding-agent-replica",
      "updates": {
        "tags": ["replica"]
      }
    }
  ]
}

每个副本条目都可以包含 updates 对象，用于覆盖副本 run 的元数据或标签。

---