id: “cb806b75-172f-5948-8588-661d3e8c7718” name: langsmith-fetch description: 通过从LangSmith Studio获取执行轨迹来调试LangChain和LangGraph代理。用于调试代理行为、调查错误、分析工具调用、检查内存操作或检查代理性能时使用。自动获取最近的轨迹并分析执行模式。需要安装langsmith-fetch CLI。
LangSmith 获取 - 代理调试技能
通过从LangSmith Studio直接获取执行轨迹来调试LangChain和LangGraph代理，在终端中进行。
何时使用此技能
当用户提到以下内容时自动激活：
- 🐛 “调试我的代理” 或 “出了什么问题？”
- 🔍 “显示最近的轨迹” 或 “发生了什么？”
- ❌ “检查错误” 或 “为什么会失败？”
- 💾 “分析内存操作” 或 “检查长时记忆”
- 📊 “回顾代理性能” 或 “检查令牌使用”
- 🔧 “调用了哪些工具？” 或 “显示执行流程”
前提条件
1. 安装 langsmith-fetch
pip install langsmith-fetch
2. 设置环境变量
export LANGSMITH_API_KEY="您的langsmith_api_key"
export LANGSMITH_PROJECT="您的项目名称"
验证设置：
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT
核心工作流程
工作流程 1: 快速调试最近活动
当用户问： “刚刚发生了什么？” 或 “调试我的代理”
执行：
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty
分析并报告：
- ✅ 找到的轨迹数量
- ⚠️ 任何错误或失败
- 🛠️ 调用的工具
- ⏱️ 执行时间
- 💰 令牌使用
响应格式示例：
在过去5分钟内找到3个轨迹：
轨迹 1: ✅ 成功
- 代理: memento
- 工具: recall_memories, create_entities
- 持续时间: 2.3秒
- 令牌: 1,245
轨迹 2: ❌ 错误
- 代理: cypher
- 错误: "Neo4j连接超时"
- 持续时间: 15.1秒
- 失败于: search_nodes工具
轨迹 3: ✅ 成功
- 代理: memento
- 工具: store_memory
- 持续时间: 1.8秒
- 令牌: 892
💡 发现的问题: 轨迹2因Neo4j超时而失败。建议检查数据库连接。
工作流程 2: 深入分析特定轨迹
当用户提供： 轨迹ID或说"调查那个错误"
执行：
langsmith-fetch trace <trace-id> --format json
分析JSON并报告：
- 🎯 代理试图做什么
- 🛠️ 调用了哪些工具（按顺序）
- ✅ 工具结果（成功/失败）
- ❌ 错误消息（如果有）
- 💡 根本原因分析
- 🔧 建议的修复
响应格式示例：
深入分析 - 轨迹 abc123
目标: 用户问 "在Neo4j中查找所有项目"
执行流程:
1. ✅ search_nodes(query: "projects")
→ 找到24个节点
2. ❌ get_node_details(node_id: "proj_123")
→ 错误: "未找到节点"
→ 这是失败点
3. ⏹️ 执行停止
根本原因:
search_nodes工具返回的节点ID在数据库中不再存在，
可能由于最近删除。
建议修复:
1. 在get_node_details工具中添加错误处理
2. 在搜索结果中过滤已删除的节点
3. 更新缓存失效策略
令牌使用: 1,842 令牌 ($0.0276)
执行时间: 8.7 秒
工作流程 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
报告：
✅ 会话成功导出！
位置: langsmith-debug/session-20251224-143022/
- 轨迹: 42 文件
- 线程: 8 文件
您现在可以:
1. 查看单个轨迹文件
2. 与团队分享文件夹
3. 使用外部工具分析
4. 归档以供将来参考
会话大小: 2.3 MB
工作流程 4: 错误检测
当用户问： “显示错误” 或 “什么失败了？”
执行：
# 获取最近轨迹
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json
# 搜索错误
grep -i "error\|failed\|exception" recent-traces.json
分析并报告：
- 📊 总错误数量
- ❌ 错误类型和频率
- 🕐 错误发生时间
- 🎯 哪个代理/工具失败
- 💡 常见模式
响应格式示例：
错误分析 - 过去30分钟
总轨迹: 50
失败轨迹: 7 (14%失败率)
错误细分:
1. Neo4j连接超时 (4次出现)
- 代理: cypher
- 工具: search_nodes
- 首次发生: 14:32
- 末次发生: 14:45
- 模式: 在高峰负载时发生
2. 内存存储失败 (2次出现)
- 代理: memento
- 工具: store_memory
- 错误: "Pinecone速率限制超限"
- 发生: 14:38, 14:41
3. 工具未找到 (1次出现)
- 代理: sqlcrm
- 尝试工具: "export_report"（不存在）
- 发生: 14:35
💡 推荐:
1. 为Neo4j超时添加重试逻辑
2. 为Pinecone实施速率限制
3. 修复sqlcrm工具配置
常见用例
用例 1: “代理不响应”
用户说： “我的代理什么都不做”
步骤：
-
检查是否存在轨迹:
langsmith-fetch traces --last-n-minutes 5 --limit 5 -
如果未找到轨迹：
- 追踪可能已禁用
- 检查: 环境中的
LANGCHAIN_TRACING_V2=true - 检查: 是否设置了
LANGCHAIN_API_KEY - 验证代理是否实际运行
-
如果找到轨迹：
- 查看错误
- 检查执行时间（是否挂起？）
- 验证工具调用是否完成
用例 2: “调用了错误工具”
用户说： “为什么调用了错误工具？”
步骤：
- 获取特定轨迹
- 查看执行时的可用工具
- 检查代理选择工具的原因
- 检查工具描述/指令
- 建议提示或工具配置改进
用例 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
故障排除
“未找到符合标准的轨迹”
可能原因：
- 在时间范围内无代理活动
- 追踪已禁用
- 错误的项目名称
- 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="正确的项目名称"
# 或永久配置
langsmith-fetch config set project "您的项目名称"
环境变量未持久化
解决方案：
# 添加到shell配置文件（~/.bashrc 或 ~/.zshrc）
echo 'export LANGSMITH_API_KEY="您的密钥"' >> ~/.bashrc
echo 'export LANGSMITH_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. 记录发现
找到错误时:
- 导出有问题的轨迹
- 保存到
error-cases/文件夹 - 在README中记录出错点
- 与团队分享轨迹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 CLI: https://github.com/langchain-ai/langsmith-fetch
- LangSmith Studio: https://smith.langchain.com/
- LangChain 文档: https://docs.langchain.com/
- 此技能仓库: https://github.com/OthmanAdi/langsmith-fetch-skill
给 Claude 的笔记
- 运行命令前始终检查是否安装了
langsmith-fetch - 验证环境变量是否设置
- 使用
--format pretty输出人类可读格式 - 使用
--format json当需要解析和分析数据时 - 导出会话时，创建有组织的文件夹结构
- 始终提供清晰分析和可操作见解
- 如果命令失败，帮助排除配置问题
版本: 0.1.0 作者: Ahmad Othman Ammar Adi 许可证: MIT 仓库: https://github.com/OthmanAdi/langsmith-fetch-skill