langsmith-fetch技能：调试LangChain和LangGraph代理的必备工具

langsmith-fetch技能：调试LangChain和LangGraph代理的必备工具

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

LangSmith Fetch是一款强大的命令行工具，专为调试LangChain和LangGraph代理而设计。它允许开发者直接从LangSmith Studio获取执行跟踪，轻松分析代理行为、排查错误、检查工具调用和内存操作，以及评估性能问题。无论是新手还是经验丰富的开发者，这款工具都能显著提升你的工作流自动化调试效率。

图：LangSmith Fetch技能帮助开发者轻松调试LangChain和LangGraph代理

快速开始：安装与配置

1. 安装langsmith-fetch

要开始使用这个强大的调试工具，首先需要通过pip安装：

pip install langsmith-fetch

2. 设置环境变量

安装完成后，需要配置环境变量以连接到LangSmith Studio：

export LANGSMITH_API_KEY="your_langsmith_api_key" export LANGSMITH_PROJECT="your_project_name"

验证设置是否成功：

echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT

核心工作流程：从简单到高级

工作流程1：快速调试最近活动

当你需要快速了解代理最近的执行情况时，只需运行：

langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

这个命令会显示过去5分钟内的5条跟踪记录，包括：

• ✅ 跟踪数量和状态
• ⚠️ 错误或失败情况
• 🛠️ 调用的工具
• ⏱️ 执行时间
• 💰 令牌使用情况

工作流程2：深入分析特定跟踪

当你需要详细分析某个特定跟踪时，可以使用跟踪ID进行深入调试：

langsmith-fetch trace <trace-id> --format json

这将提供完整的JSON格式跟踪数据，帮助你了解：

• 🎯 代理的目标
• 🛠️ 工具调用顺序
• ✅ 工具结果
• ❌ 错误信息
• 💡 根本原因分析
• 🔧 建议的修复方案

工作流程3：导出调试会话

当你需要保存当前调试会话供日后分析或与团队共享时，可以导出跟踪和线程：

# 创建带时间戳的会话文件夹 SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)" mkdir -p "$SESSION_DIR" # 导出跟踪 langsmith-fetch traces "$SESSION_DIR/traces" --last-n-minutes 30 --limit 50 --include-metadata # 导出线程（对话） langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

导出的会话将包含所有必要的调试信息，方便你进行深入分析或与团队协作解决问题。

工作流程4：错误检测与分析

当你需要快速定位和分析错误时，可以使用以下命令：

# 获取最近的跟踪 langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json # 搜索错误 grep -i "error\|failed\|exception" recent-traces.json

这将帮助你识别错误类型、频率、发生时间以及涉及的代理/工具，从而快速定位问题根源。

常见用例：解决实际问题

用例1："代理没有响应"

当你的代理没有按预期响应时，首先检查是否有跟踪记录：

langsmith-fetch traces --last-n-minutes 5 --limit 5

如果没有找到跟踪，可能是因为：

• 跟踪功能未启用（检查LANGCHAIN_TRACING_V2=true）
• API密钥未正确设置
• 代理实际上没有运行

如果找到跟踪，则需要检查错误、执行时间和工具调用完成情况。

用例2："调用了错误的工具"

当代理调用了错误的工具时，你需要：

1. 获取特定跟踪
2. 查看执行时可用的工具
3. 检查代理选择工具的推理过程
4. 检查工具描述和指令
5. 改进提示或工具配置

用例3："内存不工作"

当代理似乎不记得之前的对话时，可以搜索内存操作：

langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory\|recall\|store"

检查是否调用了内存工具、召回是否返回结果、记忆是否被正确存储，以及检索到的记忆是否被使用。

用例4："性能问题"

当代理运行缓慢时，可以导出带有元数据的跟踪进行性能分析：

langsmith-fetch traces ./perf-analysis --last-n-minutes 30 --limit 50 --include-metadata

分析执行时间、工具调用延迟、令牌使用情况、迭代次数和最慢的操作，以识别瓶颈并提出优化建议。

输出格式指南：选择适合你的格式

漂亮格式（默认）

langsmith-fetch traces --limit 5 --format pretty

用途：快速视觉检查，向用户展示结果

JSON格式

langsmith-fetch traces --limit 5 --format json

用途：详细分析，语法高亮显示

原始格式

langsmith-fetch traces --limit 5 --format raw

用途：管道传输到其他命令，自动化处理

高级功能：提升调试效率

基于时间的过滤

# 特定时间戳之后 langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20 # 最近N分钟（最常用） langsmith-fetch traces --last-n-minutes 60 --limit 100

包含元数据

# 获取额外上下文 langsmith-fetch traces --limit 10 --include-metadata # 元数据包括：代理类型、模型、标签、环境

并发获取（更快）

# 加速大型导出 langsmith-fetch traces ./output --limit 100 --concurrent 10

故障排除：解决常见问题

"未找到匹配条件的跟踪"

可能原因：

1. 时间范围内没有代理活动
2. 跟踪功能被禁用
3. 项目名称错误
4. API密钥问题

解决方案：

# 1. 尝试更长的时间范围 langsmith-fetch traces --last-n-minutes 1440 --limit 50 # 2. 检查环境 echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT # 3. 尝试获取线程 langsmith-fetch threads --limit 10 # 4. 验证代码中是否启用了跟踪 # 检查：LANGCHAIN_TRACING_V2=true

"项目未找到"

解决方案：

# 查看当前配置 langsmith-fetch config show # 设置正确的项目 export LANGSMITH_PROJECT="correct-project-name" # 或永久配置 langsmith-fetch config set project "your-project-name"

环境变量不持久

解决方案：

# 添加到shell配置文件（~/.bashrc或~/.zshrc） echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc # 重新加载shell配置 source ~/.bashrc

最佳实践：提升调试体验

1. 定期健康检查

# 更改后快速检查 langsmith-fetch traces --last-n-minutes 5 --limit 5

2. 有组织的存储

langsmith-debug/ ├── sessions/ │ ├── 2025-12-24/ │ └── 2025-12-25/ ├── error-cases/ └── performance-tests/

3. 记录发现

发现错误时：

1. 导出有问题的跟踪
2. 保存到error-cases/文件夹
3. 在README中记录问题
4. 与团队分享跟踪ID

4. 与开发集成

# 提交代码前 langsmith-fetch traces --last-n-minutes 10 --limit 5 # 如果发现错误 langsmith-fetch trace <error-id> --format json > pre-commit-error.json

快速参考：常用命令

# 最常用命令 # 快速调试 langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty # 特定跟踪 langsmith-fetch trace <trace-id> --format pretty # 导出会话 langsmith-fetch traces ./debug-session --last-n-minutes 30 --limit 50 # 查找错误 langsmith-fetch traces --last-n-minutes 30 --limit 50 --format raw | grep -i error # 包含元数据 langsmith-fetch traces --limit 10 --include-metadata

通过掌握langsmith-fetch技能，你可以轻松调试LangChain和LangGraph代理，快速定位问题并优化性能。无论你是在开发新的代理还是维护现有系统，这款工具都将成为你工作流中不可或缺的一部分。开始使用langsmith-fetch，提升你的自动化调试效率吧！

要开始使用这个强大的技能，只需克隆仓库：

git clone https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

然后按照上述指南安装和配置langsmith-fetch，开始你的高效调试之旅！

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills