企业官网建设流程全解析

使用 LangSmith Fetch 调试 LangChain/LangGraph Agent：在终端中定位 trace、错误与性能瓶颈的完整指南

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

在 awesome-codex-skills 仓库中，langsmith-fetch/ 是一个专为调试 LangChain 与 LangGraph Agent 而设计的 Codex Skill：它通过langsmith-fetchCLI 直接从 LangSmith Studio 拉取执行 trace，帮助你在终端中快速定位"Agent 为什么失败、调用了哪些工具、token 消耗在哪"。读完本文，你将掌握该 Skill 的安装与触发方式、四大核心调试工作流、四类高频实战场景的排查手法，以及输出格式、时间过滤、并发导出等高级用法，能够独立完成从"看一眼最近发生了什么"到"导出完整调试会话并给出根因分析"的全流程 Agent 排障。

一、Skill 概览：它解决什么问题

langsmith-fetch这个 Skill 的本质是一套标准化的 LangSmith 排障操作手册，其元信息记录在 SKILL.md 的 YAML frontmatter 中：

--- name: langsmith-fetch description: Debug LangChain and LangGraph agents by fetching execution traces from LangSmith Studio. Use when debugging agent behavior, investigating errors, analyzing tool calls, checking memory operations, or examining agent performance. Automatically fetches recent traces and analyzes execution patterns. Requires langsmith-fetch CLI installed. ---

从描述可以看出，它面向的典型诉求包括：调试 Agent 行为、调查错误、分析工具调用、检查记忆（memory）操作、评估 Agent 性能。凡是出现"我的 Agent 出了什么问题"这类疑问，Codex 就可以依据这段 description 自动触发该 Skill。

自动触发场景

当用户说出以下关键词时，该 Skill 应当被自动激活：

• 🐛 "Debug my agent" / "What went wrong?"（调试 Agent / 哪里出错了）
• 🔍 "Show me recent traces" / "What happened?"（查看最近 trace / 发生了什么）
• ❌ "Check for errors" / "Why did it fail?"（检查错误 / 为什么失败）
• 💾 "Analyze memory operations" / "Check LTM"（分析记忆操作 / 检查长期记忆）
• 📊 "Review agent performance" / "Check token usage"（审查性能 / 检查 token 用量）
• 🔧 "What tools were called?" / "Show execution flow"（调用了哪些工具 / 展示执行流程）

这与仓库 README.md 描述的 Codex Skill 机制一致：Skill 是模块化的指令包，Codex 读取 frontmatter 中的description来决定何时触发，命中后才加载正文，从而保持上下文精简。

二、前置条件：安装 CLI 与配置环境变量

1. 安装 langsmith-fetch CLI

pip install langsmith-fetch

该 Skill 本身只是指令文档，真正执行抓取动作的是langsmith-fetchCLI，因此安装 CLI 是硬性前提。运行任何命令前，Agent 应先确认langsmith-fetch是否已安装。

2. 设置环境变量

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

其中：

• LANGSMITH_API_KEY：LangSmith 平台的 API 密钥，用于身份认证；
• LANGSMITH_PROJECT：要拉取 trace 的目标项目名，必须与 LangSmith Studio 中的项目名完全一致。

3. 验证配置

echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT

两个变量都能正确回显，即表示配置就绪。需要注意的是，这种通过export设置的环境变量只在当前 shell 会话内有效，若希望长期生效，需要写入 shell 配置文件（详见下文"故障排查"小节）。

三、核心工作流（Core Workflows）

工作流 1：快速排查最近活动

适用场景：用户问"刚才发生了什么？"或"帮我调试一下 Agent"。

执行命令：

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

随后按以下 5 个维度分析并汇报：

1. ✅ 找到的 trace 数量
2. ⚠️ 是否存在错误或失败
3. 🛠️ 调用了哪些工具
4. ⏱️ 各 trace 的执行耗时
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.

这一工作流适合作为第一响应动作：先看最近几分钟内是否有 trace、是否有失败，快速建立全局认知。

工作流 2：深入分析指定 trace

适用场景：用户提供了 trace 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

从示例可见，该工作流的关键在于还原执行流水线（Execution Flow）：把工具调用按顺序列出、标记每一步的成败，定位"失败点（failure point）"，再给出根因与修复建议。在分析时还应同步汇报 token 消耗与执行耗时，方便判断问题是否与成本或性能相关。

工作流 3：导出调试会话

适用场景：用户说"保存这次会话"或"导出 traces"。

执行命令：

# 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

这里使用了两个子命令：

• langsmith-fetch traces <output-dir> ...：把 traces 导出到目录（此处注意命令形式是traces后跟输出路径）；
• langsmith-fetch threads <output-dir> ...：导出会话/对话线程（threads）。

