AI-Entwicklung

Was ist ein Agent Harness im AI Coding Agent? Model, Harness, Tools und JSON State (2026)

Ca. 16 Min.

Der DeepSeek-Text behandelte einen Produkthost. Dieser Text teilt die vier allgemeinen Schichten: Model, Harness, Tools, JSON State. Das Modell füllt Argumente. Der Host läuft die Schleife. Tools passieren Schema. State lässt sich wiedergeben.

Vor dem Lesen

Schicht Was sie sperrt Wer ausführt
Model tool_use / arguments Das Modell füllt JSON; es führt keine Nebenwirkungen aus
Harness Schleife / Rechte / Kompakt Der Host baut Kontext, dann führt er aus
Tools inputSchema Schema ist das Tor; der Host ruft dann
State session / turn / JSONL Nicht rekonstruierbar ist kein State

Vier Schichten sind Objekte. Ein Prompt ist keine Architektur.

Ein Harness ist die Schleife, nicht das Modell

Ein Coding Agent 2026 sieht aus wie „ein Modell ändert ein Repo“. Geteilt sind es vier Objekte. Das Modell gibt nur die nächste Aktion als JSON aus. Das Harness lädt Kontext, prüft Schema, bewertet Rechte, führt Tools aus, schreibt Ergebnisse zurück und verdichtet Geschichte, wenn das Fenster voll wird. Ohne diese Schleife ist das Modell ein Chat. Die offizielle Schleife von Claude Code ist dieselbe Tatsache: Prompt empfangen, bewerten, Tools ausführen, wieder bewerten, bis keine Tool-Aufrufe mehr kommen. Codex schreibt Kontinuität in einen Thread und eine Session-Akte. Cursor ist ebenfalls eine Host-Schleife. Das Modell berührt die Platte nicht.

  • Model: füllt lookup_order und A-1042. Es sieht den Socket nicht und startet keinen Prozess.
  • Harness: Systemprompt, Tool-Tabelle, Rechte, Verdichtung, Budget, max_turns. Das ist Host-State, nicht Modellgewicht.
  • Tools und State: Tools haben Schema. Die Session hat prüfbares JSON. Chattext ist kein State.

Wie eingebaute Tools JSON füllen: AI-Coding-Agents und JSON-Toolaufrufe. Der MCP-Sprung: Wie Coding Agents MCP rufen. Warum Schema ein Tor ist: Warum KI JSON Schema braucht. Der Plugin-Host eines Produkts: DeepSeek-Harness-Text. Dieser Text erzählt jenes Produkt nicht neu. Er stapelt nur die vier Schichten.

Schicht eins: das Modell füllt nur JSON

Das Modell sieht die Tool-Tabelle des Hosts und die Nachrichten bisher. Die Ausgabe ist Text, ein Tool-Aufruf oder beides. Fiktive Abfrage — keine echten Geheimnisse:

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "lookup_order",
  "input": { "order_id": "A-1042" }
}

Dieses Objekt ist kein HTTP und kein MCP-tools/call. Es ist das Modell, das dem Host sagt „sieh A-1042 nach“. Der Host prüft die Form und lässt zu oder sperrt. Wer das Modell als Ausführer sieht, verpasst diesen Sprung.

Schicht zwei: das Harness läuft die Schleife

Eine Session ist eine Zustandsmaschine, keine einzelne Vervollständigung. Die offizielle Schleife passt in ein Objekt: unveränderlich Modellname und Tool-Tabelle; veränderlich Nachrichtenanzahl, wartendes Tool, Budget. Runde 2 von 8 zählt der Host. Das Modell führt kein Tagebuch:

{
  "session_id": "sess_7f2a",
  "turn": 2,
  "max_turns": 8,
  "immutable": {
    "model": "coding-agent",
    "tools": ["lookup_order", "Read", "Bash"]
  },
  "mutable": {
    "messages": 6,
    "pending_tool": "lookup_order",
    "budget_tokens": 128000
  }
}

Eine Claude-Code-Runde: das Modell gibt eine Antwort mit Tools aus, der Host führt aus, schreibt tool_result zurück und fragt erneut. Ohne Tool-Aufrufe endet die Schleife und liefert Verbrauch plus session_id. Hooks können vor der Ausführung eingreifen. Codex wählt nach Freigabe eine Sandbox und führt dann aus. Rechte als Regeln: Rechtemodell des Coding Agents. Das Harness ruft Rechte auf. Es ist nicht das Recht.

Schicht drei: Tools passieren Schema

Die Tool-Tabelle ist das Menü des Modells. Jede Zeile braucht Name, Beschreibung und ein JSON Schema. Ein weites object lädt erfundene Schlüssel ein. Eine Abfrage trägt keine Erstattungsfelder:

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Nach dem Tor führt der Host aus und speist das Ergebnis als Objekt zurück. Das Modell liest die Rückschrift, nicht den Terminalscroll. Ein Fehler ist ebenfalls ein Objekt. Keinen Prosasatz fallen lassen:

{
  "type": "tool_result",
  "tool_use_id": "call_3c91",
  "content": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}"
}

Schicht vier: JSON State lässt sich wiedergeben

State ist nicht „worüber wir gerade gesprochen haben“. State sind Nachrichten, Tool-Ergebnisse, eine Session-Id, Verdichtungsgrenzen. Codex hängt die Session als JSONL an und baut bei resume neu auf. Eine Zeile soll eine Abfrage treffen:

{"ts":"2026-09-28T01:12:04.221Z","type":"tool_result","id":"call_3c91","name":"lookup_order","ok":true,"order_id":"A-1042"}

