Back to Details

langsmith-fetch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LangSmith Fetch - Agent Debugging Skill

LangSmith Fetch - Agent调试技能

Debug LangChain and LangGraph agents by fetching execution traces directly from LangSmith Studio in your terminal.
通过在终端中直接从LangSmith Studio获取执行轨迹，调试LangChain和LangGraph Agent。

When to Use This Skill

何时使用该技能

Automatically activate when user mentions:
  • 🐛 "Debug my agent" or "What went wrong?"
  • 🔍 "Show me recent traces" or "What happened?"
  • ❌ "Check for errors" or "Why did it fail?"
  • 💾 "Analyze memory operations" or "Check LTM"
  • 📊 "Review agent performance" or "Check token usage"
  • 🔧 "What tools were called?" or "Show execution flow"
当用户提及以下内容时自动激活：
  • 🐛「调试我的Agent」或「哪里出问题了？」
  • 🔍「显示我近期的轨迹」或「发生了什么？」
  • ❌「检查错误」或「为什么失败了？」
  • 💾「分析内存操作」或「检查LTM」
  • 📊「评估Agent性能」或「检查令牌使用量」
  • 🔧「调用了哪些工具？」或「显示执行流程」

Prerequisites

前提条件

1. Install langsmith-fetch

1. 安装langsmith-fetch

bash
pip install langsmith-fetch
bash
pip install langsmith-fetch

2. Set Environment Variables

2. 设置环境变量

bash
export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"
Verify setup:
bash
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT
bash
export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"
验证设置：
bash
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

Core Workflows

核心工作流

Workflow 1: Quick Debug Recent Activity

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

When user asks: "What just happened?" or "Debug my agent"
Execute:
bash
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty
Analyze and report:
  1. ✅ Number of traces found
  2. ⚠️ Any errors or failures
  3. 🛠️ Tools that were called
  4. ⏱️ Execution times
  5. 💰 Token usage
Example response format:
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.
当用户询问：「刚才发生了什么？」或「调试我的Agent」
执行命令：
bash
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty
分析并报告：
  1. ✅ 找到的轨迹数量
  2. ⚠️ 任何错误或失败情况
  3. 🛠️ 被调用的工具
  4. ⏱️ 执行时间
  5. 💰 令牌使用量
示例响应格式：
过去5分钟内找到3条轨迹：

轨迹1: ✅ 成功
- Agent: memento
- 工具: recall_memories, create_entities
- 时长: 2.3秒
- 令牌数: 1,245

轨迹2: ❌ 错误
- Agent: cypher
- 错误: "Neo4j连接超时"
- 时长: 15.1秒
- 失败点: search_nodes工具

轨迹3: ✅ 成功
- Agent: memento
- 工具: store_memory
- 时长: 1.8秒
- 令牌数: 892

💡 发现问题：轨迹2因Neo4j超时失败。建议检查数据库连接。

Workflow 2: Deep Dive Specific Trace

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

When user provides: Trace ID or says "investigate that error"
Execute:
bash
langsmith-fetch trace <trace-id> --format json
Analyze JSON and report:
  1. 🎯 What the agent was trying to do
  2. 🛠️ Which tools were called (in order)
  3. ✅ Tool results (success/failure)
  4. ❌ Error messages (if any)
  5. 💡 Root cause analysis
  6. 🔧 Suggested fix
Example response format:
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
**当用户提供：**轨迹ID或说「排查那个错误」
执行命令：
bash
langsmith-fetch trace <trace-id> --format json
分析JSON并报告：
  1. 🎯 Agent的执行目标
  2. 🛠️ 调用的工具（按顺序）
  3. ✅ 工具执行结果（成功/失败）
  4. ❌ 错误信息（如有）
  5. 💡 根本原因分析
  6. 🔧 建议修复方案
示例响应格式：
深度分析 - 轨迹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秒

Workflow 3: Export Debug Session

工作流3：导出调试会话

When user says: "Save this session" or "Export traces"
Execute:
bash
undefined
当用户说：「保存这个会话」或「导出轨迹」
执行命令：
bash
undefined

Create session folder with timestamp

创建带时间戳的会话文件夹

SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)" mkdir -p "$SESSION_DIR"
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
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

**Report:**
✅ 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

---
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

**报告：**
✅ 会话导出成功！
位置: langsmith-debug/session-20251224-143022/
  • 轨迹: 42个文件
  • 对话线程: 8个文件
你现在可以：
  1. 查看单个轨迹文件
  2. 与团队共享文件夹
  3. 使用外部工具进行分析
  4. 归档以供未来参考
会话大小: 2.3 MB

---

Workflow 4: Error Detection

工作流4：错误检测

When user asks: "Show me errors" or "What's failing?"
Execute:
bash
undefined
当用户询问：「显示错误」或「哪些功能失败了？」
执行命令：
bash
undefined

Fetch recent traces

获取近期轨迹

langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json
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

**Analyze and report:**
1. 📊 Total errors found
2. ❌ Error types and frequency
3. 🕐 When errors occurred
4. 🎯 Which agents/tools failed
5. 💡 Common patterns

**Example response format:**
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

---
grep -i "error|failed|exception" recent-traces.json

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

**示例响应格式：**
错误分析 - 过去30分钟
总轨迹数: 50 失败轨迹数: 7（失败率14%）
错误分类：
  1. Neo4j连接超时（4次）
    • Agent: cypher
    • 工具: search_nodes
    • 首次发生: 14:32
    • 末次发生: 14:45
    • 模式: 高峰负载时发生
  2. 内存存储失败（2次）
    • Agent: memento
    • 工具: store_memory
    • 错误: "Pinecone速率限制超出"
    • 发生时间: 14:38, 14:41
  3. 工具未找到（1次）
    • Agent: sqlcrm
    • 尝试调用的工具: "export_report"（不存在）
    • 发生时间: 14:35
💡 建议：
  1. 为Neo4j超时添加重试逻辑
  2. 为Pinecone实现速率限制
  3. 修复sqlcrm工具配置

---

Common Use Cases

常见使用场景

Use Case 1: "Agent Not Responding"

场景1：「Agent无响应」

User says: "My agent isn't doing anything"
Steps:
  1. Check if traces exist:
    bash
    langsmith-fetch traces --last-n-minutes 5 --limit 5
  2. If NO traces found:
    • Tracing might be disabled
    • Check: 
      LANGCHAIN_TRACING_V2=true
      in environment
    • Check: 
      LANGCHAIN_API_KEY
      is set
    • Verify agent actually ran
  3. If traces found:
    • Review for errors
    • Check execution time (hanging?)
    • Verify tool calls completed
用户说：「我的Agent没有任何反应」
步骤：
  1. 检查是否存在轨迹：
    bash
    langsmith-fetch traces --last-n-minutes 5 --limit 5
  2. 如果未找到轨迹：
    • 可能已禁用追踪
    • 检查环境变量：
      LANGCHAIN_TRACING_V2=true
    • 检查：
      LANGCHAIN_API_KEY
      是否已设置
    • 验证Agent是否实际运行
  3. 如果找到轨迹：
    • 检查是否有错误
    • 查看执行时间（是否挂起？）
    • 验证工具调用是否完成

Use Case 2: "Wrong Tool Called"

场景2：「调用了错误的工具」

User says: "Why did it use the wrong tool?"
Steps:
  1. Get the specific trace
  2. Review available tools at execution time
  3. Check agent's reasoning for tool selection
  4. Examine tool descriptions/instructions
  5. Suggest prompt or tool config improvements
用户说：「为什么它调用了错误的工具？」
步骤：
  1. 获取特定轨迹
  2. 查看执行时可用的工具
  3. 检查Agent选择工具的推理过程
  4. 检查工具描述/指令
  5. 建议优化提示词或工具配置

Use Case 3: "Memory Not Working"

场景3：「内存不工作」

User says: "Agent doesn't remember things"
Steps:
  1. Search for memory operations:
    bash
    langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory\|recall\|store"
  2. Check:
    • Were memory tools called?
    • Did recall return results?
    • Were memories actually stored?
    • Are retrieved memories being used?
用户说：「Agent不记得之前的内容」
步骤：
  1. 搜索内存操作：
    bash
    langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory\|recall\|store"
  2. 检查：
    • 是否调用了内存工具？
    • 回忆操作是否返回结果？
    • 记忆是否实际存储？
    • 检索到的记忆是否被使用？

Use Case 4: "Performance Issues"

场景4：「性能问题」

User says: "Agent is too slow"
Steps:
  1. Export with metadata:
    bash
    langsmith-fetch traces ./perf-analysis --last-n-minutes 30 --limit 50 --include-metadata
  2. Analyze:
    • Execution time per trace
    • Tool call latencies
    • Token usage (context size)
    • Number of iterations
    • Slowest operations
  3. Identify bottlenecks and suggest optimizations
用户说：「Agent太慢了」
步骤：
  1. 导出带元数据的轨迹：
    bash
    langsmith-fetch traces ./perf-analysis --last-n-minutes 30 --limit 50 --include-metadata
  2. 分析：
    • 每条轨迹的执行时间
    • 工具调用延迟
    • 令牌使用量（上下文大小）
    • 迭代次数
    • 最慢的操作
  3. 识别瓶颈并提出优化建议

Output Format Guide

输出格式指南

Pretty Format (Default)

美观格式（默认）

bash
langsmith-fetch traces --limit 5 --format pretty
Use for: Quick visual inspection, showing to users
bash
langsmith-fetch traces --limit 5 --format pretty
**适用场景：**快速可视化检查、展示给用户

JSON Format

JSON格式

bash
langsmith-fetch traces --limit 5 --format json
Use for: Detailed analysis, syntax-highlighted review
bash
langsmith-fetch traces --limit 5 --format json
**适用场景：**详细分析、语法高亮查看