$(date +%Y%m%d-%H%M%S)生成时间戳，保证每次导出目录不冲突。该工作流为团队协作、跨工具分析和归档留档提供了标准路径。

工作流 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

这个工作流展示了--format json与标准 shell 工具（grep）的组合用法：先导出 JSON，再正则检索错误关键词，最后按"错误类型 → 涉及 Agent/工具 → 发生时间 → 共性规律"组织分析，并给出可执行的建议。示例中的"14% failure rate"、"Happens during peak load"等洞察，正是从这类聚合分析中得出的。

四、常见使用场景（Common Use Cases）

场景 1："Agent 不响应"

用户说："我的 Agent 什么都没做。"

排查步骤：

1. 检查是否存在 trace：

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

2. 如果没有任何 trace，说明问题可能出在数据采集层，而非 Agent 本身：

   • 追踪（tracing）可能被禁用；
   • 检查环境中是否设置LANGCHAIN_TRACING_V2=true；
   • 检查LANGCHAIN_API_KEY是否已设置；
   • 确认 Agent 是否真的运行过。

3. 如果找到了 trace：

   • 检查是否有错误；
   • 检查执行耗时（是否卡住/挂起）；
   • 确认工具调用是否都已完成。

这里的核心思路是先判断"问题在数据层面还是运行层面"：查不到 trace 时优先怀疑 tracing 开关与密钥配置，查到 trace 时则聚焦运行细节。

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

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

排查步骤：

1. 获取对应的具体 trace；
2. 回顾执行时点上 Agent 可用的工具集合；
3. 检查 Agent 选择该工具时的推理过程（reasoning）；
4. 检查工具的 description / 指令描述是否清晰；
5. 据此建议改进 prompt 或工具配置。

这一场景强调：工具选错往往不是随机行为，而是工具描述歧义、工具集过大或推理上下文不完整导致的，修复方向应落在 prompt 与工具注册配置上。

场景 3："记忆功能不工作"

用户说："Agent 记不住事情。"

排查步骤：

1. 检索记忆相关操作：

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

2. 依次检查：

   • 记忆工具（memory tools）是否真的被调用？
   • recall 是否返回了结果？
   • 记忆是否真的被存储？
   • 检索到的记忆是否被后续使用？

通过 trace 还原记忆读写链路，可以区分"没调用工具"、"调用了但存储失败"、"存储成功但未被使用"等不同层次的故障。

场景 4："性能问题"

用户说："Agent 太慢了。"

排查步骤：

1. 导出带元数据的 traces：

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

2. 分析以下指标：

   • 每条 trace 的执行耗时；
   • 工具调用的延迟（latency）；
   • token 用量（上下文大小）；
   • 迭代（iteration）次数；
   • 最慢的操作是什么。

3. 定位瓶颈并给出优化建议。

性能分析的核心是将慢操作归因到具体环节——是模型推理慢、某个外部工具慢，还是迭代轮次过多导致上下文膨胀。

五、输出格式指南（Output Format Guide）

langsmith-fetch traces支持三种输出格式，通过--format参数切换：

实际使用中建议：给人看用pretty，给程序/工具用json，做 grep 过滤与自动化时用raw。错误检测工作流里的grep、记忆排查里的管道过滤，都依赖json或raw这类可解析格式。

六、高级特性（Advanced Features）

基于时间的过滤（Time-Based Filtering）

# After specific timestamp（指定时间戳之后） langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20 # Last N minutes（最近 N 分钟，最常用） langsmith-fetch traces --last-n-minutes 60 --limit 100

• --after：按 ISO 8601 时间戳过滤，适合跨天、跨时段回溯；
• --last-n-minutes：按分钟数回看，适合"刚才发生了什么"这类即时排查，是最高频的参数。

附带元数据（Include Metadata）

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

加上--include-metadata后，导出的数据会包含额外的上下文信息，SKILL.md 中明确列出的元数据字段包括：agent type（Agent 类型）、model（所用模型）、tags（标签）、environment（运行环境）。这些字段对跨 Agent、跨环境的对比分析非常有价值。

并发抓取（Concurrent Fetching）

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

当批量导出大量 traces 时，--concurrent 10可开启 10 路并发抓取，显著缩短大导出任务的等待时间。

七、故障排查（Troubleshooting）

现象："No traces found matching criteria"

可能原因：

1. 该时间窗口内没有 Agent 活动；
2. 追踪功能被禁用；
3. 项目名（project name）写错；
4. API key 存在问题。

解决方案：

# 1. 尝试更长时间窗口 langsmith-fetch traces --last-n-minutes 1440 --limit 50 # 2. 检查环境变量 echo $LANGSMITH_API_KEY echo $LANGSMITH_PROJECT # 3. 改用 threads 子命令 langsmith-fetch threads --limit 10 # 4. 确认代码中已开启 tracing # 检查是否设置了: LANGCHAIN_TRACING_V2=true

