langsmith-fetch

LangSmith Fetch - エージェントのデバッグスキル

ターミナルから LangSmith Studio の実行トレースを直接取得して、LangChain と LangGraph のエージェントをデバッグします。

このスキルを使用するタイミング

ユーザーが次のように言及した場合に自動的に有効化します：

• 🐛 「エージェントをデバッグして」または「何が問題だったの？」
• 🔍 「最近のトレースを表示して」または「何が起きたの？」
• ❌ 「エラーを確認して」または「なぜ失敗したの？」
• 💾 「メモリ操作を分析して」または「LTM を確認して」
• 📊 「エージェントのパフォーマンスを確認して」または「トークン使用量を確認して」
• 🔧 「どのツールが呼び出されたの？」または「実行フローを表示して」

前提条件

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

分析して報告する：

1. ✅ 見つかったトレースの数
2. ⚠️ エラーや失敗の有無
3. 🛠️ 呼び出されたツール
4. ⏱️ 実行時間
5. 💰 トークン使用量

回答形式の例：

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.

---

ワークフロー 2：特定のトレースを詳しく調査する

ユーザーが指定するもの： トレース ID、または「そのエラーを調査して」

実行：

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

JSON を分析して報告する：

1. 🎯 エージェントが何をしようとしていたか
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

---

ワークフロー 3：デバッグセッションをエクスポートする

ユーザーの依頼： 「このセッションを保存して」または「トレースをエクスポートして」

実行：

# 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

---

ワークフロー 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. 🎯 失敗したエージェント／ツール
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

---

よくあるユースケース

ユースケース 1：「エージェントが応答しない」

ユーザーの発言： 「エージェントが何もしない」

手順：

1. トレースが存在するか確認する：

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

2. トレースが見つからない場合：

   • トレースが無効になっている可能性があります
   • 確認：環境変数で LANGCHAIN_TRACING_V2=true が設定されていること
   • 確認：LANGCHAIN_API_KEY が設定されていること
   • エージェントが実際に実行されたことを確認する

3. トレースが見つかった場合：

   • エラーがないか確認する
   • 実行時間を確認する（処理が停止していないか）
   • ツール呼び出しが完了したことを確認する

---

ユースケース 2：「誤ったツールが呼び出された」

ユーザーの発言： 「なぜ誤ったツールを使ったの？」

手順：

1. 該当するトレースを取得する
2. 実行時に使用可能だったツールを確認する
3. ツール選択に関するエージェントの推論を確認する
4. ツールの説明／指示を調べる
5. プロンプトまたはツール設定の改善案を提案する

---

ユースケース 3：「メモリが機能しない」

ユーザーの発言： 「エージェントが情報を覚えてくれない」

手順：

1. メモリ操作を検索する：

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

2. 次の点を確認する：

   • メモリツールが呼び出されたか
   • 呼び出しによって結果が返されたか
   • メモリが実際に保存されたか
   • 取得したメモリが使用されているか

---

ユースケース 4：「パフォーマンスの問題」

ユーザーの発言： 「エージェントの動作が遅すぎる」

手順：

1. メタデータを含めてエクスポートする：

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

2. 分析する：

   • トレースごとの実行時間
   • ツール呼び出しのレイテンシ
   • トークン使用量（コンテキストサイズ）
   • イテレーション数
   • 最も遅い操作

3. ボトルネックを特定し、最適化案を提案する

---

出力形式ガイド

整形済み形式（デフォルト）

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

用途： すばやく目視で確認するとき、ユーザーに表示するとき

JSON 形式

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

用途： 詳細な分析、シンタックスハイライト付きの確認

Raw 形式

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

用途： 他のコマンドへのパイプ、オートメーション

---

高度な機能

時間ベースのフィルタリング

# After specific timestamp
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# Last N minutes (most common)
langsmith-fetch traces --last-n-minutes 60 --limit 100

メタデータを含める

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

# Metadata includes: agent type, model, tags, environment

並行フェッチ（高速化）

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

---

トラブルシューティング

「条件に一致するトレースが見つかりません」

考えられる原因：

1. 指定した時間範囲内にエージェントのアクティビティがない
2. トレースが無効になっている
3. プロジェクト名が間違っている
4. API キーに問題がある

解決策：

# 1. Try longer timeframe
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. Check environment
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. Try fetching threads instead
langsmith-fetch threads --limit 10

# 4. Verify tracing is enabled in your code
# Check for: LANGCHAIN_TRACING_V2=true

「プロジェクトが見つかりません」

解決策：

# View current config
langsmith-fetch config show

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

# Or configure permanently
langsmith-fetch config set project "your-project-name"

環境変数が保持されない

解決方法：

# Add to shell config file (~/.bashrc or ~/.zshrc)
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# Reload shell config
source ~/.bashrc

---

ベストプラクティス

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/

3. 調査結果を記録する

バグを見つけた場合：

1. 問題のあるトレースをエクスポートします
2. error-cases/ フォルダーに保存します
3. README に問題の内容を記録します
4. トレース ID をチームに共有します

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

---

クイックリファレンス

# Most common commands

# Quick debug
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# 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

---

リソース

• 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