DeepSeek Harness AI Agent: Entwicklungsleitfaden

Dieser Leitfaden richtet sich an Entwickler, die mit DeepSeek Harness einen ersten AI Agent aufbauen und später zuverlässig betreiben möchten. Wir führen Sie zeitlich durch die Vorbereitung, den minimalen Aufgabenzyklus, eigene Tools, Zustandsverwaltung, Fehlerbehandlung und die Abnahme vor dem produktiven Einsatz.

Letzte Aktualisierung: 17.08.2026. Die technischen Angaben wurden gegen das offizielle Repository, die dort verlinkte Benutzerdokumentation, die Entwicklungsdokumentation und die DeepSeek-API-Dokumentation geprüft. Im September 2026 sind das offizielle Repository deepseek-ai/deepseek-harness und die CLI dsh öffentlich. Wer die offizielle Runtime installieren und Web / Headless betreiben will, liest DeepSeek Harness dsh Installation. Dieser Text bleibt bei der selbst gebauten Schleife und der Tool-Abnahme; er ersetzt die offizielle CLI-Dokumentation nicht.

Schnellentscheidung

Geeignet: Wenn Sie mit DeepSeek Harness einen kontrollierten Tool-Agent oder Coding Agent entwickeln und zunächst einen klar begrenzten Aufgabenablauf testen möchten. Nicht geeignet: Wenn Sie sofort ein komplexes Multi-Agent-System mit vielen Plugins, dauerhaftem Speicher und paralleler Ausführung erwarten. Dafür fehlt am Anfang die wichtigste Grundlage: ein nachweisbar funktionierender Minimalablauf.

Das offizielle DeepSeek-Harness-Repository bezeichnet das Projekt als Open-Source-Agent-Harness und beschreibt eine Architektur, in der zentrale Funktionen über Plugins bereitgestellt werden. Gleichzeitig befindet sich das Projekt laut README in der Developer Preview. Inkompatible Änderungen sind daher möglich. Unsere Empfehlung ist eindeutig: Prüfen Sie zuerst Modelladapter, Tool-Aufruf, Sitzungsverlauf und Endbedingung in einer kleinen Aufgabe. Danach erweitern Sie schrittweise um Plugins, Speicher und parallele Ausführung.

Diese Anleitung richtet sich an Entwickler, die erstmals mit DeepSeek Harness arbeiten, an Teams mit einem lokalen Agent-Prototyp sowie an technische Verantwortliche, die Tool-Zuverlässigkeit und Aufgabenabschluss bewerten müssen.

Vorbereitung und Aufgabenrahmen

Bevor Sie Code schreiben, legen Sie die kleinste sinnvolle Aufgabe fest. Ein guter erster Test besitzt vier Eigenschaften:

1. Eingabe: ein eindeutig formulierter Auftrag.
2. Werkzeug: genau eine Funktion mit überschaubarem Risiko.
3. Ergebnis: ein prüfbares Artefakt oder eine konkrete Antwort.
4. Endbedingung: ein Zustand, bei dem der Agent sicher stoppen muss.

Ein Beispiel wäre ein Agent, der eine Projektdatei liest, eine strukturierte Zusammenfassung erstellt und diese in eine neue Datei schreibt. Das ist aussagekräftiger als ein allgemeiner „Programmierassistent“, weil jede Phase kontrolliert werden kann.

Wir vermeiden am Anfang Schreibzugriffe auf Produktivdatenbanken, unbeschränkte Shell-Befehle und selbstständige Netzwerkzugriffe. Diese Funktionen erzeugen versteckte Fehlerquellen:

• Berechtigungsrisiko: Ein Tool kann mehr ausführen, als seine Beschreibung vermuten lässt.
• Kontextkosten: Lange Sitzungen blähen die Nachrichtenhistorie auf und erschweren die Fehlersuche.
• Endlosschleifen: Ohne maximale Versuchsanzahl oder Stop-Bedingung kann der Agent dieselbe Aktion wiederholen.
• Zustandsverlust: Ein Neustart kann den Unterschied zwischen „Tool erfolgreich ausgeführt“ und „Ergebnis nur teilweise gespeichert“ verwischen.
• Versionsrisiko: Eine Developer Preview kann Plugin-Schnittstellen, Startbefehle oder interne Abläufe verändern.

Prüfen Sie vor der Installation den aktuellen Standard-Branch, die Release-Hinweise und die Beispiele. Die offizielle Entwicklungsdokumentation nennt derzeit Node.js 22.19 oder neuer beziehungsweise Node.js 24, eine Corepack-fähige pnpm-Installation sowie Git 2.26 oder neuer als Entwicklungsgrundlage. Diese Angaben sind versionsabhängig und sollten vor jedem neuen Setup erneut kontrolliert werden.

Der erste Entwicklungsabschnitt: Umgebung und Start

Die schnellste Route zu einem sichtbaren Ergebnis führt über die Web-Oberfläche. Das offizielle README beschreibt dafür den Start mit:

npx @deepseek-ai/dsh web

Alternativ können Sie das Repository auschecken und den Entwicklungsstand aus dem Quellcode bauen:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Die Web-Oberfläche läuft laut README standardmäßig lokal auf Port 3.080. Das ist kein Leistungsversprechen, sondern lediglich die dokumentierte lokale Startadresse.

Nach dem Start sind vier Komponenten voneinander zu trennen:

• Modelladapter: Er übersetzt Agent-Anfragen in das erwartete API-Format und verarbeitet die Modellantwort.
• Agent-Schleife: Sie entscheidet, ob eine Antwort ausgegeben, ein Tool aufgerufen oder die Aufgabe fortgesetzt wird.
• Nachrichtenhistorie: Sie hält Benutzerauftrag, Assistentenantworten und Tool-Ergebnisse in der richtigen Reihenfolge.
• Aufgabeneinstieg: Er nimmt den Auftrag entgegen, wählt Arbeitsverzeichnis und Berechtigungen und erzeugt die erste Sitzung.

Die offizielle Benutzeranleitung beschreibt einen ähnlichen Ablauf: API-Schlüssel hinterlegen, Arbeitsbereich auswählen, Sitzung starten und eine konkrete Aufgabe senden. Erst nach Auswahl eines Arbeitsbereichs wird der Sitzungseditor verfügbar.

Fünf Schritte für den Minimaltest

1. Arbeitsverzeichnis anlegen: Verwenden Sie ein isoliertes Testprojekt, nicht das produktive Repository.
2. Abhängigkeiten installieren: Führen Sie die dokumentierte Installation aus und prüfen Sie anschließend den Typcheck.
3. API-Zugang getrennt hinterlegen: Speichern Sie den Schlüssel in einer Umgebungsvariable oder einer ignorierten .env-Datei. Niemals in Quelltext oder Git-Historie.
4. Ein Arbeitsverzeichnis auswählen: Der Agent darf nur Dateien sehen, die für den Test erforderlich sind.
5. Eine Aufgabe mit Endbedingung senden: Formulieren Sie Ergebnis und Abbruchkriterium ausdrücklich, etwa „Lese diese Datei, erstelle eine Zusammenfassung und beende die Sitzung nach erfolgreichem Schreiben“.

Für die Quellcode-Variante nennt die Entwicklungsdokumentation pnpm run typecheck als erfolgreichen Prüfpunkt nach einem frischen Checkout. Die dort dokumentierte Umgebungsvariable DEEPSEEK_API_KEY darf nicht in das Repository gelangen.

Tool-Aufrufe und Rückgabeprotokoll

Der wichtigste Übergang vom Chatbot zum AI Agent ist der Tool-Aufruf. Das Modell führt die Funktion nicht selbst aus. Es erzeugt einen strukturierten Vorschlag; die Laufzeit muss diesen validieren, ausführen und das Ergebnis anschließend als Tool-Nachricht zurückgeben. Die DeepSeek-Dokumentation zu Tool-Aufrufen beschreibt diese Abfolge aus Modellantwort, Funktionsausführung und Rückgabe an das Modell.

Ein Tool sollte mindestens diese Eigenschaften besitzen:

• Eindeutiger Name: Nur Buchstaben, Zahlen, Unterstriche oder Bindestriche.
• Kurze Beschreibung: Nicht die interne Implementierung erklären, sondern Zweck, Eingaben und Grenzen.
• JSON-Schema: Datentypen, Pflichtfelder und zulässige Werte definieren.
• Berechtigungsgrenze: Lesen, Schreiben, Prozessstart und Netzwerkzugriff getrennt behandeln.
• Fehlerformat: Fehler als strukturierte Rückgabe liefern, nicht als unkontrollierte Ausnahme.
• Aufruf-ID: Jede Antwort muss eindeutig dem vorherigen Tool-Aufruf zugeordnet werden.

Die API-Dokumentation erlaubt bis zu 128 Funktionen in der tools-Liste. Diese Obergrenze ist kein sinnvolles Ziel für den ersten Agenten. Viele Tools erhöhen die Auswahlunsicherheit und machen Beschreibungsfehler wahrscheinlicher. Für den Minimaltest ist ein einzelnes Werkzeug die bessere Entscheidung. (API-Referenz für Chat Completions)

