Fünf Ingenieurpatronen von Agenten, die sich lohnen, von DeepSeek’s Harness zu übernehmen
Event-Log als Wahrheitsquelle, gestufte Schleifenwarnungen, explizite Trunkierung, kodierter Modus mit Berechtigungsprüfung sowie Übertragung an neue Agenten – fünf Muster zur Erstellung von debugfähigen Agentensystemen.
Quellen: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness
Agenten werden immer besser darin, Code zu schreiben, Tools aufzurufen, Dateien zu durchsuchen und langwierige Aufgaben durchzuziehen. Darunter verbirgt sich jedoch ein noch gravierenderes Problem: Was verhindert, dass ein Agent unübersichtlich, unvorhersehbar und nahezu unmöglich zu debuggen wird? Eine Durchsicht der ingenieurtechnischen Entscheidungen in DeepSeeks Open-Source-Agent-Plattform bringt fünf Ansätze zum Vorschein, die es lohnt, zu übernehmen – auch wenn man die Plattform selbst nie verwendet. Es handelt sich dabei weniger um DeepSeek-spezifische Tricks als vielmehr um grundsätzliche Prinzipien für Agentensysteme im Allgemeinen.
1. Machen Sie das Ereignisprotokoll zur Quelle der Wahrheit
Die meisten Agentensysteme speichern das Gespräch in einer Liste, die an das Modell übergeben wird:
messages = [...]
An anderer Stelle notiert ein Forstarbeiter, was geschehen ist:
logger.info({
"messages": messages,
"tool_calls": tool_calls,
"tokens": tokens
})
Das scheint vernünftig zu sein, doch es erzeugt zwei Beschreibungen derselben Ereignisse – und das ist der riskante Aspekt. Angenommen, die Anwendung bearbeitet die Nachrichtenliste vor dem Versenden, zum Beispiel indem sie eine zusätzliche Anweisung einfügt:
messages.append({
"role": "system",
"content": "Remember to be concise."
})
Falls das Ereignisprotokoll diese Änderung niemals aufgezeichnet hat, hat das Modell etwas gesehen, von dem Ihre Protokolle nichts wissen. Sechs Stunden später handelt der Agent seltsam, und Sie öffnen die Protokolle und fragen sich, warum. Die Erklärung könnte eine Systemnachricht sein, die in der aufgezeichneten Historie nirgends erscheint.
Der bessere Ansatz
Machen Sie das Ereignisprotokoll zur einzigen Quelle der Wahrheit. Es enthält die Fakten – wie den Antrag des Benutzers, jeden Toolaufruf, jedes Ergebnis sowie die Antworten des Assistenten:
events = [
UserMessage("Fix the authentication bug"),
ToolCall("grep", {"query": "auth"}),
ToolResult("Found 12 matches"),
AssistantMessage("I'll inspect the middleware")
]
Der Kontext des Modells wird anschließend aus diesen Ereignissen abgeleitet und nicht als separate Liste aufbewahrt:
def build_context(events):
return [
event.to_message()
for event in events
if event.visible_to_model
]
Der Punkt ist, dass es kein privates, verstecktes Nachrichtenarray gibt. Man berechnet es jedes Mal neu. Vergleichen Sie die beiden Strukturen. Die bevorzugte Variante verläuft vom Log über einen Context Builder bis zur Anfrage:
Event Log
↓
Context Builder
↓
LLM Request
Die Variante, die man vermeiden sollte, teilt das Protokoll auf – wobei eine Abteilung die Protokolle und eine andere die an das Modell gesendeten Nachrichten enthält:
Event Log ─────────→ Logs
\
→ Messages ─→ LLM
Diese kleine strukturelle Änderung macht das Debuggen erheblich einfacher.
Gehen Sie noch einen Schritt weiter und überprüfen Sie es
Während der Entwicklung können Sie eine Überprüfung hinzufügen, die den erwarteten Kontext aus dem Protokoll neu erstellt und ihn mit dem vergleicht, was tatsächlich gesendet werden soll:
expected = build_context(event_log)
actual = request.messages
if actual != expected:
raise RuntimeError(
"log-reconstruction desync"
)
Sobald das umgesetzt ist, wird das „Driften im Kontext“ zu einem fehlerhaften Test und nicht mehr zu einem rätselhaften Produktionsfehler. Es gibt sogar einen Bonus: Die Beobachtbarkeit wird deutlich nützlicher. Wenn eine Trajektorienansicht Modelleinsätze, Werkzeugeinsätze, Werkzeugergebnisse, Tokenverbrauch und Zeitangaben anzeigt, muss niemand eine separate Darstellung dessen erstellen, was passiert ist – die Informationen sind bereits vorhanden: Der Agent benötigt sie, um seinen eigenen Kontext wiederherzustellen. Eine einzige Quelle der Wahrheit erfüllt somit zwei Funktionen.
2. Blockieren Sie Agentenschleifen nicht sofort strikt
Jeder Agent-Entwickler stößt früher oder später darauf. Das Modell führt dieselbe Suche immer wieder aus:
grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...
Das Problem ist offensichtlich, und die klare Lösung ist genauso offensichtlich: wiederholte Anrufe ablehnen.
if previous_call == current_call:
raise LoopError()
Das Problem ist, dass Wiederholungen manchmal berechtigt sind. Eine Netzwerkanfrage kann fehlschlagen, eine Datei hat sich geändert, und es ist tatsächlich ein Neversuch notwendig. Anstatt das Modell zu blockieren, sollte man es warnen.
Stellen Sie sich ein Drucksystem vor, das mit der Anzahl der Wiederholungen zunimmt:
3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder
Die erste Ebene könnte angeben, dass derselbe Toolaufruf wiederholt wird, und vorschlagen, das letzte Ergebnis erneut zu lesen:
if repeat_count >= 3:
inject(
"You are repeating the same tool call. "
"Re-read the last result and consider another approach."
)
Die zweite Stufe ist strenger und weist den Agenten an, anzuhalten und neu zu bewerten:
if repeat_count >= 5:
inject(
"You have repeated this exact operation several times. "
"Stop and reassess the approach."
)
In Schritt drei heißt es, es handele sich dabei um einen Kreislauf, der Ansatz müsse geändert werden, oder die Arbeit sollte abgeschlossen werden:
if repeat_count >= 8:
inject(
"This appears to be a loop. "
"Change your approach or wrap up."
)
Achten Sie darauf, was das Harness nicht tut. Es gibt niemals eine klare Ablehnung wie diese zurück:
return False
Die Kontrolle bleibt beim Modell. Der Harness liefert lediglich zusätzliche Informationen und ermöglicht es dem Modell, zu entscheiden – das ist ein wichtiger Unterschied.
Echte Wiederholungen zählen
Ein guter Detektor lässt sich nicht durch dazwischengeschobene, unverwandte Aufrufe täuschen. Diese Abfolge sollte dennoch als Wiederholung gezählt werden:
grep foo
todo update
grep foo
Andernfalls könnte das Modell seinen eigenen Zähler durch sinnlose Arbeit zwischen identischen Aufrufen zurücksetzen. Die Argumente sollten ebenfalls normalisiert werden, sodass diese beiden als dieselbe Operation gelten:
{"query": "foo", "path": "src"}
und:
{"path": "src", "query": "foo"}
Die Reihenfolge der Schlüssel in einem Wörterbuch sollte keine Rolle spielen. Ablaufende Anrufe sollten ebenfalls berücksichtigt werden. Wenn das Modell weiterhin solche Versuche unternimmt:
run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied
Dann ist genau der Moment, in dem es erkennen muss, dass es klug sein könnte, aufzuhören zu versuchen.
Das allgemeine Muster
Der schwache Ansatz ist eine unüberlegte Reaktion auf schlechtes Verhalten:
Bad behavior → hard block
Eines mit stärkerer Leistung erkennt das Verhalten, erhöht die Rückkopplung und ermöglicht es dem Modell, sich zu erholen:
Bad behavior
↓
Detect
↓
Increase feedback
↓
Let model recover
Es handelt sich um eine täuschend einfache Idee, die in nahezu jedes Agentenframework passt, das Toolaufrufe ermöglicht.
3. Teilen Sie dem Modell mit, was es nicht gesehen hat
Das klingt offensichtlich, doch viele Tools machen den Fehler. Angenommen, ein Repository enthält Folgendes:
4,000 files
und ein Suchwerkzeug gibt nur Folgendes zurück:
100 files
Falls die Antwort einfach nur diese hundert Dateien sind, könnte das Modell zu dem Schluss kommen, dass genau hundert Dateien übereinstimmen. Tatsächlich sagte das Tool „Hier sind hundert, weil ich aufgehört habe zu suchen“, und die beiden Bedeutungen sind völlig unterschiedlich.
Machen Sie die Trunkierung explizit
Eine bessere Antwort erklärt, was passiert ist und wo der Rest zu finden ist:
Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt
Das Modell weiß jetzt drei Dinge: Es existieren mehr Ergebnisse, das, was es hat, ist nur ein Teilmenge, und die vollständige Liste ist bei Bedarf erreichbar. Das ist eine viel sicherere Position.
Stichprobenentnahme kann besser sein als das Nehmen der ersten N
Nehmen wir an, es gibt 4.000 Dateien und Platz für 100. Die naive Methode ist ein einfacher Ausschnitt:
results[:100]
Sortierte Ergebnisse können gefährlich sein, da man aus einem Verzeichnis oder einem Nammungsmuster Hunderte von Dateien erhalten kann. Die Verteilung der Beispiele über die gesamte Liste ist informativer:
def sample_results(results, limit=100):
step = len(results) / limit
return [
results[int(i * step)]
for i in range(limit)
]
Der genaue Algorithmus ist weniger wichtig als das Prinzip: Lassen Sie niemals zu, dass das Modell das Existierende mit dem verwechselt, was die Tool angezeigt hat.
Fehler erfordern dieselbe Sorgfalt
Auch Tool-Fehler können einen Agenten in die Irre führen. Angenommen, ein Befehl wird durch eine Sicherheitsrichtlinie blockiert. Eine solch einfache Nachricht ist unzureichend:
Permission denied
Weil das Modell entscheiden könnte, dass seine Syntax falsch ist, und dann immer wieder versuchen würde. Eine weitaus bessere Nachricht ist eine explizite:
Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.
Das ist mehr als nur eine freundlichere Nachricht – es handelt sich um Anleitungen für den Agenten. Ihre Tools leisten mehr als nur die Ausführung von Operationen, da sie mit einem anderen Reasoning-System kommunizieren. Die Ausgabe der Tools sollte eine Frage beantworten: Was muss das Modell wissen, um seine nächste Entscheidung richtig zu treffen?
4. Die Ausführung von Code darf keine Berechtigungen umgehen
Ein weiteres Muster in modernen Agentensystemen ist der Code-Modus. Anstatt pro Runde nur einen Toolaufruf zuzulassen, stellen Sie dem Modell eine Programmierumgebung zur Verfügung:
files = search("authentication")
for file in files:
content = read_file(file)
print(analyze(content))
Das ist leistungsstark. Während die übliche Schleife Runde für Runde zwischen Aufruf des Modells und des Tools wechselt:
LLM
↓
search
↓
LLM
↓
read
↓
LLM
↓
read
↓
LLM
↓
read
Der Code-Modus ermöglicht es dem Modell, ein Programm auszuführen, das viele Aufrufe vornimmt und eine Zusammenfassung zurückgibt:
LLM
↓
run_code(...)
↓
50 tool calls
↓
summary
Das kann die Hin- und Rückwege sowie den Kontextverbrauch erheblich verringern, doch es wirft eine ernste Sicherheitsfrage auf.
Wer überprüft die Aufrufe innerhalb des Programms?
Ihre herkömmliche Architektur leitet jede Modellaktion über eine Berechtigungsstufe, bevor sie ein Tool erreicht:
Model
↓
Permission Layer
↓
Tool
Fügt man Codeausführung unvorsichtig hinzu, kann der Code direkt auf Tools zugreifen:
Model
↓
Code
↓
Tool
Falls das der Fall ist, haben Sie eine Hintertür in Ihr Berechtigungssystem eingebaut, was eindeutig schlecht ist. Eine richtige Gestaltung sorgt dafür, dass alle Aufrufe des Programms denselben Sicherheitsweg nutzen:
Model
↓
run_code
↓
Program
↓
Permission Layer
↓
Tool
Jeder Aufruf eines Tools durchläuft weiterhin denselben Ablauf. Konzeptionell prüft die Datei-Lese-Funktion selbst vor dem Ausführen jeglicher Aktion die Berechtigungen:
def read_file(path):
permission = check_permission(
operation="read",
path=path
)
if not permission.allowed:
raise PermissionError(
"File access denied"
)
return actual_read(path)
Der Codeinterpreter erhält keine spezielle Version der Funktion. Er bekommt dieselbe, die auch alle anderen verwenden.
Abweisungen in normale Programmfehler umwandeln
Ein noch feinerer Punkt folgt. Wenn ein Programm versucht, etwas zu tun, was ihm nicht erlaubt ist:
try:
delete_file("/important/file")
except PermissionError as e:
print(e)
Es sollte einen normalen, fängbaren Fehler erhalten. Es darf nicht endlos hängen bleiben:
hang forever
Es sollte nicht stillschweigend ein leeres Ergebnis erhalten:
return None
Und es sollte sich nicht so verhalten, als wäre nichts passiert:
pretend nothing happened
Das Programm muss erkennen, dass die Operation fehlgeschlagen ist – was besonders wichtig ist, wenn das Modell Programme im Echtzeitmodus erstellt. Der Code-Modus ist gerade deshalb mächtig, weil er dem Modell mehr Kontrolle gibt; das bedeutet, dass die Berechtigungsregeln strenger und nicht schwächer werden müssen.
5. Manchmal ist die beste Strategie für den Kontext keiner
Das ist eine Idee, die mehr Entwickler von Agenten ausprobieren sollten. Langlaufende Agenten sammeln enorme Mengen an Konversationshistorie an. Zuerst hilft das, doch später wird es zu einem Belastungsfaktor. Am Ende erhält man eine Kette von Runden, die einen riesigen Kontext versorgen müssen:
Round 1
↓
Round 2
↓
Round 3
↓
Round 4
↓
Round 5
↓
Huge context
Nun konzentriert sich das Modell darauf, seine eigene Vergangenheit erneut durchzugehen, anstatt die Aufgabe zu lösen. Zusammenfassung ist ein Heilmittel, aber es gibt noch eines: Das Gespräch beenden und den Arbeitsbereich beibehalten.
Nehmen wir eine Programmieraufgabe, die fünf Runden umfasst. In Runde eins inspiziert der erste Agent das Repository, vornimmt Änderungen, speichert seine Arbeit und schreibt eine Übergabeanmerkung:
Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff
Die zweite Runde beginnt mit einem völlig neuen Agenten, der den Arbeitsbereich sowie die Übertragung auswertet und fortfährt:
Agent B
→ read workspace
→ read handoff
→ continue
Es gibt keine umfangreiche Geschichte, keine veralteten Argumente und keinen angesammelten „Rauschen“ durch Tools. Es gibt nur den aktuellen Zustand.