langsmith-fetch

LangSmith Fetch - 代理除錯技能

直接在終端機中從 LangSmith Studio 擷取執行追蹤，來除錯 LangChain 和 LangGraph 代理。

何時使用此技能

當使用者提到以下內容時自動啟用：

🐛 "除錯我的代理" 或 "哪裡出錯了？"
🔍 "顯示最近的追蹤" 或 "發生了什麼事？"
❌ "檢查錯誤" 或 "為什麼失敗了？"
💾 "分析記憶體操作" 或 "檢查 LTM"
📊 "檢視代理效能" 或 "檢查 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：快速除錯近期活動

當使用者問： "剛剛發生了什麼事？" 或 "除錯我的代理"

執行：

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

分析並回報：

✅ 找到的追蹤數量
⚠️ 任何錯誤或失敗
🛠️ 被呼叫的工具
⏱️ 執行時間
💰 Token 用量

範例回覆格式：

在過去 5 分鐘內找到 3 個追蹤：

追蹤 1：✅ 成功
- 代理：memento
- 工具：recall_memories, create_entities
- 持續時間：2.3 秒
- Token：1,245

追蹤 2：❌ 錯誤
- 代理：cypher
- 錯誤："Neo4j 連線逾時"
- 持續時間：15.1 秒
- 失敗於：search_nodes 工具

追蹤 3：✅ 成功
- 代理：memento
- 工具：store_memory
- 持續時間：1.8 秒
- Token：892

💡 發現問題：追蹤 2 因 Neo4j 逾時而失敗。建議檢查資料庫連線。

工作流程 2：深入分析特定追蹤

當使用者提供： 追蹤 ID 或說 "調查那個錯誤"

執行：

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

分析 JSON 並回報：

🎯 代理嘗試做什麼
🛠️ 呼叫了哪些工具（依序）
✅ 工具結果（成功/失敗）
❌ 錯誤訊息（如果有）
💡 根本原因分析
🔧 建議的修正

範例回覆格式：

深入分析 - 追蹤 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. 更新快取失效策略

Token 用量：1,842 tokens ($0.0276)
執行時間：8.7 秒

工作流程 3：匯出除錯工作階段

當使用者說： "儲存這個工作階段" 或 "匯出追蹤"

執行：

# 建立帶時間戳的工作階段資料夾
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

回報：

✅ 工作階段匯出成功！

位置：langsmith-debug/session-20251224-143022/
- 追蹤：42 個檔案
- 執行緒：8 個檔案

您現在可以：
1. 檢閱個別追蹤檔案
2. 與團隊分享資料夾
3. 使用外部工具分析
4. 封存以供未來參考

工作階段大小：2.3 MB

工作流程 4：錯誤偵測

當使用者問： "顯示錯誤" 或 "什麼東西在失敗？"

執行：

# 擷取最近的追蹤
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json

# 搜尋錯誤
grep -i "error\|failed\|exception" recent-traces.json

分析並回報：

📊 找到的錯誤總數
❌ 錯誤類型與頻率
🕐 錯誤發生的時間
🎯 哪些代理/工具失敗
💡 常見模式

範例回覆格式：

錯誤分析 - 過去 30 分鐘

追蹤總數：50
失敗追蹤：7（14% 失敗率）

錯誤細項：
1. Neo4j 連線逾時（4 次）
   - 代理：cypher
   - 工具：search_nodes
   - 首次發生：14:32
   - 最後發生：14:45
   - 模式：發生在尖峰負載時

2. 記憶體儲存失敗（2 次）
   - 代理：memento
   - 工具：store_memory
   - 錯誤："Pinecone 速率限制超標"
   - 發生時間：14:38, 14:41

3. 找不到工具（1 次）
   - 代理：sqlcrm
   - 嘗試的工具："export_report"（不存在）
   - 發生時間：14:35

💡 建議：
1. 為 Neo4j 逾時新增重試邏輯
2. 對 Pinecone 實施速率限制
3. 修正 sqlcrm 工具設定

常見使用案例

使用案例 1："代理沒有回應"

使用者說： "我的代理沒有任何動作"

步驟：

檢查是否有追蹤存在：

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

如果找不到追蹤：
- 追蹤功能可能被停用
- 檢查環境中是否有 LANGCHAIN_TRACING_V2=true
- 檢查 LANGCHAIN_API_KEY 是否已設定
- 確認代理確實有執行
如果找到追蹤：
- 檢閱是否有錯誤
- 檢查執行時間（是否卡住？）
- 確認工具呼叫是否完成

使用案例 2："呼叫了錯誤的工具"

使用者說： "為什麼它用了錯誤的工具？"

步驟：

取得特定追蹤
檢視執行時可用的工具
檢查代理選擇工具的推理過程
檢查工具描述/指令
建議改善提示或工具設定

使用案例 3："記憶體無法運作"

使用者說： "代理記不住事情"

步驟：

搜尋記憶體操作：

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

檢查：
- 是否有呼叫記憶體工具？
- recall 是否有傳回結果？
- 記憶體是否確實被儲存？
- 擷取的記憶體是否被使用？

使用案例 4："效能問題"

使用者說： "代理太慢了"

步驟：

匯出含中繼資料的追蹤：

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

分析：
- 每個追蹤的執行時間
- 工具呼叫延遲
- Token 用量（上下文大小）
- 迭代次數
- 最慢的操作
找出瓶頸並建議最佳化

輸出格式指南

Pretty 格式（預設）

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

用於： 快速視覺檢查、向使用者展示

JSON 格式

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

