langsmith-fetch

LangSmith Fetch - Agent 调试技能

在终端中直接从 LangSmith Studio 获取执行跟踪，调试 LangChain 和 LangGraph Agent。

何时使用此技能

当用户提到以下内容时自动启用：

• 🐛 “调试我的 Agent”或“出了什么问题？”
• 🔍 “显示最近的跟踪记录”或“发生了什么？”
• ❌ “检查错误”或“为什么失败了？”
• 💾 “分析记忆操作”或“检查 LTM”
• 📊 “查看 Agent 性能”或“检查 token 用量”
• 🔧 “调用了哪些工具？”或“显示执行流程”

前提条件

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：快速调试近期活动

用户询问时：“刚才发生了什么？”或“调试我的 Agent”

执行：

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

分析并报告：

1. ✅ 找到的跟踪记录数量
2. ⚠️ 是否有错误或失败
3. 🛠️ 调用过的工具
4. ⏱️ 执行时间
5. 💰 Token 用量

示例回复格式：

Found 3 traces in the last 5 minutes:

Trace 1: ✅ Success
- Agent: memento
- Tools: recall_memories, create_entities
- Duration: 2.3s
- Tokens: 1,245

Trace 2: ❌ Error
- Agent: cypher
- Error: "Neo4j connection timeout"
- Duration: 15.1s
- Failed at: search_nodes tool

Trace 3: ✅ Success
- Agent: memento
- Tools: store_memory
- Duration: 1.8s
- Tokens: 892

💡 Issue found: Trace 2 failed due to Neo4j timeout. Recommend checking database connection.

---

工作流 2：深入调查特定跟踪记录

**用户提供以下内容时：**跟踪 ID，或说“调查那个错误”

执行：

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

分析 JSON 并报告：

1. 🎯 Agent 试图完成什么
2. 🛠️ 调用了哪些工具（按顺序）
3. ✅ 工具结果（成功/失败）
4. ❌ 错误消息（如有）
5. 💡 根本原因分析
6. 🔧 建议的修复方案

示例回复格式：

Deep Dive Analysis - Trace abc123

Goal: User asked "Find all projects in Neo4j"

Execution Flow:
1. ✅ search_nodes(query: "projects")
   → Found 24 nodes

2. ❌ get_node_details(node_id: "proj_123")
   → Error: "Node not found"
   → This is the failure point

3. ⏹️ Execution stopped

Root Cause:
The search_nodes tool returned node IDs that no longer exist in the database,
possibly due to recent deletions.

Suggested Fix:
1. Add error handling in get_node_details tool
2. Filter deleted nodes in search results
3. Update cache invalidation strategy

Token Usage: 1,842 tokens ($0.0276)
Execution Time: 8.7 seconds

---

工作流 3：导出调试会话

用户说以下内容时：“保存此会话”或“导出跟踪记录”

执行：

# Create session folder with timestamp
SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SESSION_DIR"

# Export traces
langsmith-fetch traces "$SESSION_DIR/traces" --last-n-minutes 30 --limit 50 --include-metadata

# Export threads (conversations)
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

报告：

✅ Session exported successfully!

Location: langsmith-debug/session-20251224-143022/
- Traces: 42 files
- Threads: 8 files

You can now:
1. Review individual trace files
2. Share folder with team
3. Analyze with external tools
4. Archive for future reference

Session size: 2.3 MB

---

工作流 4：错误检测

用户询问时：“显示错误”或“哪里出问题了？”

执行：

# Fetch recent traces
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json

# Search for errors
grep -i "error\|failed\|exception" recent-traces.json

分析并报告：

1. 📊 找到的错误总数
2. ❌ 错误类型及频率
3. 🕐 错误发生时间
4. 🎯 失败的 Agent/工具
5. 💡 常见模式

示例回复格式：

Error Analysis - Last 30 Minutes

Total Traces: 50
Failed Traces: 7 (14% failure rate)

