跟踪 Pi 编程代理会话

本指南向您展示如何使用 @langchain/langsmith-pi-extension 扩展将 Pi 编程代理会话跟踪到 LangSmith。配置完成后，每个 Pi 会话都会向 LangSmith 发送跟踪数据。每条跟踪包含用户消息、助手响应、工具调用和单次 LLM 调用，这使您能够对 Pi 编程代理的运行进行全面观察。

前提条件

在设置跟踪之前，请确保您已：

安装了 Pi。
拥有一个 LangSmith API 密钥。

安装

通过 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 配置文件。值的合并顺序如下，后来源的优先级更高：

默认值
~/.pi/langsmith.json（全局配置）
<当前工作目录>/.pi/langsmith.json（项目配置）
环境变量

环境变量

变量	描述
`TRACE_TO_LANGSMITH`	设置为 `true`、`1`、`yes` 或 `on` 时启用跟踪。设置为 `false`、`0`、`no` 或 `off` 时禁用跟踪。
`LANGSMITH_PI_API_KEY`	LangSmith API 密钥。如果未设置，将回退到 `LANGSMITH_API_KEY`。
`LANGSMITH_PI_ENDPOINT`	用于自托管或自定义部署的 LangSmith API URL。如果未设置，将回退到 `LANGSMITH_ENDPOINT`。
`LANGSMITH_PI_PROJECT`	LangSmith 项目名称。如果未设置，将回退到 `LANGSMITH_PROJECT`。默认为 `pi-coding-agent`。
`LANGSMITH_PI_METADATA`	添加到根运行元数据中的 JSON 对象。如果未设置，将回退到 `LANGSMITH_METADATA`。
`LANGSMITH_PI_RUNS_ENDPOINTS`	副本运行目标的 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 密钥。除非由环境变量或副本提供，否则必需。
`api_url`	否	LangSmith SDK 默认值	LangSmith API URL，通常是 `https://api.smith.langchain.com`。
`project`	否	`pi-coding-agent`	LangSmith 项目名称。
`metadata`	否	—	合并到根跟踪元数据中的对象。
`replicas`	否	—	用于将跟踪复制到的其他 LangSmith 目标的数组。

副本

使用 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 对象，用于覆盖复制的运行上的元数据或标签。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

前提条件

安装

快速开始

配置

环境变量

配置文件

副本

​前提条件

​安装

​快速开始

​配置

​环境变量

​配置文件

​副本

前提条件

安装

快速开始

配置

环境变量

配置文件

副本