Kontext füllt sich. Claude Code verdichtet nahe der Grenze automatisch und sendet compact_boundary im Strom. Frühe Details können in der Zusammenfassung verschwinden. Das CLAUDE.md im Projektstamm wird erneut eingelegt, deshalb gehören dauerhafte Regeln in eine Datei, nicht nur in den ersten Prompt. Verdichtung ist ein Zustandswechsel, kein stilles Vergessen:

{
  "type": "system",
  "subtype": "compact_boundary",
  "session_id": "sess_7f2a"
}

Fünf Schritte zu einem Harness, das man zeigen kann

Beginnen Sie nicht mit „stärkeres Modell einsetzen“. Schreiben Sie Objekte:

  1. Zuerst die Tool-Tabelle listen. Jedes Tool hat ein Schema. additionalProperties: false. Kein Tool ohne Schema an das Modell geben.
  2. Die Stoppbedingung schreiben. max_turns oder ein Budget. Offene Aufgaben nicht nackt laufen lassen.
  3. Rechte als Regeln schreiben. Nur-Lesen-Abfrage allow. Schreiben ask. Erstattung deny. „Alles genehmigen“ ist kein Tagesdefault.
  4. State als JSON landen. Mindestens tool_use, tool_result, session_id. Stimmen die Ids, ist die Schleife verbunden.
  5. Compact als Ereignis behandeln. Compact heißt: eine Zusammenfassung hat ältere Nachrichten ersetzt. Regeln, die überleben müssen, liegen auf der Platte.

Wie Schema als Tor wirkt: Agents API + JSON Schema. Dieser Text verlangt nur vier Schichten als Objekte, mit dem Host an den Nebenwirkungen.

Zum Debuggen vier JSON-Objekte ausbreiten

Die meisten Fehler sind Tool-Tabelle, Recht oder State außer Reihe — nicht ein Modell, das „nicht klug genug“ ist.

  • formatieren von inputSchema und input. Fehlende Felder und Extra-Schlüssel suchen.
  • Mit JSONPath extrahieren $.name, $.input.order_id, $.session_id ziehen.
  • JSON Diff einer erfolgreichen Rückschrift und einer Ablehnung. Zuerst Schema und Regeln, danach Prompts.
  • Prüfen, dass call_3c91 auf tool_use und tool_result dieselbe Id ist.
  • Session-JSONL, Tokens und Repopfade nicht in einen öffentlichen Formatter kleben. JSONSort läuft im Browser.

Wenn alle vier Objekte gegen Schema neu gebaut werden, sammeln Sie Architektur — nicht den Satz „es schien Dateien zu ändern“.

Häufige Fallen

  • Das Harness für ein neues Modell halten. Modelle rotieren. Schleife, Tore und State zuerst stabilisieren. Schiefe Evals beginnen hier.
  • Einen längeren Systemprompt Architektur nennen. Prompts werden verdichtet. Tool-Tabelle, Rechte und Session-Akte nicht.
  • Schema überspringen und ausführen. Das Harness besitzt die Schleife. Es erspart keine zweite Prüfung. Ein weites object schickt erfundene Schlüssel in Nebenwirkungen.
  • Das Chatfenster für State halten. Das Fenster ist eine Darstellung. State ist JSON. Resume liest die Akte, kein Bildschirmfoto.
  • Compact als Nicht-Ereignis behandeln. Offizielle Clients senden ein Grenzereignis. Verschachtelte Regeln brauchen oft ein erneutes Lesen der Datei.
  • Plugin-Wörter eines Produkts als Gattungswörter nutzen. dsh und Capability Seam gehören zu jenem Produkttext. Die vier allgemeinen Schichten sind Model / Harness / Tools / State.

FAQ

Ist ein Harness dasselbe wie ein Agent-Framework?

Nicht dieselbe Schicht. Ein Framework orchestriert oft Knoten in einem Geschäftsrepo. Ein Harness ist die Host-Schleife: Kontext laden, Tore passieren, ausführen, State halten. Sie dürfen einen Geschäftsagenten auf einem Harness schreiben. Die zwei Schichten nicht vermengen.

Ändert das Modell Dateien selbst?

Nein. Das Modell füllt nur Tool-JSON. Lesen, Schreiben, Shell und MCP führt der Host aus. Kein Host, keine Repoänderung.

Muss JSON State JSONL sein?

Nein. Codex nutzt Session-JSONL als maßgebliche Akte. Claude Code nutzt Transkripte und einen Ereignisstrom. Die Anforderung ist, per Id zu rekonstruieren, was das Modell sah — nicht eine Dateiendung.

Wirft die Verdichtung Schema weg?

Tooldefinitionen werden meist als stabiles Präfix erneut eingelegt. Wegfällt frühes Gesprächsdetail. Regeln, die überleben müssen, gehören in eine Projektdatei, nicht nur in die erste Nutzernachricht.

Schreibe ich das Harness neu, wenn ich das Modell tausche?

Das sollten Sie nicht. Der Modelladapter darf wechseln. Tool-Schema, Rechtetabelle und State-Form sollen halten. Ein Modelltausch tauscht die Schicht, die JSON füllt, nicht die Vier-Schichten-Architektur.

Fazit

Die Architektur eines Coding Agents ist nicht „ein größeres Modell“. Das Modell füllt JSON. Das Harness läuft die Schleife. Tools passieren Schema. State lässt sich wiedergeben.

Schreiben Sie, welches Tool, welche Runde und welche State-Akte A-1042 betritt. Können Sie vier Objekte zeigen, haben Sie ein Harness. Modelle rotieren. Stabilisieren Sie zuerst die vier Schichten.

Weiterlesen

Änderungsprotokoll: Erstveröffentlichung