langsmith-fetch

LangSmith Fetch - 智能体调试技能

通过直接在终端中从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.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="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

你可能还喜欢

planning-with-files-es

25Kagent-workflows

Sistema de planificación basado en archivos estilo Manus para organizar y rastrear el progreso de tareas complejas. Crea task_plan.md, findings.md y progress.md. Cuando el usuario solicita planificación, desglose u organización de proyectos multipaso, tareas de investigación o trabajos que requieren más de 5 llamadas a herramientas. Soporta recuperación automática de sesión tras /clear. Palabras clave: planificación de tareas, planificación de proyecto, crear plan de trabajo, analizar tareas, organizar proyecto, seguimiento de progreso, planificación multipaso, ayúdame a planificar, desglosar proyecto

othmanadi

获取

hv-analysis

19Kagent-workflows

横纵分析法（Horizontal-Vertical Analysis）深度研究Skill。由数字生命卡兹克提出，融合了索绪尔的历时-共时分析、社会科学的纵向-横截面研究设计、商学院案例研究法与竞争战略分析的核心思想。当用户想要系统性研究一个产品、公司、概念、技术或人物时使用。核心是双轴分析：纵轴追踪从诞生到当下的完整生命历程（以叙事故事呈现），横轴在当下时间截面上与竞品/同类进行系统性横向对比，最后交叉两条轴产出独到洞察。最终产出一份排版精美的PDF研究报告。触发词包括但不限于：横纵分析、研究一下、帮我分析、深度研究、做个研究、调研一下、竞品分析、帮我看看这个东西怎么样、这个产品/公司/概念是怎么回事、帮我摸清楚、帮我搞懂、帮我做个deep research。即使用户只是说"帮我了解一下XX"或"XX是什么来头"，只要上下文暗示需要系统性的深度研究（而非简单的概念解释），都应该触发。也适用于用户丢来一个产品名、公司名、技术名词说"帮我研究一下这个"的场景。不要用于简单的名词解释（用户只是问"XX是什么"）、不要用于公众号写作（那个用khazix-writer）、不要用于纯标题摘要生成（用wechat-title）。

kkkkhazix

获取

homelab-vlan-segmentation

238Kagent-workflows

Segmenting home networks into VLANs for IoT, guest, trusted, and server traffic using UniFi, pfSense/OPNsense, and MikroTik — including switch trunk config, firewall rules, and wireless SSID mapping.

affaan-m

获取

继续探索

浏览 agent-workflows 热门 Skills 最近更新

langsmith-fetch

相关 Skills

LangSmith Fetch - 智能体调试技能

何时使用此技能

前提条件

1. 安装langsmith-fetch

2. 设置环境变量

核心工作流

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

工作流2：深入分析特定轨迹

工作流3：导出调试会话

工作流4：错误检测

常见用例

用例1："智能体无响应"

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

用例3："记忆不起作用"

用例4："性能问题"

输出格式指南

美观格式（默认）

JSON格式

原始格式

高级功能

基于时间的过滤

包含元数据

并发获取（更快）

故障排除

"未找到匹配条件的轨迹"

"项目未找到"

环境变量不持久

最佳实践

1. 定期健康检查

2. 组织存储

3. 记录发现

4. 与开发集成

快速参考

资源

给Claude的备注

你可能还喜欢

planning-with-files-es

hv-analysis

homelab-vlan-segmentation

继续探索