claude-to-deerflow

DeerFlow Skill

Kommuniziere mit einer laufenden DeerFlow-Instanz über deren HTTP-API. DeerFlow ist eine KI-Agentenplattform, die auf LangGraph aufbaut und Unter-Agenten für Recherche, Code-Ausführung, Web-Browsing und mehr orchestriert.

Architektur

DeerFlow stellt zwei API-Oberflächen hinter einem Nginx-Reverse-Proxy bereit:

Service	Direkter Port	Über Proxy	Zweck
Gateway-API	8001	$DEERFLOW_GATEWAY_URL	REST-Endpunkte und eingebettete Agenten-Laufzeit
LangGraph-kompatible API	8001	$DEERFLOW_LANGGRAPH_URL	Agent-Threads, Runs, Streaming

Umgebungsvariablen

Alle URLs sind über Umgebungsvariablen konfigurierbar. Lies diese Umgebungsvariablen, bevor du eine Anfrage stellst.

Variable	Standard	Beschreibung
DEERFLOW_URL	http://localhost:2026	Einheitliche Proxy-Basis-URL
DEERFLOW_GATEWAY_URL	${DEERFLOW_URL}	Gateway-API-Basis (Modelle, Skills, Speicher, Uploads)
DEERFLOW_LANGGRAPH_URL	${DEERFLOW_URL}/api/langgraph	LangGraph-API-Basis (Threads, Runs)

Wenn du curl-Aufrufe tätigst, löse die URL immer so auf:

# Basis-URLs aus Umgebungsvariablen auflösen (mache dies zuerst VOR jedem API-Aufruf)
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"

Verfügbare Operationen

1. Gesundheitstest

Prüfe, ob DeerFlow läuft:

curl -s "$DEERFLOW_GATEWAY_URL/health"

2. Nachricht senden (Streaming)

Dies ist die primäre Operation. Sie erstellt einen Thread und streamt die Antwort des Agenten.

Schritt 1: Thread erstellen

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
  -H "Content-Type: application/json" \
  -d '{}'

Antwort: {"thread_id": "<uuid>", ...}

Schritt 2: Run streamen

curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "lead_agent",
    "input": {
      "messages": [
        {
          "type": "human",
          "content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
        }
      ]
    },
    "stream_mode": ["values", "messages-tuple"],
    "stream_subgraphs": true,
    "config": {
      "recursion_limit": 1000
    },
    "context": {
      "thinking_enabled": true,
      "is_plan_mode": true,
      "subagent_enabled": true,
      "thread_id": "<thread_id>"
    }
  }'

Die Antwort ist ein SSE-Stream. Jedes Ereignis hat das Format:

event: <ereignistyp>
data: <json_daten>

Wichtige Ereignistypen:

• metadata — Run-Metadaten inklusive run_id
• values — Vollständiger Zustandsschnappschuss mit messages-Array
• messages-tuple — Inkrementelle Nachrichtenaktualisierungen (KI-Textblöcke, Tool-Aufrufe, Tool-Ergebnisse)
• end — Stream ist abgeschlossen

Kontextmodi (über context gesetzt):

• Flash-Modus: thinking_enabled: false, is_plan_mode: false, subagent_enabled: false
• Standard-Modus: thinking_enabled: true, is_plan_mode: false, subagent_enabled: false
• Pro-Modus: thinking_enabled: true, is_plan_mode: true, subagent_enabled: false
• Ultra-Modus: thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

3. Unterhaltung fortsetzen

Um Folgenachrichten zu senden, verwende die gleiche thread_id aus Schritt 2 erneut und sende einen weiteren Run mit der neuen Nachricht.

4. Modelle auflisten

curl -s "$DEERFLOW_GATEWAY_URL/api/models"

Gibt zurück: {"models": [{"name": "...", "provider": "...", ...}, ...]}

5. Skills auflisten

curl -s "$DEERFLOW_GATEWAY_URL/api/skills"

Gibt zurück: {"skills": [{"name": "...", "enabled": true, ...}, ...]}

6. Skill aktivieren/deaktivieren

curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

7. Agenten auflisten

curl -s "$DEERFLOW_GATEWAY_URL/api/agents"

Gibt zurück: {"agents": [{"name": "...", ...}, ...]}

8. Speicher abrufen

curl -s "$DEERFLOW_GATEWAY_URL/api/memory"

Gibt Benutzerkontext, Fakten und Zusammenfassungen des Gesprächsverlaufs zurück.

9. Dateien in einen Thread hochladen

curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
  -F "files=@/pfad/zu/datei.pdf"

Unterstützt PDF, PPTX, XLSX, DOCX – wird automatisch in Markdown konvertiert.

10. Hochgeladene Dateien auflisten

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"

11. Thread-Verlauf abrufen

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"

12. Threads auflisten

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'

Nutzungsskript

Verwende das Hilfsskript zum Senden von Nachrichten und Sammeln der vollständigen Antwort:

bash /pfad/zu/skills/claude-to-deerflow/scripts/chat.sh "Deine Frage hier"

Siehe scripts/chat.sh für die Implementierung. Das Skript:

1. Prüft die Gesundheit
2. Erstellt einen Thread
3. Streamt den Run und sammelt die finale KI-Antwort
4. Gibt das Ergebnis aus

SSE-Ausgabe parsen

Der Stream gibt SSE-Ereignisse zurück. Um die finale KI-Antwort aus einem values-Ereignis zu extrahieren:

• Suche nach dem letzten event: values-Block
• Parse dessen data-JSON
• Das messages-Array enthält alle Nachrichten; die letzte mit type: "ai" ist die Antwort
• Das content-Feld dieser Nachricht ist die Textantwort der KI

Fehlerbehandlung

• Wenn der Gesundheitstest fehlschlägt, läuft DeerFlow nicht. Informiere den Benutzer, dass er es starten muss.
• Wenn der Stream ein Fehlerereignis zurückgibt, extrahiere und zeige die Fehlermeldung an.
• Häufige Probleme: Port nicht geöffnet, Dienste starten noch, Konfigurationsfehler.

Tipps

• Für schnelle Fragen verwende den Flash-Modus (schnellste, keine Planung).
• Für Recherche-Aufgaben verwende den Pro- oder Ultra-Modus (ermöglicht Planung und Unter-Agenten).
• Du kannst zuerst Dateien hochladen und dann in deiner Nachricht darauf verweisen.
• Thread-IDs bleiben bestehen – du kannst später zu einer Unterhaltung zurückkehren.