建议按"时间窗口 → 环境变量 → 换子命令 → 检查代码侧 tracing 开关"的顺序逐层排查。

现象："Project not found"

解决方案：

# 查看当前配置 langsmith-fetch config show # 设置正确的项目名（临时，环境变量方式） export LANGSMITH_PROJECT="correct-project-name" # 或者永久配置（CLI 配置方式） langsmith-fetch config set project "your-project-name"

注意这里展示了两种配置途径：LANGSMITH_PROJECT环境变量适合临时切换；langsmith-fetch config set project则将配置写入 CLI 的持久化配置中。可以先通过config show查看当前生效配置来对比排查。

现象：环境变量不持久化

解决方案：

# 写入 shell 配置文件（~/.bashrc 或 ~/.zshrc） echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc # 重载 shell 配置 source ~/.bashrc

如果使用 zsh，将.bashrc替换为.zshrc即可。重载后建议用echo $LANGSMITH_API_KEY再次验证。

八、最佳实践（Best Practices）

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/

按日期分层的sessions/、专门存放失败案例的error-cases/与性能数据的performance-tests/，让每个调试会话都有明确的落盘位置。

3. 文档化发现（Document Findings）

发现 bug 时，遵循标准流程：

1. 导出出问题的 trace；
2. 保存到error-cases/文件夹；
3. 在 README 中记录问题原因；
4. 将 trace ID 分享给团队。

trace ID 是 LangSmith 中的唯一标识，团队成员可凭它直接在 Studio 中复现查看。

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

把 trace 检查嵌入提交前环节，可以让调试从"事后救火"前移到"事前预防"。

九、快速参考：常用命令一览

# 最常用命令 # 快速调试：最近 5 分钟、5 条、pretty 格式 langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty # 指定 trace 详情 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

十、Agent 执行须知（面向自动化 Agent 的提示）

原 SKILL.md 面向 Agent 执行者给出了一组操作纪律，归纳如下：

• 运行命令前，始终先确认langsmith-fetch是否已安装；
• 验证环境变量（LANGSMITH_API_KEY、LANGSMITH_PROJECT）已正确设置；
• 面向人类阅读的输出使用--format pretty；
• 需要解析、分析数据时使用--format json；
• 导出会话时，创建规范的目录结构（带时间戳、分类清晰）；
• 始终给出明确的分析结论与可执行的洞察（actionable insights），而不是罗列原始数据；
• 若命令失败，主动帮助用户排查配置问题。

这套"先验证环境 → 选对格式 → 规范落盘 → 输出可执行结论"的执行纪律，是让整个调试流程可复现、可信赖的关键。

十一、如何将该 Skill 集成到 Codex

本 Skill 已收录于 awesome-codex-skills 仓库，可通过两种方式安装（详见 README.md）：

方式一：使用 Skill Installer（推荐）

git clone https://github.com/ComposioHQ/awesome-codex-skills.git cd awesome-codex-skills python skill-installer/scripts/install-skill-from-github.py --repo ComposioHQ/awesome-codex-skills --path langsmith-fetch

方式二：手动安装

1. 将langsmith-fetch/整个文件夹复制到$CODEX_HOME/skills/（默认为~/.codex/skills/）；
2. 重启 Codex 以加载新的元数据；
3. 在会话中自然描述任务（如"帮我调试 Agent"），Codex 会根据 frontmatter 的description自动触发该 Skill。

仓库 README.md 中对该 Skill 的定位描述是 "Pull LangSmith project/test data for analysis"，即拉取 LangSmith 项目/测试数据用于分析。安装完成后，即可配合pip install langsmith-fetch与环境变量配置，在 Codex 会话中获得一套完整的 LangSmith trace 调试能力。

小结

langsmith-fetch这个 Skill 的价值在于把 LangSmith 的 trace 调试从"手动点 Studio 页面"升级为"终端内可命令化、可脚本化、可汇报化"的流程：四个核心工作流覆盖了快速概览、单点深挖、会话导出与错误聚合；四个实战场景覆盖了无响应、错调工具、记忆失效与性能瓶颈；再加上三种输出格式、时间过滤、元数据与并发导出等高级特性，足以支撑日常的 Agent 排障与性能分析。对正在构建 LangChain/LangGraph 应用的开发者而言，把它装进 Codex 就相当于随身携带了一名熟悉 LangSmith 的调试助手。

附注：本 Skill 版本为 0.1.0，作者 Ahmad Othman Ammar Adi，采用 MIT 许可证，完整指令文档见 langsmith-fetch/SKILL.md。

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills