ComposioHQ/langsmith-fetch

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

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

このスキルを使うタイミング

ユーザーが以下のような発言をしたときに自動的に有効化します：

• 🐛 「エージェントをデバッグして」または「何が問題だった？」
• 🔍 「最近のトレースを見せて」または「何が起きた？」
• ❌ 「エラーを確認して」または「なぜ失敗した？」
• 💾 「メモリ操作を分析して」または「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. 確認事項:

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

---

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

ユーザーが言う: 「エージェントが遅すぎる」

手順:

1. メタデータ付きでエクスポート:

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

2. 分析:

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

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

---

出力形式ガイド

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

# メタデータに含まれるもの: agent type, model, tags, environment

並列フェッチ（高速化）

# 大規模エクスポートを高速化
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

トラブルシューティング

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

考えられる原因:

1. 時間範囲内にエージェントのアクティビティがない
2. トレースが無効になっている
3. プロジェクト名が間違っている
4. 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"

環境変数が永続化されない

解決策:

# シェル設定ファイルに追加 (~/.bashrc または ~/.zshrc)
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# シェル設定を再読み込み
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. 発見事項の文書化

バグを見つけた場合:

1. 問題のトレースをエクスポート
2. error-cases/ フォルダに保存
3. 何が問題だったか README に記録
4. トレース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 Docs: 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