用於： 詳細分析、語法高亮檢閱

Raw 格式

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

用於： 管線傳遞給其他指令、自動化

進階功能

時間篩選

# 特定時間戳之後
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# 最近 N 分鐘（最常用）
langsmith-fetch traces --last-n-minutes 60 --limit 100

包含中繼資料

# 取得額外上下文
langsmith-fetch traces --limit 10 --include-metadata

# 中繼資料包含：代理類型、模型、標籤、環境

並行擷取（更快）

# 加速大量匯出
langsmith-fetch traces ./output --limit 100 --concurrent 10

疑難排解

"找不到符合條件的追蹤"

可能原因：

時間範圍內沒有代理活動
追蹤功能已停用
專案名稱錯誤
API 金鑰問題

解決方案：

# 1. 嘗試更長的時間範圍
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. 檢查環境
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. 嘗試改為擷取執行緒
langsmith-fetch threads --limit 10

# 4. 確認程式碼中已啟用追蹤
# 檢查是否有：LANGCHAIN_TRACING_V2=true

"找不到專案"

解決方案：

# 檢視目前設定
langsmith-fetch config show

# 設定正確的專案
export LANGSMITH_PROJECT="correct-project-name"

# 或永久設定
langsmith-fetch config set project "your-project-name"

環境變數未持久化

解決方案：

# 加入 shell 設定檔（~/.bashrc 或 ~/.zshrc）
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# 重新載入 shell 設定
source ~/.bashrc

最佳實務

1. 定期健康檢查

# 修改後快速檢查
langsmith-fetch traces --last-n-minutes 5 --limit 5

2. 有組織的儲存

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

3. 記錄發現

當您發現錯誤時：

匯出有問題的追蹤
儲存到 error-cases/ 資料夾
在 README 中記錄問題
與團隊分享追蹤 ID

4. 與開發流程整合

# 提交程式碼前
langsmith-fetch traces --last-n-minutes 10 --limit 5

# 如果發現錯誤
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

快速參考

# 最常用的指令

# 快速除錯
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# 特定追蹤
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

資源

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

您可能也喜歡

planning-with-files-es

25Kagent-workflows

Sistema de planificación basado en archivos estilo Manus para organizar y rastrear el progreso de tareas complejas. Crea task_plan.md, findings.md y progress.md. Cuando el usuario solicita planificación, desglose u organización de proyectos multipaso, tareas de investigación o trabajos que requieren más de 5 llamadas a herramientas. Soporta recuperación automática de sesión tras /clear. Palabras clave: planificación de tareas, planificación de proyecto, crear plan de trabajo, analizar tareas, organizar proyecto, seguimiento de progreso, planificación multipaso, ayúdame a planificar, desglosar proyecto

othmanadi

獲取

hv-analysis

19Kagent-workflows

横纵分析法（Horizontal-Vertical Analysis）深度研究Skill。由数字生命卡兹克提出，融合了索绪尔的历时-共时分析、社会科学的纵向-横截面研究设计、商学院案例研究法与竞争战略分析的核心思想。当用户想要系统性研究一个产品、公司、概念、技术或人物时使用。核心是双轴分析：纵轴追踪从诞生到当下的完整生命历程（以叙事故事呈现），横轴在当下时间截面上与竞品/同类进行系统性横向对比，最后交叉两条轴产出独到洞察。最终产出一份排版精美的PDF研究报告。触发词包括但不限于：横纵分析、研究一下、帮我分析、深度研究、做个研究、调研一下、竞品分析、帮我看看这个东西怎么样、这个产品/公司/概念是怎么回事、帮我摸清楚、帮我搞懂、帮我做个deep research。即使用户只是说"帮我了解一下XX"或"XX是什么来头"，只要上下文暗示需要系统性的深度研究（而非简单的概念解释），都应该触发。也适用于用户丢来一个产品名、公司名、技术名词说"帮我研究一下这个"的场景。不要用于简单的名词解释（用户只是问"XX是什么"）、不要用于公众号写作（那个用khazix-writer）、不要用于纯标题摘要生成（用wechat-title）。

kkkkhazix

獲取

homelab-vlan-segmentation

238Kagent-workflows

Segmenting home networks into VLANs for IoT, guest, trusted, and server traffic using UniFi, pfSense/OPNsense, and MikroTik — including switch trunk config, firewall rules, and wireless SSID mapping.

affaan-m

獲取

繼續探索

瀏覽 agent-workflows 熱門 Skills 最近更新

langsmith-fetch

相關技能

LangSmith Fetch - 代理除錯技能

何時使用此技能

前置需求

1. 安裝 langsmith-fetch

2. 設定環境變數

核心工作流程

工作流程 1：快速除錯近期活動

工作流程 2：深入分析特定追蹤

工作流程 3：匯出除錯工作階段

工作流程 4：錯誤偵測

常見使用案例

使用案例 1："代理沒有回應"

使用案例 2："呼叫了錯誤的工具"

使用案例 3："記憶體無法運作"

使用案例 4："效能問題"

輸出格式指南

Pretty 格式（預設）

JSON 格式

Raw 格式

進階功能

時間篩選

包含中繼資料

並行擷取（更快）

疑難排解

"找不到符合條件的追蹤"

"找不到專案"

環境變數未持久化

最佳實務

1. 定期健康檢查

2. 有組織的儲存

3. 記錄發現

4. 與開發流程整合

快速參考

資源

給 Claude 的備註

您可能也喜歡

planning-with-files-es

hv-analysis

homelab-vlan-segmentation

繼續探索