langsmith-fetch

langsmith-fetch skill 概览

langsmith-fetch 的作用

langsmith-fetch 是一个面向 LangChain 和 LangGraph 应用的调试 skill，适合需要从 LangSmith Studio 进行 trace 级别排查的场景。它不是让助手凭经验猜测 agent 为什么失败，而是引导助手使用 langsmith-fetch CLI 拉取最近的 LangSmith traces，检查 runs、errors、tool calls、memory activity、timing 和 token usage，然后总结最可能发生了什么。

最适合 LangChain 和 LangGraph 调试的场景

langsmith-fetch skill 最适合这样的情况：你已经为 agents 启用了 LangSmith tracing，并希望在开发调试或事故复盘时更快定位问题。它适用于类似这些问题：“这个 agent 为什么失败了？”、“调用了哪些 tools？”、“为什么延迟这么高？”、“memory 是否正确更新？”、“最近几分钟发生了什么？”

如果你的应用没有向 LangSmith 发送 traces、你没有相关 project 的访问权限，或者你需要的是 trace 数据之外的代码级性能分析，那么它的帮助会比较有限。

核心差异：先看证据，再分析 agent

普通 prompt 可以描述可能原因，但 langsmith-fetch 会把助手引向可观察证据：recent traces、run statuses、execution flow、tool invocations、errors、timings 和 token usage。对于调试 agent 行为来说，这会让输出更可执行，尤其是当失败取决于运行时状态，而不是静态代码本身时。

如何使用 langsmith-fetch skill

langsmith-fetch 安装与设置

在依赖这个 skill 之前，先安装 CLI：

pip install langsmith-fetch

设置 CLI 查询所需的 LangSmith 凭据和 project：

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

确认这些变量在你的 assistant 或终端命令将要运行的 shell 中都可用：

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

如果这些变量缺失，或者指向了错误的 project，这个 skill 可能会给出空结果，甚至产生误导性的调试结论。

你需要提供给 skill 的输入

为了得到更好的结果，请给助手明确的调试目标、时间窗口和问题现象。一个较弱的 prompt 是：“debug my agent.” 更好的 prompt 是：

Use langsmith-fetch to inspect the last 15 minutes of traces in my LangSmith project. Focus on failed LangGraph runs, tool call errors, memory writes, latency spikes, and token usage. Summarize the likely root cause and list the trace evidence you used.

有用的信息包括：

• 大致失败时间，或“last N minutes”
• agent、graph、chain 或 endpoint 名称
• 预期行为与实际行为的差异
• 是否优先关注 errors、tools、memory、performance 或 cost
• 与事故相关的用户输入或 run ID

实用的 langsmith-fetch 使用流程

常见的第一条命令是：

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

这适合在最近一次失败后做快速分诊。可以要求助手报告：

1. 找到了多少条 traces
2. 哪些 traces 失败了，或看起来异常
3. 相关 tool calls 及其 inputs/outputs
4. 如果你的 agent 使用 memory 或 state，报告相应操作
5. latency 和 token usage 的模式
6. 一个简洁的根因假设，并附上证据

如果要做更深入的调试，可以扩大时间窗口或提高 limit。对于噪声较多的 projects，可以按 project 上下文、时间范围、run name 或具体失败现象缩小查询范围。

优先阅读的仓库文件

上游 skill 的主要内容集中在 SKILL.md；从仓库预览来看，没有重要的配套 scripts/、resources/ 或 references/ 文件夹。应先阅读 SKILL.md，了解它预期的触发短语、前置条件和工作流模式。采用这个 skill 的关键检查点不是仓库复杂度，而是你的 LangSmith 环境和 CLI 访问是否已经配置好。

langsmith-fetch skill 常见问题

langsmith-fetch 只适用于 LangGraph 吗？

不是。这个 skill 面向 LangChain 和 LangGraph agent 调试。它对 graph 风格的执行尤其有用，因为 traces 可以揭示 node flow、tool calls、state transitions，以及 run 从预期路径偏离的位置。

这比让 AI 根据日志调试好在哪里？

当问题能在 LangSmith traces 中看到时，langsmith-fetch skill 更有优势。它为助手提供了一个拉取执行数据的具体工作流，而不是依赖粘贴的日志或猜测。你仍然需要批判性地审查结果，但分析会从实际观察到的 runs 出发，而不是泛泛的调试建议。

新手需要了解 LangSmith 才能使用吗？

如果已经有人启用了 LangSmith tracing，并提供了正确的 LANGSMITH_API_KEY 和 LANGSMITH_PROJECT，新手也可以使用这个 skill。没有这些设置时，主要障碍不是 prompt 怎么写，而是环境访问权限。对 traces、runs、tool calls 和 projects 有基本了解，会更容易理解输出。

什么时候不应该使用 langsmith-fetch？

不要把它用于未在 LangSmith 中 tracing 的应用、仅前端行为的调试、未体现在 traces 中的数据库问题，或 assistant 环境不应访问 LangSmith 凭据的私有 projects。还有一种情况也不适合：你已经有精确的 run ID，并且需要在 LangSmith UI 中结合截图或团队标注进行人工检查。

如何改进 langsmith-fetch skill

用更明确的范围改进 langsmith-fetch prompts

最大的质量提升来自缩小问题范围。不要要求做宽泛审查，而是明确你需要做出的判断：

Check recent traces for failed tool calls in the payment support agent. Determine whether failures come from tool input formatting, tool timeout, or model planning. Include trace IDs or run names if available.

这样能帮助助手区分现象和原因，避免把每条 trace 都泛泛总结一遍。

提供证据目标，而不只是描述症状

告诉 skill 哪些证据最重要。做可靠性调试时，要求查看 errors、retries、exception messages 和 last successful step。做性能调试时，要求查看 slow runs、long tool calls、model latency 和 token usage。做 memory 调试时，要求查看 read/write operations、missing context、unexpected state updates，以及后续步骤是否使用了已存储的信息。

留意常见失败模式

常见问题包括查询了错误的 LangSmith project、时间窗口太短、拉取的 traces 太少，或把一次失败的 run 当作整体代表。如果结果看起来为空，先确认环境变量，并扩大时间窗口。如果结果噪声太多，就按 agent name、time 或 symptom 缩小范围。如果分析听起来像猜测，要求助手把“trace evidence”和“hypothesis”分开写。

第一次输出后继续迭代

初次使用 langsmith-fetch 之后，可以继续追问，把 trace 分析转化为工程行动：

• “Which code path should I inspect first?”
• “What prompt or tool schema change would prevent this?”
• “Compare failed and successful traces in the same window.”
• “List the minimal reproduction from the trace.”
• “What metric should I monitor to catch this earlier?”

这样可以把这个 skill 从一个 trace 查看器，变成面向 LangChain 和 LangGraph agents 的实用调试闭环。