Ein vereinfachtes Schema für ein Lesewerkzeug kann so aussehen:

{
  "type": "function",
  "function": {
    "name": "read_project_file",
    "description": "Liest eine Datei ausschließlich aus dem freigegebenen Arbeitsverzeichnis.",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Relativer Pfad innerhalb des Arbeitsverzeichnisses."
        }
      },
      "required": ["path"],
      "additionalProperties": false
    }
  }
}

Vor der Ausführung muss Ihre Laufzeit prüfen, ob der Pfad tatsächlich innerhalb des erlaubten Verzeichnisses liegt. Eine gültige JSON-Struktur bedeutet nicht automatisch, dass der angeforderte Zugriff sicher ist.

Für jeden Aufruf speichern wir mindestens:

• Sitzungskennung
• Aufgabenkennung
• Toolname
• übergebene Parameter
• Beginn und Ende
• Ergebnisstatus
• Fehlerklasse und Fehlermeldung
• verwendeter Arbeitsbereich
• nachfolgende Agent-Entscheidung

Generierte Argumente können trotz Schema ungültig sein oder zusätzliche Parameter enthalten. Deshalb müssen Argumente im Anwendungscode validiert werden. Der Aufruf darf erst nach erfolgreicher Prüfung ausgeführt werden.

Aufgabenphasen und Statusverwaltung

Ein langer Agent-Lauf sollte nicht als ein einziger Textblock behandelt werden. Wir teilen ihn in überprüfbare Phasen:

1. Auftrag analysieren
2. benötigte Dateien oder Daten bestimmen
3. Werkzeug ausführen
4. Ergebnis validieren
5. Artefakt erzeugen
6. Ergebnis prüfen
7. Sitzung beenden

Der Status muss nicht den gesamten Gesprächsverlauf ersetzen. Er sollte lediglich festhalten, was für die Wiederaufnahme erforderlich ist:

{
  "phase": "ergebnis_pruefen",
  "last_success": "datei_geschrieben",
  "retry_count": 0,
  "awaiting_approval": false,
  "artifact": "output/summary.md",
  "next_action": "inhalt_validieren"
}

Wir unterscheiden drei Speicherarten:

• Kurzzeitiger Sitzungszustand: aktuelle Nachrichten, laufende Tool-Aufrufe und unmittelbare Entscheidungen.
• Aufgabenartefakte: Dateien, Testergebnisse, Protokolle und Zwischenberichte.
• Langfristiges Wissen: bewusst kuratierte Regeln oder Dokumente, die auch für spätere Aufgaben gelten.

Diese Trennung verhindert, dass jede alte Nachricht wieder in den Kontext geladen wird. Sie erleichtert außerdem Datenschutzprüfungen nach DSGVO. Für die technische Umsetzung sollten Sie festlegen, welche Sitzungsdaten wie lange gespeichert werden und wer sie lesen darf. Ergänzende Hinweise zum Umgang mit personenbezogenen Daten finden Sie in der Datenschutzerklärung von ZekVPS.

Wiederholen, pausieren und fortsetzen

Ein Tool-Fehler ist nicht automatisch ein Grund für einen Neustart. Definieren Sie stattdessen klare Regeln:

• Wiederholen: nur bei vorübergehenden Fehlern, mit begrenzter Anzahl.
• Pausieren: bei fehlenden Zugangsdaten, unklaren Eingaben oder notwendiger Freigabe.
• Abbrechen: bei Berechtigungsverstoß, ungültigem Zustand oder wiederholtem identischem Fehler.
• Fortsetzen: nur aus dem zuletzt dauerhaft gespeicherten erfolgreichen Status.
• Zurücksetzen: wenn Artefakte teilweise geschrieben wurden und keine sichere Prüfung möglich ist.

Besonders bei Coding Agents ist „Datei verändert“ kein ausreichendes Erfolgsmerkmal. Der Agent muss zusätzlich prüfen, ob Formatierung, Tests oder erwartete Ausgabestruktur stimmen.

Übergang vom Prototyp zum Dauerbetrieb

Eine lokale Maschine genügt, wenn eine einzelne Person kurze Tests ausführt, der Agent keine dauerhaften Aufgaben übernimmt und ein Neustart akzeptabel ist. Eine unabhängige, remote erreichbare Umgebung wird sinnvoll, wenn mindestens eine dieser Bedingungen erfüllt ist:

• Aufgaben laufen über längere Zeit ohne aktive Beobachtung.
• Mehrere Personen benötigen denselben reproduzierbaren Stand.
• Ein fehlerhafter Lauf darf den Arbeitsplatz nicht beschädigen.
• Sitzungen müssen nach einem Neustart wiederhergestellt werden.
• Arbeitsbereiche sollen vollständig zurückgesetzt werden können.
• Protokolle und Artefakte müssen dauerhaft verfügbar bleiben.

Für die Bereitstellung empfehlen wir diese Reihenfolge:

1. Abhängigkeiten sperren: Lock-Datei, Node-Version und Paketmanager-Version gemeinsam dokumentieren.
2. Geheimnisse injizieren: API-Schlüssel nur über Umgebungsvariablen oder einen Secret-Speicher bereitstellen.
3. Arbeitsverzeichnisse isolieren: Jede Aufgabe erhält einen eigenen Pfad und eine eigene Berechtigungsgruppe.
4. Protokolle persistieren: Sitzungsereignisse und Tool-Ergebnisse dürfen nicht ausschließlich im Terminal verbleiben.
5. Parallelität begrenzen: Legen Sie maximale gleichzeitige Sitzungen, Tool-Aufrufe und Wiederholungen fest.
6. Reset testen: Löschen Sie eine Testumgebung absichtlich und prüfen Sie, ob sie reproduzierbar neu erstellt werden kann.
7. Zugriffe absichern: Remote-Zugang, Firewall, Benutzerrechte und Datenschutzanforderungen müssen vor dem Teamzugriff geprüft werden.

DeepSeek Harness dokumentiert neben der Web-Oberfläche auch Headless- und Automatisierungsabläufe. Die Entwicklungsdokumentation zeigt dafür einen Headless-Aufruf und weist erneut auf den erforderlichen API-Schlüssel hin.

Entscheidungshilfe für die passende Umgebung

Verwenden Sie die folgende Bedingungsliste statt einer pauschalen Hardwareentscheidung:

• Wenn der Test nur wenige Minuten dauert, ein Entwickler allein arbeitet und ein Verlust des lokalen Zustands akzeptabel ist, dann wählen Sie zunächst lokal.
• Wenn mehrere Sitzungen parallel laufen oder der Agent Dateien verändert, dann wählen Sie eine isolierte Remote-Umgebung.
• Wenn ein Lauf nach Unterbrechung fortgesetzt werden muss, dann wählen Sie persistente Datenträger und externe Protokollspeicherung.
• Wenn ein fehlerhafter Agent keinen Zugriff auf persönliche Dateien erhalten darf, dann wählen Sie ein getrenntes Arbeitsverzeichnis oder eine zurücksetzbare Maschine.
• Wenn Sie physische Geräte, lokale Spezialhardware oder direkte Anschlüsse benötigen, dann prüfen Sie zuerst eine lokale Maschine.
• Wenn mehrere Teammitglieder wiederholt dieselbe Umgebung brauchen, dann vermeiden Sie individuelle Entwicklerrechner als einzige Betriebsplattform.

Unsere Bewertung für einen ersten DeepSeek Harness AI Agent:

Die Bewertungen sind eine technische Entscheidungshilfe, keine offizielle Produktbewertung. Sie ergeben sich aus dem dokumentierten Preview-Status, den vorhandenen Startwegen und den zusätzlichen Anforderungen an Logs, Rechte, Isolation und Wiederherstellung.

Abnahme vor dem produktiven Einsatz

Eine Demo ist bestanden, wenn sie einmal funktioniert. Ein Agent ist abnahmefähig, wenn er eine reale Aufgabenmenge wiederholt kontrolliert bearbeiten kann.

Wir verwenden mindestens diese Prüfpunkte:

1. Aufgabenabschluss: Wird das erwartete Artefakt tatsächlich erzeugt?
2. Tool-Parameter: Sind Pfade, Werte und Pflichtfelder korrekt?
3. Endbedingung: Stoppt der Agent nach Erfolg und nach einem definierten Fehler?
4. Fehlerwiederherstellung: Kann ein unterbrochener Lauf fortgesetzt oder sicher zurückgesetzt werden?
5. Wiederholbarkeit: Liefert dieselbe Eingabe unter denselben Bedingungen vergleichbare Ergebnisse?
6. Berechtigungen: Werden nicht freigegebene Dateien und Aktionen blockiert?
7. Ressourcenverbrauch: Bleiben Sitzungszahl, Protokollvolumen und Prozessanzahl innerhalb der gesetzten Grenzen?
8. Nachvollziehbarkeit: Können Sie aus den Logs rekonstruieren, warum ein Tool gewählt und wie sein Ergebnis verarbeitet wurde?

