ComposioHQ/langsmith-fetch

LangSmith Fetch – Fähigkeit zum Debuggen von Agenten

Debugge LangChain- und LangGraph-Agenten, indem du Ausführungs-Traces direkt aus LangSmith Studio in deinem Terminal abrufst.

Wann diese Fähigkeit zu verwenden ist

Automatisch aktivieren, wenn der Benutzer erwähnt:

• 🐛 „Debugge meinen Agenten“ oder „Was ist schiefgelaufen?“
• 🔍 „Zeig mir aktuelle Traces“ oder „Was ist passiert?“
• ❌ „Prüfe auf Fehler“ oder „Warum ist es fehlgeschlagen?“
• 💾 „Analysiere Speicheroperationen“ oder „Prüfe LTM“
• 📊 „Überprüfe die Agentenleistung“ oder „Prüfe Token-Nutzung“
• 🔧 „Welche Tools wurden aufgerufen?“ oder „Zeige den Ausführungsablauf“

Voraussetzungen

1. Installiere langsmith-fetch

pip install langsmith-fetch

2. Setze Umgebungsvariablen

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

Überprüfe die Einrichtung:

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

Kern-Workflows

Workflow 1: Schnelles Debuggen der letzten Aktivität

Wenn der Benutzer fragt: „Was ist gerade passiert?“ oder „Debugge meinen Agenten“

Ausführen:

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

Analysieren und berichten:

1. ✅ Anzahl der gefundenen Traces
2. ⚠️ Fehler oder Misserfolge
3. 🛠️ Aufgerufene Tools
4. ⏱️ Ausführungszeiten
5. 💰 Token-Nutzung

Beispiel-Antwortformat:

3 Traces in den letzten 5 Minuten gefunden:

Trace 1: ✅ Erfolg
- Agent: memento
- Tools: recall_memories, create_entities
- Dauer: 2,3s
- Tokens: 1.245

Trace 2: ❌ Fehler
- Agent: cypher
- Fehler: „Neo4j-Verbindungszeitüberschreitung“
- Dauer: 15,1s
- Fehlgeschlagen bei: search_nodes-Tool

Trace 3: ✅ Erfolg
- Agent: memento
- Tools: store_memory
- Dauer: 1,8s
- Tokens: 892

💡 Problem gefunden: Trace 2 ist aufgrund eines Neo4j-Timeout fehlgeschlagen. Empfehlung: Datenbankverbindung prüfen.

---

Workflow 2: Tiefgehende Analyse eines bestimmten Traces

Wenn der Benutzer angibt: Trace-ID oder sagt „Untersuche diesen Fehler“

Ausführen:

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

JSON analysieren und berichten:

1. 🎯 Was der Agent zu tun versuchte
2. 🛠️ Welche Tools aufgerufen wurden (in Reihenfolge)
3. ✅ Tool-Ergebnisse (Erfolg/Fehlschlag)
4. ❌ Fehlermeldungen (falls vorhanden)
5. 💡 Ursachenanalyse
6. 🔧 Vorgeschlagene Lösung

Beispiel-Antwortformat:

Tiefgehende Analyse – Trace abc123

Ziel: Benutzer fragte „Finde alle Projekte in Neo4j“

Ausführungsablauf:
1. ✅ search_nodes(query: „projects“)
   → 24 Knoten gefunden

2. ❌ get_node_details(node_id: „proj_123“)
   → Fehler: „Knoten nicht gefunden“
   → Dies ist der Fehlerpunkt

3. ⏹️ Ausführung gestoppt

Ursache:
Das search_nodes-Tool hat Knoten-IDs zurückgegeben, die in der Datenbank nicht mehr existieren,
möglicherweise aufgrund kürzlicher Löschungen.

Vorgeschlagene Lösung:
1. Fehlerbehandlung in get_node_details-Tool hinzufügen
2. Gelöschte Knoten in Suchergebnissen filtern
3. Cache-Invalidierungsstrategie aktualisieren

Token-Nutzung: 1.842 Tokens (0,0276 $)
Ausführungszeit: 8,7 Sekunden

---

Workflow 3: Debug-Sitzung exportieren

Wenn der Benutzer sagt: „Diese Sitzung speichern“ oder „Traces exportieren“

Ausführen:

# Sitzungsordner mit Zeitstempel erstellen
SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SESSION_DIR"

# Traces exportieren
langsmith-fetch traces "$SESSION_DIR/traces" --last-n-minutes 30 --limit 50 --include-metadata

