langsmith-fetch

LangSmith Fetch – Agenten-Debugging-Fähigkeit

Debuggen Sie LangChain- und LangGraph-Agenten, indem Sie Ausführungs-Traces direkt von LangSmith Studio in Ihrem Terminal abrufen.

Wann Sie diese Fähigkeit verwenden sollten

Automatisch aktivieren, wenn der Benutzer Folgendes erwähnt:

• 🐛 "Meinen Agenten debuggen" oder "Was ist schiefgelaufen?"
• 🔍 "Zeige mir aktuelle Traces" oder "Was ist passiert?"
• ❌ "Auf Fehler prüfen" oder "Warum ist es fehlgeschlagen?"
• 💾 "Speicheroperationen analysieren" oder "LTM prüfen"
• 📊 "Agentenleistung überprüfen" oder "Token-Verbrauch prüfen"
• 🔧 "Welche Tools wurden aufgerufen?" oder "Ausführungsablauf anzeigen"

Voraussetzungen

1. langsmith-fetch installieren

pip install langsmith-fetch

2. Umgebungsvariablen setzen

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

Einrichtung überprüfen:

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. ⚠️ Eventuelle Fehler oder Fehlschläge
3. 🛠️ Aufgerufene Tools
4. ⏱️ Ausführungszeiten
5. 💰 Token-Verbrauch

Beispiel für 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 connection timeout"
- 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 fehlgeschlagen aufgrund von Neo4j-Timeout. Empfehlung: Datenbankverbindung prüfen.

---

Workflow 2: Tiefergehende 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 für Antwortformat:

Tiefenanalyse – 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 Tool search_nodes gab Knoten-IDs zurück, die in der Datenbank nicht mehr existieren,
möglicherweise aufgrund kürzlicher Löschungen.

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

Token-Verbrauch: 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 (Unterhaltungen)
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

Berichten:

✅ Sitzung erfolgreich exportiert!

Speicherort: 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 Referenzen archivieren

Sitzungsgröße: 2,3 MB

---

Workflow 4: Fehlererkennung

Wenn der Benutzer fragt: "Zeige 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. 📊 Gesamtanzahl gefundener Fehler
2. ❌ Fehlertypen und Häufigkeit
3. 🕐 Zeitpunkt der Fehler
4. 🎯 Welche Agenten/Tools fehlgeschlagen sind
5. 💡 Häufige Muster

Beispiel für Antwortformat:

Fehleranalyse – Letzte 30 Minuten

Gesamttraces: 50
Fehlgeschlagene Traces: 7 (14% Fehlerrate)

Fehleraufschlüsselung:
1. Neo4j-Verbindungstimeout (4 Vorkommen)
   - Agent: cypher
   - Tool: search_nodes
   - Erstes Auftreten: 14:32
   - Letztes Auftreten: 14:45
   - Muster: Tritt bei Spitzenlast auf

2. Speicher speichern fehlgeschlagen (2 Vorkommen)
   - Agent: memento
   - Tool: store_memory
   - Fehler: "Pinecone rate limit exceeded"
   - Auftreten: 14:38, 14:41

3. Tool nicht gefunden (1 Vorkommen)
   - Agent: sqlcrm
   - Versuchtes Tool: "export_report" (existiert nicht)
   - Auftreten: 14:35

💡 Empfehlungen:
1. Wiederholungslogik für Neo4j-Timeouts hinzufügen
2. Ratenbegrenzung für Pinecone implementieren
3. Tool-Konfiguration von sqlcrm korrigieren

---

Häufige Anwendungsfälle

Anwendungsfall 1: "Agent antwortet nicht"

Benutzer sagt: "Mein Agent tut nichts"

Schritte:

1. Prüfen, ob Traces existieren:

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

2. Wenn KEINE Traces gefunden:

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

3. Wenn Traces gefunden:

   • Auf Fehler prüfen
   • Ausführungszeit prüfen (hängt?)
   • Überprüfen, ob Tool-Aufrufe abgeschlossen wurden

---

Anwendungsfall 2: "Falsches Tool aufgerufen"

Benutzer sagt: "Warum hat es das falsche Tool verwendet?"

Schritte:

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

---

Anwendungsfall 3: "Speicher funktioniert nicht"

Benutzer sagt: "Agent erinnert sich nicht an Dinge"

Schritte:

1. Nach Speicheroperationen suchen:

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

2. Prüfen:

   • Wurden Speicher-Tools aufgerufen?
   • Hat recall Ergebnisse zurückgegeben?
   • Wurden Erinnerungen tatsächlich gespeichert?
   • Werden abgerufene Erinnerungen 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
   • Latenzen von Tool-Aufrufen
   • Token-Verbrauch (Kontextgröße)
   • Anzahl der Iterationen
   • Langsamste Vorgänge

3. Engpässe identifizieren und Optimierungen vorschlagen

---

Leitfaden zum Ausgabeformat

Pretty-Format (Standard)

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

Verwendung für: Schnelle visuelle Inspektion, Anzeige für Benutzer

JSON-Format

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

Verwendung für: Detailanalyse, syntaxhervorgehobene Überprüfung

Raw-Format

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

Verwendung 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 häufigsten)
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: Agent-Typ, 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 Zeitraum
2. Tracing ist deaktiviert
3. Falscher Projektname
4. API-Schlüssel-Probleme

Lösungen:

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

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

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

# 4. Überprüfen, ob 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 erhalten

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

# Kurzer Check 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. Erkenntnisse dokumentieren

Wenn Sie Fehler finden:

1. Den problematischen Trace exportieren
2. Im Ordner error-cases/ speichern
3. Notieren, was schiefgelaufen ist, 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

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

---

Kurzreferenz

# Häufigste Befehle

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

# Spezifischer 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 Docs: https://docs.langchain.com/
• Dieses Skill-Repository: https://github.com/OthmanAdi/langsmith-fetch-skill

---

Hinweise für Claude

• Stellen Sie immer sicher, dass langsmith-fetch installiert ist, bevor Sie Befehle ausführen
• Überprüfen Sie, ob Umgebungsvariablen gesetzt sind
• Verwenden Sie --format pretty für menschenlesbare Ausgabe
• Verwenden Sie --format json, wenn Sie Daten parsen und analysieren müssen
• Erstellen Sie beim Exportieren von Sitzungen organisierte Ordnerstrukturen
• Geben Sie immer klare Analysen und umsetzbare Erkenntnisse
• Wenn Befehle fehlschlagen, helfen Sie bei der Fehlerbehebung von Konfigurationsproblemen

---

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