Für die Bewertung sollten Sie keine künstliche Einzelaufgabe verwenden. Erstellen Sie eine kleine Sammlung aus normalen Fällen, fehlenden Eingaben, ungültigen Parametern, absichtlich fehlschlagenden Tools und abgebrochenen Sitzungen. Erst diese Mischung zeigt, ob der Agent stabil arbeitet.

Die DeepSeek-API unterstützt automatische, verpflichtende und deaktivierte Tool-Auswahl. Außerdem kann im Beta-Modus ein strikteres JSON-Schema verwendet werden. Diese Optionen sind nützlich, ersetzen aber nicht die Validierung in Ihrer Anwendung.

Häufige Fragen

Wie erstelle ich mit DeepSeek Harness den ersten AI Agent?

Beginnen Sie mit einer frischen Projektkopie, installieren Sie die dokumentierten Abhängigkeiten und starten Sie die Web-Oberfläche oder den Headless-Modus. Hinterlegen Sie anschließend den API-Schlüssel, wählen Sie ein Arbeitsverzeichnis und geben Sie eine Aufgabe mit klar definiertem Ergebnis und Endbedingung vor. Erst wenn dieser Ablauf reproduzierbar funktioniert, sollten Sie weitere Plugins hinzufügen.

Wie bindet man ein eigenes Tool in DeepSeek Harness ein?

Ein eigenes Tool benötigt eine eindeutige Beschreibung, einen Namen, ein überprüfbares Parameterschema und eine klar begrenzte Berechtigung. Der Agent erzeugt zunächst einen strukturierten Aufruf; Ihre Laufzeit validiert die Parameter, führt die Funktion aus und gibt das Ergebnis mit einer eindeutigen Aufruf-ID zurück. Fehler dürfen nicht verschleiert, sondern müssen als maschinenlesbares Ergebnis protokolliert werden.

Wie speichert ein Agent während der Aufgabenausführung seinen Status?

Trennen Sie Gesprächsverlauf, laufenden Aufgabenstatus und erzeugte Dateien. Im Status sollten mindestens die aktuelle Phase, die letzte erfolgreiche Aktion, offene Versuche, erforderliche Bestätigungen und der Pfad zu den Ergebnissen stehen. Speichern Sie diese Informationen außerhalb des flüchtigen Kontexts, damit ein unterbrochener Lauf nach einem Neustart kontrolliert fortgesetzt oder sicher zurückgesetzt werden kann.

Eignet sich DeepSeek Harness für einen Coding Agent?

Ja, für kontrollierte Entwicklungsaufgaben ist DeepSeek Harness grundsätzlich geeignet, weil der Agent Arbeitsdateien lesen und verändern, Befehle ausführen und einen Plan verwalten kann. Für dauerhafte Teamnutzung reicht eine lokale Demo jedoch nicht aus. Sie benötigen isolierte Arbeitsverzeichnisse, begrenzte Berechtigungen, persistente Protokolle, reproduzierbare Abhängigkeiten und eine Testmenge für wiederholbare Abnahmen.

Lokale Maschine oder gemietete Mac-Umgebung?

Ein lokaler Rechner ist für den ersten Test oft die vernünftigste Wahl. Er ist sofort verfügbar und verursacht keine zusätzliche Bereitstellungsarbeit. Für längere Coding-Agent-Läufe entstehen jedoch typische Nachteile: Der persönliche Arbeitsplatz bleibt blockiert, Sitzungen hängen an lokalen Einstellungen, Neustarts unterbrechen Aufgaben und mehrere Teammitglieder arbeiten nicht mit demselben Ausgangszustand.

Eine gemietete Mac-Umgebung ist deshalb interessanter, wenn Sie DeepSeek Harness nur für eine begrenzte Entwicklungsphase, reproduzierbare Tests oder gemeinsam genutzte Agent-Aufgaben benötigen. Sie erhalten einen getrennten Arbeitsplatz, können die Umgebung für einen Versuch sauber vorbereiten und müssen nicht dauerhaft eigene Hardware für ein noch instabiles Preview-Projekt reservieren.

Das ist kein Argument gegen den lokalen Rechner. Für kurze Experimente bleibt er die bessere Option. Wenn Aufgaben jedoch über längere Zeit laufen, mehrere Personen beteiligt sind oder ein vollständiger Reset wichtig ist, sind Isolation, Remote-Zugriff und wiederholbare Bereitstellung wichtiger als die Bequemlichkeit einer einzelnen lokalen Installation. Für die Auswahl eines passenden Mac-Arbeitsplatzes können Sie die verfügbaren Mac-Umgebungen von ZekVPS prüfen und anschließend die Anforderungen aus dieser Anleitung dagegenhalten.