# Threads exportieren (Konversationen)
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

Berichten:

✅ Sitzung erfolgreich exportiert!

Ort: langsmith-debug/session-20251224-143022/
- Traces: 42 Dateien
- Threads: 8 Dateien

Sie können jetzt:
1. Einzelne Trace-Dateien überprüfen
2. Ordner mit dem Team teilen
3. Mit externen Tools analysieren
4. Für zukünftige Referenz archivieren

Sitzungsgröße: 2,3 MB

---

Workflow 4: Fehlererkennung

Wenn der Benutzer fragt: „Zeig mir Fehler“ oder „Was schlägt fehl?“

Ausführen:

# Aktuelle Traces abrufen
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json

# Nach Fehlern suchen
grep -i "error\|failed\|exception" recent-traces.json

Analysieren und berichten:

1. 📊 Gesamtzahl der gefundenen Fehler
2. ❌ Fehlertypen und -häufigkeit
3. 🕐 Wann Fehler aufgetreten sind
4. 🎯 Welche Agenten/Tools fehlgeschlagen sind
5. 💡 Häufige Muster

Beispiel-Antwortformat:

Fehleranalyse – Letzte 30 Minuten

Gesamtzahl Traces: 50
Fehlgeschlagene Traces: 7 (14 % Fehlerquote)

Fehleraufschlüsselung:
1. Neo4j-Verbindungszeitüberschreitung (4 Vorkommen)
   - Agent: cypher
   - Tool: search_nodes
   - Erstmals aufgetreten: 14:32
   - Zuletzt aufgetreten: 14:45
   - Muster: Tritt während Spitzenlast auf

2. Speicher speichern fehlgeschlagen (2 Vorkommen)
   - Agent: memento
   - Tool: store_memory
   - Fehler: „Pinecone-Ratenlimit überschritten“
   - Aufgetreten: 14:38, 14:41

3. Tool nicht gefunden (1 Vorkommen)
   - Agent: sqlcrm
   - Versuchtes Tool: „export_report“ (existiert nicht)
   - Aufgetreten: 14:35

💡 Empfehlungen:
1. Wiederholungslogik für Neo4j-Zeitüberschreitungen hinzufügen
2. Ratenbegrenzung für Pinecone implementieren
3. sqlcrm-Toolkonfiguration korrigieren

---

Häufige Anwendungsfälle

Anwendungsfall 1: „Agent antwortet nicht“

Benutzer sagt: „Mein Agent tut nichts“

Schritte:

1. Prüfen, ob Traces vorhanden sind:

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

2. Wenn KEINE Traces gefunden werden:

   • Tracing könnte deaktiviert sein
   • Überprüfen: LANGCHAIN_TRACING_V2=true in der Umgebung
   • Überprüfen: LANGCHAIN_API_KEY ist gesetzt
   • Sicherstellen, dass der Agent tatsächlich ausgeführt wurde

3. Wenn Traces gefunden werden:

   • Auf Fehler überprüfen
   • Ausführungszeit prüfen (hängend?)
   • Tool-Aufrufe auf Vollständigkeit prüfen

---

Anwendungsfall 2: „Falsches Tool aufgerufen“

Benutzer sagt: „Warum wurde das falsche Tool verwendet?“

Schritte:

1. Den spezifischen Trace abrufen
2. Verfügbare Tools zum Zeitpunkt der Ausführung überprüfen
3. Die Begründung des Agenten für die Toolauswahl prüfen
4. Tool-Beschreibungen/-Anweisungen untersuchen
5. Verbesserungen an Prompt oder Tool-Konfiguration vorschlagen

---

Anwendungsfall 3: „Speicher funktioniert nicht“

Benutzer sagt: „Agent merkt sich Dinge nicht“

Schritte:

1. Nach Speicheroperationen suchen:

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

2. Überprüfen:

   • Wurden Speicher-Tools aufgerufen?
   • Gab recall Ergebnisse zurück?
   • Wurden Erinnerungen tatsächlich gespeichert?
   • Werden abgerufene Erinnerungen tatsächlich verwendet?

---

Anwendungsfall 4: „Leistungsprobleme“

Benutzer sagt: „Agent ist zu langsam“

Schritte:

1. Mit Metadaten exportieren:

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

2. Analysieren:

   • Ausführungszeit pro Trace
   • Tool-Aufruf-Latenzen
   • Token-Nutzung (Kontextgröße)
   • Anzahl der Iterationen
   • Langsamste Operationen

