# Agent开发应知应会：Langfuse 的两种使用方式

> 通过 Text-to-SQL Agent 项目实战，讲解 Langfuse 的自动 Callback 集成与手动 Span 追踪两种方式

- 原文链接: https://laojin.blog/repost/20260211_langfuse_usage
- 作者: zaizaizhao（老金转载）
- 原始出处: https://juejin.cn/post/7605135197166272562
- 发布日期: 2026-02-11
- 标签: Langfuse, 可观测性, AI Agent, 转载

---

[原文链接](https://juejin.cn/post/7605135197166272562)

这篇文章基于作者开发的 **Text-to-SQL Agent 项目**，分享了如何通过 **Langfuse** 解决 LLM 应用开发中的"黑盒"问题（如内部调用链路不清晰、Token 消耗不明等）。

---

## 什么是 Langfuse？

Langfuse 是一个 LLM 应用的可观测性平台，帮助开发者追踪和调试 Agent 的执行过程。

## 两种集成方式

### 1. 自动 Callback 集成（推荐入门）

**原理**：利用 LangChain/LangGraph 框架内置的回调机制，通过 `CallbackHandler` 自动捕获 LLM 调用、工具调用及链路执行过程。

**优点**：
- 零侵入、配置简单
- 自动记录输入输出、Token 用量、延迟等

**局限**：
- 仅能追踪框架内部的逻辑
- 对于框架外的自定义 Python 代码（如数据库查询）不可见
- 对 Trace 结构的控制力较弱

### 2. 手动 Span 追踪（适合进阶）

**原理**：直接使用 Langfuse SDK，通过装饰器或上下文管理器手动创建 `Span`，以记录业务层面的关键信息。

**用途**：
- 在细粒度追踪之上添加"业务汇总层"
- 直接记录最终生成的 SQL、验证结果及迭代轮次
- 便于在 Dashboard 中快速查看执行结果

---

## 最佳实践

文章建议在实际项目中**结合使用**这两种方式：

- **Callback**：自动捕获技术细节
- **手动 Span**：附加业务语义信息

从而实现既有深度又有概览的完整可观测性。

---

> 详细代码示例请阅读[原文](https://juejin.cn/post/7605135197166272562)