给 Pi Agent 接入 Langfuse：一份简单的可观测性教程

本文介绍如何参考 Langfuse 官方教程，为 Pi Agent 接入 Langfuse，从而查看 Agent 的运行轨迹、模型调用、工具执行、Token 消耗和耗时。

为什么要接入 Langfuse？

Pi Agent 能够调用大模型和各种开发工具完成任务，但当一次任务执行失败、响应变慢或成本异常时，仅查看终端输出通常很难定位原因。

接入 Langfuse 后，我们可以在可视化页面中观察：

• 每次 Agent 会话及其完整执行链路
• 大模型的输入、输出和调用耗时
• Agent 发起的工具调用及其结果
• Token 使用量和模型成本
• 不同任务之间的性能差异

简单来说，Langfuse 相当于给 Pi Agent 增加了一套“运行记录和调试面板”。

准备工作

开始前需要准备：

1. 已经安装并能正常运行的 Pi Agent
2. 一个 Langfuse Cloud 或自托管 Langfuse 实例
3. Langfuse 项目的 Public Key 和 Secret Key

如果还没有 Langfuse 项目，可以登录 Langfuse，新建一个项目，然后在项目的 API Keys 页面创建密钥。

第一步：安装 Langfuse 集成

按照官方集成页面提供的命令安装 Pi Agent 的 Langfuse 扩展。当前版本可使用类似下面的命令：

pi install npm:pi-langfuse

由于 Pi Agent 的扩展生态仍在更新，如果该命令与官方页面不一致，应以官方页面显示的最新安装命令为准。

安装完成后，重新启动 Pi Agent，使扩展被正确加载。

第二步：配置 Langfuse 环境变量

重启pi的时候会自动弹出配置引导了，所以这一步其实没那么复杂，去Langfuse申请的配置复制后丢到pi输出的引导中就可以了。

扩展需要通过环境变量读取 Langfuse 地址和项目密钥。

Linux 或 macOS：

export LANGFUSE_PUBLIC_KEY="pk-lf-你的公钥"
export LANGFUSE_SECRET_KEY="sk-lf-你的密钥"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

Windows PowerShell：

$env:LANGFUSE_PUBLIC_KEY="pk-lf-你的公钥"
$env:LANGFUSE_SECRET_KEY="sk-lf-你的密钥"
$env:LANGFUSE_BASE_URL="https://cloud.langfuse.com"

如果使用 Langfuse 美国区，将地址改为：

https://us.cloud.langfuse.com

如果使用自托管版本，则填写自己的 Langfuse 服务地址。不要在地址末尾额外添加 API 路径，除非官方文档明确要求。

Secret Key 属于敏感凭据，不要提交到 Git 仓库，也不要直接写入公开代码。

第三步：运行一次 Pi Agent 任务

完成配置后，在设置环境变量的同一个终端中启动 Pi Agent：

pi

随后执行一个简单任务，例如：

阅读当前项目的 README，并总结项目的主要功能。

Pi Agent 会正常调用模型和工具，同时由 Langfuse 扩展采集相关观测数据。

第四步：在 Langfuse 中查看 Trace

打开 Langfuse 项目，进入 Tracing 页面。正常情况下，可以看到刚才产生的一条 Trace。

点开 Trace 后，通常可以检查：

• 用户输入的任务内容
• Agent 的多轮执行过程
• 模型请求及模型输出
• 工具名称、参数和执行结果
• 每个步骤的耗时
• Token 用量及估算成本

当任务结果不符合预期时，可以从上到下检查整条调用链，确认问题发生在提示词、模型推理、工具调用还是工具返回阶段。

常见问题

Langfuse 中没有出现 Trace

首先确认环境变量和 Pi Agent 位于同一个终端会话中。然后检查：

• Public Key 和 Secret Key 是否属于同一个项目
• LANGFUSE_BASE_URL 是否对应正确的云端区域
• Langfuse 扩展是否已经成功安装和加载
• 当前网络是否能够访问 Langfuse
• 关闭 Agent 时是否直接强制终止，导致尚未上传的数据来不及发送

Trace 中缺少部分数据

部分遥测数据可能会在任务结束时批量上传。应让 Pi Agent 正常完成或退出，避免直接结束进程。

是否会上传源代码？

这取决于 Agent 的输入、模型上下文、工具参数以及工具返回内容。Trace 可能包含提示词、文件内容或命令输出，因此在生产环境使用前，应先确认数据采集范围，并避免把密码、Token、.env 内容等敏感信息发送到观测平台。

总结

Pi Agent 接入 Langfuse 的核心步骤只有三个：安装集成扩展、配置 Langfuse 密钥、运行任务并检查 Trace。

完成接入后，我们不仅能看到 Agent 最终回答了什么，还能了解它调用了哪些模型和工具、每个步骤花费了多长时间，以及问题具体发生在哪里。这对于调试复杂 Agent、控制模型成本和优化执行效果都非常有帮助。

参考资料

• Langfuse：Pi Agent 官方集成教程
• Langfuse 官方文档