Error Breakdown:
1. Neo4j Connection Timeout (4 occurrences)
   - Agent: cypher
   - Tool: search_nodes
   - First occurred: 14:32
   - Last occurred: 14:45
   - Pattern: Happens during peak load

2. Memory Store Failed (2 occurrences)
   - Agent: memento
   - Tool: store_memory
   - Error: "Pinecone rate limit exceeded"
   - Occurred: 14:38, 14:41

3. Tool Not Found (1 occurrence)
   - Agent: sqlcrm
   - Attempted tool: "export_report" (doesn't exist)
   - Occurred: 14:35

💡 Recommendations:
1. Add retry logic for Neo4j timeouts
2. Implement rate limiting for Pinecone
3. Fix sqlcrm tool configuration

---

常见用例

用例 1：“Agent 没有响应”

用户说：“我的 Agent 什么也没做”

步骤：

1. 检查是否存在跟踪记录：

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

2. 如果没有找到跟踪记录：

   • 跟踪功能可能已禁用
   • 检查：环境中是否设置了 LANGCHAIN_TRACING_V2=true
   • 检查：是否已设置 LANGCHAIN_API_KEY
   • 确认 Agent 确实已运行

3. 如果找到了跟踪记录：

   • 检查是否有错误
   • 检查执行时间（是否卡住？）
   • 确认工具调用已完成

---

用例 2：“调用了错误的工具”

用户说：“为什么它用了错误的工具？”

步骤：

1. 获取特定跟踪记录
2. 查看执行时可用的工具
3. 检查 Agent 选择工具的推理过程
4. 检查工具描述/说明
5. 建议改进提示词或工具配置

---

用例 3：“记忆无法正常工作”

用户说：“Agent 记不住东西”

步骤：

1. 搜索记忆操作：

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

2. 检查：

   • 是否调用了记忆工具？
   • 检索是否返回结果？
   • 是否实际存储了记忆？
   • 是否使用了检索到的记忆？

---

用例 4：“性能问题”

用户说：“Agent 太慢了”

步骤：

1. 导出并包含元数据：

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

2. 分析：

   • 每条跟踪记录的执行时间
   • 工具调用延迟
   • Token 用量（上下文大小）
   • 迭代次数
   • 最慢的操作

3. 找出瓶颈并提出优化建议

---

输出格式指南

美化格式（默认）

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

**适用于：**快速目视检查、向用户展示

JSON 格式

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

**适用于：**详细分析、语法高亮查看

原始格式

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

**适用于：**通过管道传递给其他命令、自动化

---

高级功能

基于时间筛选

# After specific timestamp
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# Last N minutes (most common)
langsmith-fetch traces --last-n-minutes 60 --limit 100

包含元数据

# Get extra context
langsmith-fetch traces --limit 10 --include-metadata

# Metadata includes: agent type, model, tags, environment

并发获取（更快）

# Speed up large exports
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

故障排除

“没有找到符合条件的跟踪记录”

可能原因：

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

解决方案：

# 1. Try longer timeframe
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. Check environment
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. Try fetching threads instead
langsmith-fetch threads --limit 10

# 4. Verify tracing is enabled in your code
# Check for: LANGCHAIN_TRACING_V2=true

“找不到项目”

解决方案：

# View current config
langsmith-fetch config show

# Set correct project
export LANGSMITH_PROJECT="correct-project-name"

# Or configure permanently
langsmith-fetch config set project "your-project-name"

环境变量未持久化

解决方案：

# Add to shell config file (~/.bashrc or ~/.zshrc)
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# Reload shell config
source ~/.bashrc

---

最佳实践

1. 定期健康检查

# Quick check after making changes
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. 与开发集成

# Before committing code
langsmith-fetch traces --last-n-minutes 10 --limit 5

# If errors found
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---

快速参考

# Most common commands

# Quick debug
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# Specific trace
langsmith-fetch trace <trace-id> --format pretty

# Export session
langsmith-fetch traces ./debug-session --last-n-minutes 30 --limit 50

# Find errors
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format raw | grep -i error

# With metadata
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