终端一键获取 LangSmith 执行轨迹调试 Agent

解决 LangChain 和 LangGraph Agent 调试难题：无需登录网页，直接在终端从 LangSmith Studio 拉取执行轨迹，快速分析错误原因、工具调用顺序、内存操作及 Token 消耗情况。

为什么需要这个技能

开发 LangChain 或 LangGraph 应用时，AI Agent 偶尔会出意外，比如报错、调用工具失败或逻辑死循环。

LangSmith 是官方监控平台，但登录网页查看记录比较繁琐，尤其需要查最近几分钟的数据。本技能允许你直接在命令行安装 langsmith-fetch，自动拉取最近轨迹并解析关键指标，极大加速定位问题过程。

适用场景

• 排查 Agent 故障：当用户反馈"Agent 没反应”或“运行报错”时，快速拉取最近 5 分钟的轨迹看哪里断了。
• 分析工具调用链：确认 Agent 是否正确调用了预期的工具，如数据库查询或外部 API。
• 检查内存与状态：查看长期记忆（LTM）是否成功存储和检索，判断为何 Agent 没记住之前的对话内容。
• 性能监控：统计 Token 使用量和执行耗时，识别导致 Agent 变慢的瓶颈操作。

核心工作流

1. 安装与环境配置

首先安装 CLI 工具并设置环境变量：

pip install langsmith-fetch

export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"

验证安装：

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

2. 快速查看近期活动

询问用户最近发生了什么，执行：

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

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

3. 深入分析特定错误

提供 Trace ID 或描述错误时，执行：

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

分析步骤：

1. 🎯 还原 Agent 目标任务
2. 🛠️ 列出按顺序调用的工具
3. ✅ 标记成功/失败的步骤
4. ❌ 提取错误消息
5. 💡 分析根本原因（Root Cause）
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.

Suggested Fix:
1. Add error handling in get_node_details tool
2. Filter deleted nodes in search results

4. 导出调试会话

用户要求保存本次会话时：

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

结果确认：

✅ Session exported successfully!
- Traces: 42 files
- Threads: 8 files

常见问题排查

Agent 无响应

检查点：

# 确认近期有轨迹生成
langsmith-fetch traces --last-n-minutes 5 --limit 5

# 若无轨迹，检查环境变量
echo $LANGCHAIN_TRACING_V2
echo $LANGCHAIN_API_KEY

工具调用错误

步骤：

1. 获取具体 Trace
2. 审查 Agent 选择工具时的推理
3. 检查工具描述（Tool Descriptions）是否匹配当前需求

内存失效

验证步骤：

# 搜索记忆相关操作
langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory"

输出格式选择

• Pretty：给人看，适合快速汇报。
• JSON：用于脚本解析或详细分析。
• Raw：用于管道命令或自动化处理。

最佳实践

• 定期健康检查：每次代码变更后，运行一次快速抓取确认无异常。
• 错误归档：遇到 Bug 时，将轨迹导出至专门的 error-cases 文件夹并记录在案。
• 并发加速：导出大量数据时，可使用 --concurrent 10 提升速度。

下载和安装

下载 langsmith-fetch 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。

你可能还需要

暂无推荐