追踪 Pi 编码代理会话 - 以编程方式使用文档

本指南展示如何追踪 Pi 编码代理会话到 LangSmith，使用 @langchain/langsmith-pi-extension extension.

配置完成后，每个 Pi 会话会将追踪数据发送到 LangSmith。每条追踪记录包含用户消息、助手回复、工具调用和各个 LLM 调用，让您可以全面了解 Pi 编码代理的运行情况。

前提条件

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

- **Pi** installed.
- A **LangSmith API 密钥**.

安装

通过 Pi 安装扩展：

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

快速开始

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

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

/langsmith-tracing

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

配置

配置可以来自环境变量或 JSON 配置文件。值按以下顺序合并，后者优先级更高：

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

环境变量

变量	描述
`TRACE_TO_LANGSMITH`	设置为 `true`, `1`, `yes`, or `on`时启用追踪，设置为 `false`, `0`, `no`, or `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`.

Example:

配置文件

创建 ~/.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`	No*	—	LangSmith API 密钥。除非通过环境变量或副本提供，否则为必填。
`api_url`	否	LangSmith SDK 默认值	LangSmith API URL，通常为 `https://api.smith.langchain.com`.
`project`	No	`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 对象，用于覆盖副本运行的元数据或标签。