langsmith-fetch

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

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

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

以下のようなユーザーの発言があった場合に自動的に有効化されます：

• 🐛 「エージェントをデバッグして」「何が問題だった？」
• 🔍 「最近のトレースを見せて」「何が起こった？」
• ❌ 「エラーをチェックして」「なぜ失敗した？」
• 💾 「メモリ操作を分析して」「長期記憶を確認」
• 📊 「エージェントのパフォーマンスを確認」「トークン使用量をチェック」
• 🔧 「どのツールが呼ばれた？」「実行フローを見せて」

前提条件

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. 💰 トークン使用量

回答形式の例:

直近5分間で3件のトレースを検出:

トレース 1: ✅ 成功
- エージェント: memento
- ツール: recall_memories, create_entities
- 実行時間: 2.3秒
- トークン: 1,245

トレース 2: ❌ エラー
- エージェント: cypher
- エラー: "Neo4j connection timeout"
- 実行時間: 15.1秒
- 失敗箇所: search_nodes ツール

トレース 3: ✅ 成功
- エージェント: memento
- ツール: store_memory
- 実行時間: 1.8秒
- トークン: 892

💡 問題発見: トレース2はNeo4jタイムアウトにより失敗。データベース接続を確認することを推奨。

---

ワークフロー 2: 特定トレースの詳細分析

ユーザーが提供した場合: トレースID、または「そのエラーを調査して」と言った場合

実行:

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

JSONを分析して報告:

1. 🎯 エージェントが実行しようとしていた内容
2. 🛠️ 呼び出されたツール（順序）
3. ✅ ツールの結果（成功/失敗）
4. ❌ エラーメッセージ（存在する場合）
5. 💡 根本原因の分析
6. 🔧 推奨される修正

回答形式の例:

詳細分析 - トレース abc123

目標: ユーザーが「Neo4j内のすべてのプロジェクトを検索」と依頼

実行フロー:
1. ✅ search_nodes(query: "projects")
   → 24ノード発見

2. ❌ get_node_details(node_id: "proj_123")
   → エラー: "Node not found"
   → これが失敗箇所

3. ⏹️ 実行停止

根本原因:
search_nodesツールが、データベースに存在しなくなったノードIDを返しました。
最近の削除が原因の可能性があります。

推奨修正:
1. get_node_detailsツールにエラーハンドリングを追加
2. 検索結果から削除済みノードをフィルタリング
3. キャッシュ無効化戦略を更新

トークン使用量: 1,842 トークン ($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

分析して報告:

1. 📊 検出されたエラーの総数
2. ❌ エラーの種類と頻度
3. 🕐 エラーが発生した時間
4. 🎯 どのエージェント/ツールが失敗したか
5. 💡 共通パターン

回答形式の例:

エラー分析 - 直近30分

総トレース数: 50
失敗トレース数: 7 (14% の失敗率)

エラー内訳:
1. Neo4j接続タイムアウト (4回発生)
   - エージェント: cypher
   - ツール: search_nodes
   - 初回発生: 14:32
   - 最終発生: 14:45
   - パターン: ピーク負荷時に発生

2. メモリストア失敗 (2回発生)
   - エージェント: memento
   - ツール: store_memory
   - エラー: "Pinecone rate limit exceeded"
   - 発生時刻: 14:38, 14:41

3. ツール未検出 (1回発生)
   - エージェント: sqlcrm
   - 試行されたツール: "export_report" (存在しない)
   - 発生時刻: 14:35

💡 推奨事項:
1. Neo4jタイムアウトに対するリトライロジックを追加
2. Pineconeのレート制限を実装
3. sqlcrmのツール設定を修正

---

一般的なユースケース

ユースケース 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

# メタデータに含まれるもの: エージェントタイプ、モデル、タグ、環境

同時フェッチ（高速化）

# 大規模なエクスポートを高速化
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 ドキュメント: 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