3. Engpässe identifizieren und Optimierungen vorschlagen

---

Leitfaden für Ausgabeformate

Pretty-Format (Standard)

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

Verwenden für: Schnelle visuelle Inspektion, Anzeigen für Benutzer

JSON-Format

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

Verwenden für: Detaillierte Analyse, syntaxhervorgehobene Überprüfung

Raw-Format

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

Verwenden für: Weiterleitung an andere Befehle, Automatisierung

---

Erweiterte Funktionen

Zeitbasierte Filterung

# Nach einem bestimmten Zeitstempel
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# Letzte N Minuten (am gebräuchlichsten)
langsmith-fetch traces --last-n-minutes 60 --limit 100

Metadaten einschließen

# Zusätzlichen Kontext abrufen
langsmith-fetch traces --limit 10 --include-metadata

# Metadaten umfassen: Agententyp, Modell, Tags, Umgebung

Gleichzeitiges Abrufen (Schneller)

# Große Exporte beschleunigen
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

Fehlerbehebung

„Keine Traces gefunden, die den Kriterien entsprechen“

Mögliche Ursachen:

1. Keine Agentenaktivität im angegebenen Zeitraum
2. Tracing ist deaktiviert
3. Falscher Projektname
4. Probleme mit dem API-Key

Lösungen:

# 1. Längeren Zeitraum versuchen
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. Umgebung überprüfen
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. Stattdessen Threads abrufen
langsmith-fetch threads --limit 10

# 4. Sicherstellen, dass Tracing im Code aktiviert ist
# Prüfen auf: LANGCHAIN_TRACING_V2=true

„Projekt nicht gefunden“

Lösung:

# Aktuelle Konfiguration anzeigen
langsmith-fetch config show

# Richtiges Projekt setzen
export LANGSMITH_PROJECT="correct-project-name"

# Oder dauerhaft konfigurieren
langsmith-fetch config set project "your-project-name"

Umgebungsvariablen bleiben nicht bestehen

Lösung:

# Zur Shell-Konfigurationsdatei hinzufügen (~/.bashrc oder ~/.zshrc)
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# Shell-Konfiguration neu laden
source ~/.bashrc

---

Best Practices

1. Regelmäßige Gesundheitschecks

# Schnelle Überprüfung nach Änderungen
langsmith-fetch traces --last-n-minutes 5 --limit 5

2. Organisierte Speicherung

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

3. Ergebnisse dokumentieren

Wenn Sie Fehler finden:

1. Exportieren Sie den problematischen Trace
2. Im Ordner error-cases/ speichern
3. Notieren Sie, was schiefging, in einer README
4. Trace-ID mit dem Team teilen

4. Integration in die Entwicklung

# Vor dem Committen von Code
langsmith-fetch traces --last-n-minutes 10 --limit 5

# Falls Fehler gefunden werden
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---

Kurzreferenz

# Die gebräuchlichsten Befehle

# Schnelles Debuggen
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# Bestimmter Trace
langsmith-fetch trace <trace-id> --format pretty

# Sitzung exportieren
langsmith-fetch traces ./debug-session --last-n-minutes 30 --limit 50

# Fehler finden
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format raw | grep -i error

# Mit Metadaten
langsmith-fetch traces --limit 10 --include-metadata

---

Ressourcen

• LangSmith Fetch CLI: https://github.com/langchain-ai/langsmith-fetch
• LangSmith Studio: https://smith.langchain.com/
• LangChain-Dokumentation: https://docs.langchain.com/
• Repo dieser Fähigkeit: https://github.com/OthmanAdi/langsmith-fetch-skill

---

Hinweise für Claude

• Vor dem Ausführen von Befehlen immer prüfen, ob langsmith-fetch installiert ist
• Sicherstellen, dass Umgebungsvariablen gesetzt sind
• --format pretty für menschenlesbare Ausgabe verwenden
• --format json verwenden, wenn Sie Daten parsen und analysieren müssen
• Beim Exportieren von Sitzungen organisierte Ordnerstrukturen erstellen
• Immer klare Analysen und umsetzbare Erkenntnisse liefern
• Wenn Befehle fehlschlagen, bei der Fehlerbehebung von Konfigurationsproblemen helfen

---

Version: 0.1.0 Autor: Ahmad Othman Ammar Adi Lizenz: MIT Repository: https://github.com/OthmanAdi/langsmith-fetch-skill