langsmith-fetch

LangSmith Fetch - LangChain Agent 调试工具

技能概述

langsmith-fetch 是一个命令行工具，帮助开发者在终端中直接获取和分析 LangChain 与 LangGraph Agent 的执行追踪，无需切换到 LangSmith Studio 网页界面。

适用场景

1. Agent 错误快速诊断

当 Agent 执行失败或调用错误工具时，使用 langsmith-fetch traces --last-n-minutes 5 快速获取最近的执行记录，查看失败原因和错误堆栈，无需手动打开浏览器登录 LangSmith。

2. Agent 性能瓶颈分析

当 Agent 响应缓慢或 token 消耗异常时，通过执行追踪分析各工具调用耗时、迭代次数和上下文大小，定位性能瓶颈，支持 --include-metadata 获取详细性能指标。

3. 调试会话导出与分享

当需要团队协作或保存调试记录时，将追踪数据导出到本地文件夹，便于离线分析、代码审查或与团队成员共享，支持 JSON、Pretty 和 Raw 三种格式。

核心功能

1. 实时追踪获取

自动从 LangSmith 获取最近的执行追踪，支持时间范围过滤（如 --last-n-minutes 30）和数量限制，可快速定位问题发生的具体时间点和执行上下文，帮助开发者复现和修复 Bug。

2. 多维度执行分析

分析 Agent 的工具调用链路、内存操作记录、错误堆栈信息和 token 使用统计，支持 Pretty、JSON、Raw 三种输出格式，适配不同分析场景（快速浏览、详细审查、脚本自动化）。

3. 调试会话管理

支持将追踪数据导出到本地文件系统，创建带时间戳的调试会话文件夹，便于归档历史问题、分享给团队成员或使用外部工具进行深度分析。

常见问题

langsmith-fetch 需要什么环境配置？

需要设置 LANGSMITH_API_KEY 和 LANGSMITH_PROJECT 两个环境变量。先通过 pip 安装 langsmith-fetch，然后在 ~/.bashrc 或 ~/.zshrc 中添加环境变量，执行 source 命令使其生效。

找不到追踪记录怎么办？

首先确认 LANGCHAIN_TRACING_V2=true 已启用，检查 API Key 和项目名称是否正确。如果最近几分钟无记录，尝试扩大时间范围到 --last-n-minutes 1440（24 小时），或使用 langsmith-fetch threads 检查会话记录。

如何分析 Agent 的工具调用错误？

使用 langsmith-fetch trace <trace-id> --format pretty 获取特定追踪的详细信息，查看工具调用的顺序和返回结果，定位失败的工具及其错误消息，结合 Root Cause 分析找出问题根源。