名称：langsmith-fetch 描述：通过从 LangSmith Studio 抓取执行轨迹来调试 LangChain 和 LangGraph 智能体。用于调试智能体行为、调查错误、分析工具调用、检查内存操作或审查智能体性能时使用。自动抓取最近的轨迹并分析执行模式。需要安装 langsmith-fetch CLI。

LangSmith 抓取 - 智能体调试技能

通过直接从 LangSmith Studio 抓取执行轨迹，在终端中调试 LangChain 和 LangGraph 智能体。

何时使用此技能

用户提及以下情况时自动激活：

🐛 “调试我的智能体”或“出了什么问题？”
🔍 “显示最近的轨迹”或“发生了什么？”
❌ “检查错误”或“为什么失败了？”
💾 “分析内存操作”或“检查 LTM”
📊 “审查智能体性能”或“检查令牌使用”
🔧 “调用了哪些工具？”或“显示执行流程”

前提条件

1. 安装 langsmith-fetch

pip install langsmith-fetch

2. 设置环境变量

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 分钟内找到 3 个轨迹：

轨迹 1：✅ 成功
- 智能体：memento
- 工具：recall_memories, create_entities
- 时长：2.3s
- 令牌：1,245

轨迹 2：❌ 错误
- 智能体：cypher
- 错误：“Neo4j 连接超时”
- 时长：15.1s
- 失败位置：search_nodes 工具

轨迹 3：✅ 成功
- 智能体：memento
- 工具：store_memory
- 时长：1.8s
- 令牌：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="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. 文档化发现

当发现错误时：

导出有问题的轨迹
保存到 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