Raw Format

原始格式

bash
langsmith-fetch traces --limit 5 --format raw
Use for: Piping to other commands, automation
bash
langsmith-fetch traces --limit 5 --format raw
**适用场景：**管道传输到其他命令、自动化

Advanced Features

高级功能

Time-Based Filtering

基于时间的过滤

bash
undefined
bash
undefined

After specific timestamp

特定时间戳之后的轨迹

langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

Last N minutes (most common)

过去N分钟内的轨迹（最常用）

langsmith-fetch traces --last-n-minutes 60 --limit 100
undefined
langsmith-fetch traces --last-n-minutes 60 --limit 100
undefined

Include Metadata

包含元数据

bash
undefined
bash
undefined

Get extra context

获取额外上下文

langsmith-fetch traces --limit 10 --include-metadata
langsmith-fetch traces --limit 10 --include-metadata

Metadata includes: agent type, model, tags, environment

元数据包括：Agent类型、模型、标签、环境

undefined
undefined

Concurrent Fetching (Faster)

并发获取（更快）

bash
undefined
bash
undefined

Speed up large exports

加速大量导出

langsmith-fetch traces ./output --limit 100 --concurrent 10

---
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

Troubleshooting

故障排除

"No traces found matching criteria"

「未找到匹配条件的轨迹」

Possible causes:
  1. No agent activity in the timeframe
  2. Tracing is disabled
  3. Wrong project name
  4. API key issues
Solutions:
bash
undefined
可能原因：
  1. 该时间段内无Agent活动
  2. 已禁用追踪
  3. 项目名称错误
  4. API密钥问题
解决方案：
bash
undefined

1. Try longer timeframe

1. 尝试更长的时间范围

langsmith-fetch traces --last-n-minutes 1440 --limit 50
langsmith-fetch traces --last-n-minutes 1440 --limit 50

2. Check environment

2. 检查环境变量

echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT
echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT

3. Try fetching threads instead

3. 尝试获取对话线程

langsmith-fetch threads --limit 10
langsmith-fetch threads --limit 10

4. Verify tracing is enabled in your code

4. 验证代码中是否启用了追踪

Check for: LANGCHAIN_TRACING_V2=true

检查是否设置：LANGCHAIN_TRACING_V2=true

undefined
undefined

"Project not found"

「项目未找到」

Solution:
bash
undefined
解决方案：
bash
undefined

View current config

查看当前配置

langsmith-fetch config show
langsmith-fetch config show

Set correct project

设置正确的项目

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

Or configure permanently

或永久配置

langsmith-fetch config set project "your-project-name"
undefined
langsmith-fetch config set project "your-project-name"
undefined

Environment variables not persisting

环境变量不持久

Solution:
bash
undefined
解决方案：
bash
undefined

Add to shell config file (~/.bashrc or ~/.zshrc)

添加到shell配置文件（/.bashrc或/.zshrc）

echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

Reload shell config

重新加载shell配置

source ~/.bashrc

---
source ~/.bashrc

---

Best Practices

最佳实践

1. Regular Health Checks

1. 定期健康检查

bash
undefined
bash
undefined

Quick check after making changes

更改代码后快速检查

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

2. Organized Storage

2. 有序存储

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

3. Document Findings

3. 记录发现

When you find bugs:
  1. Export the problematic trace
  2. Save to 
    error-cases/
    folder
  3. Note what went wrong in a README
  4. Share trace ID with team
当发现bug时：
  1. 导出有问题的轨迹
  2. 保存到
    error-cases/
    文件夹
  3. 在README中记录问题
  4. 与团队共享轨迹ID

4. Integration with Development

4. 与开发流程集成

bash
undefined
bash
undefined

Before committing code

提交代码前

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

If errors found

如果发现错误

langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---

Quick Reference

资源

bash
undefined

Most common commands

给Claude的提示

Quick debug

—
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty
  • 运行命令前始终检查是否已安装
    langsmith-fetch
  • 验证环境变量是否已设置
  • 使用
    --format pretty
    输出人类可读的内容
  • 需要解析和分析数据时使用
    --format json
  • 导出会话时创建有序的文件夹结构
  • 始终提供清晰的分析和可操作的建议
  • 如果命令失败，帮助排查配置问题
版本: 0.1.0 作者: Ahmad Othman Ammar Adi 许可证: MIT 仓库: https://github.com/OthmanAdi/langsmith-fetch-skill

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

---
—

Resources

—
—

Notes for Claude

—
  • Always check if 
    langsmith-fetch
    is installed before running commands
  • Verify environment variables are set
  • Use 
    --format pretty
    for human-readable output
  • Use 
    --format json
    when you need to parse and analyze data
  • When exporting sessions, create organized folder structures
  • Always provide clear analysis and actionable insights
  • If commands fail, help troubleshoot configuration issues
Version: 0.1.0 Author: Ahmad Othman Ammar Adi License: MIT Repository: https://github.com/OthmanAdi/langsmith-fetch-skill
—