← Blog
Aus der Praxis20 Min. Lesezeit

Warum ich meinen eigenen AI Agent von Grund auf neu geschrieben habe?

Eine Neuschreibung ließ mich Zustand, Kontext und Systemgrenzen neu verstehen.

Translated by AI
Der Entwickler zerlegte den komplexen quallenförmigen Agenten und reorganisierte die Module für Gedächtnis, Nachrichten und Workflow.
Der Ausgangspunkt der Neuschreibung war das erneute Verständnis dafür, welche Verantwortung jedes Modul tragen sollte.

Als ich zum ersten Mal die Hauptkette des Agenten zum Laufen brachte, dachte ich, der schwierigste Teil sei vorbei.

Das Modell konnte aufgerufen werden, Daten konnten in die Datenbank geschrieben werden, Vektoren konnten abgerufen werden, und der Workflow lief reibungslos bis zum Ende. Für jemanden, der zum ersten Mal ein vollständiges Projekt mit LangGraph umsetzte, war das aufregend genug für eine Weile.

Doch erst als ich ihn wirklich kontinuierlich nutzte, tauchten die Probleme einzeln auf: Obwohl ein Checkpoint konfiguriert war, wusste das Modell in der nächsten Runde nicht, was in der vorherigen passiert war; der Workflow war fein zerlegt, aber der Zustand war vollgestopft mit unnötigen Zwischenprodukten; in der Datenbank lagen viele Informationen, aber der Kontext, den das Modell erhielt, war nicht unbedingt nützlich.

Noch unangenehmer war: Wann immer sich die Produktanforderungen änderten, musste ich zuerst erklären, warum die bestehende Architektur diese Anforderung nicht wirklich unterstützte, und dann einen Weg finden, sie hineinzuzwängen.

Später entschied ich mich, neu zu schreiben.

Um die Diskussion zu erleichtern, lasse ich im Folgenden das konkrete Geschäft des Projekts weg und betrachte es als einen dialogorientierten Agenten, der kontinuierlich Kontext ansammeln und mehrrundige Interaktionen unterstützen muss. Dieser Artikel soll auch nicht den Tech-Stack auflisten; ich möchte lieber über die Stellen sprechen, an denen ich wirklich feststeckte, und darüber, wie diese Probleme mein Verständnis von Agent-Entwicklung verändert haben.

Erstens: Ich hielt den Workflow-Zustand für das Gedächtnis des Modells

Die früheste Architektur war eine ziemlich lange Pipeline: Geschäftsobjekte laden, Basismaterialien aufbereiten, Retrieval-Query erstellen, Informationen abrufen, Kontext organisieren und schließlich das Modell aufrufen.

Um Daten bequem zwischen Knoten zu übergeben, packte ich fast alles, was unterwegs entstand, in den Graph State. Abfrageergebnisse, Retrieval-Queries, halb organisierter Kontext und sogar SQLAlchemy-ORM-Instanzen – alles wurde hineingestopft.

Damals war mein Verständnis einfach: State ist doch nur Daten, die zwischen Knoten geteilt werden? Reinlegen, und der nächste Knoten nimmt sie direkt – wie praktisch.

Bis ich den Checkpoint anband, kam das Problem.

Zuerst die Serialisierung. ORM-Instanzen lassen sich nicht wie gewöhnliche Dictionaries direkt an die damalige Checkpoint-Serialisierungskette übergeben. Dann der Persistenzumfang: Viele temporäre Daten, die nur für die aktuelle Ausführung nützlich waren, wurden zusammen mit dem Zustand gespeichert.

Meine erste Korrektur war, die Zwischenfelder im letzten Knoten zu leeren. Später erkannte ich, dass der Checkpoint den Zustand bereits während der Ausführung aufzeichnet; einmal am Ende zu leeren beseitigt nicht die zuvor geschriebenen Snapshots.

Aber das war noch nicht die größte Falle.

Um fortlaufende Rückfragen zu unterstützen, wollte ich in der zweiten Runde den in der ersten Runde gespeicherten Kontext direkt wiederverwenden und einen zeitaufwändigen Aufbauvorgang sparen. Ich konfigurierte dieselbe thread_id und rief den Graph erneut auf – doch das Modell verhielt sich, als hätte es die vorherige Runde nie gesehen.

Beim genauen Hinsehen war die Ursache eigentlich ganz klar: Der Zustand war wiederhergestellt, aber beim Aufruf des Modells konstruierte ich nur eine neue HumanMessage. Die historischen Informationen lagen im State, wurden aber nicht in diese Anfrage eingebunden, also konnte das Modell sie natürlich nicht sehen.

Noch absurder: In der Eingabe der zweiten Runde übergab ich dem Kontextfeld auch noch einen leeren String. Eigentlich wollte ich ausdrücken „diese Runde nicht neu berechnen“, tatsächlich überschrieb ich aber den vorhandenen Zustand mit einem leeren Wert …

Erst danach habe ich wirklich mehrere Dinge auseinandergehalten:

DatenVerantwortung im System
Temporäre Variablen innerhalb eines KnotensDen aktuellen Schritt abschließen, danach verwerfen
Graph StateAusführungszustand, der zwischen Knoten weitergegeben und bei Bedarf wiederhergestellt wird
NachrichtenhistorieDialoginhalte, die bei mehrrundiger Interaktion erhalten bleiben müssen
Modell-Eingabe dieser RundeInformationen, die die aktuelle Aufgabe wirklich konsumieren muss

Der Checkpoint kann helfen, den Ausführungszustand wiederherzustellen, aber welche Inhalte in die Modell-Eingabe gelangen, muss ich immer noch selbst entwerfen. Umgekehrt bedeutet ein großer State nicht, dass jede Anfrage zwangsläufig viele Tokens verbraucht; erst wenn diese Inhalte an das Modell gesendet werden, werden sie zu Eingabekosten.

Dieser Unterschied wirkt sehr grundlegend, aber ich habe ihn tatsächlich erst nach einem Reinfall verstanden.

Ich habe auch die Knotenaufteilung neu überdacht. Früher wurde fast jede Funktion zu einem eigenen Node; später ging ich kurz ins andere Extrem und stopfte die ganze Kette zurück in einen Node. Erst beim Weiterarbeiten erkannte ich, dass sich Knotengrenzen nach den Ausführungsanforderungen richten sollten: Schritte, die unabhängig beobachtet, per Branch geroutet oder parallel geplant werden müssen, lohnen sich als eigene Knoten; Transformationslogik, die nur lokal verwendet wird, ist als normale Funktion ausreichend.

Informationen aus dem Speicherschrank werden erst nach Auswahl an das Modell auf der rechten Seite übergeben.
Der gespeicherte Zustand wird erst dann zum Kontext, den das Modell nutzen kann, wenn er in die aktuelle Anfrage eingebunden wird.

Zweitens: Wenn das Modell langsam verarbeitet, ist manchmal die Aufgabe zu schwer, die ich ihm gestellt habe

Früher gab es eine Eingabekette, die strukturierte Datensätze aus Screenshots wiederherstellen musste.

Ich verlangte vom Modell, für jede Nachricht Sprecher, Inhalt und Zeit zu erkennen und daraus strenges JSON zu machen. Um die Genauigkeit zu erhöhen, legte ich den Nutzern außerdem viele Einschränkungen auf: Screenshots der Reihe nach hochladen, Zeitangaben enthalten, Anzahl der Bilder begrenzen und so weiter.

Das Ergebnis war nicht zufriedenstellend. In einem Versuch brauchten zwei Screenshots etwa zwei Minuten, und es gab weiterhin Zeitverwirrung, vertauschte Sprecher und ungültige Inhalte.

Die erste Reaktion war natürlich, weiter am Prompt zu feilen. Aber als ich den endgültigen Verwendungszweck noch einmal ansah, merkte ich plötzlich, dass ich die Rohdatensätze gar nicht lückenlos wiederherstellen musste.

Was die nachgelagerte Verarbeitung wirklich brauchte, war: Worum geht es in diesem Material, welche Informationen sind es wert, erhalten zu bleiben, und in welchem Kontext sind sie aufgetreten.

Also änderte ich die Datengranularität von „einzelne Rohdatensätze“ zu „um ein Thema organisierte Informationen“. Das Modell musste nicht mehr die vollständige Rekonstruktion der Datensätze übernehmen, und auch der spätere Abruf musste nicht zuerst aus vielen verstreuten Nachrichten die Semantik neu zusammensetzen.

Natürlich hatte dieser Ansatz damals auch Kosten: Ich verlangte von den Nutzern, dass die pro Vorgang eingereichten Materialien möglichst zum selben Thema gehören, was einen Teil der Segmentierungsarbeit an die Nutzer zurückgab. Das verringerte die Verarbeitungslast, war aber noch keine vollständige Lösung der Eingabeerfahrung.

Diese Sache brachte mir an, vor der Optimierung des Modells zuerst zwei Fragen zu stellen: Welche Informationen braucht die endgültige Funktion eigentlich? Ist die Granularität, die ich das Modell jetzt ausgeben lasse, größer als der tatsächliche Verwendungszweck?

Nur weil die Datenbank Rohdatensätze aufnehmen kann, heißt das nicht, dass das Modell sie einzeln rekonstruieren muss; nur weil das Modell eine komplexe Struktur ausgeben kann, heißt das nicht, dass das Produkt will, dass Nutzer warten, bis es diese Struktur ausgefüllt hat.

Drittens: Die Schwierigkeit des Kontexts verlagerte sich von „gespeichert bekommen“ zu „wie diese Runde ihn nutzt“

Beim ersten Gedächtnisaufbau lag mein Fokus vor allem auf der Schreibseite: Wie werden Materialien extrahiert, wie werden Daten modelliert, wie wird Text vektorisiert.

Später stieß ich auf einige Ansätze, die Kontext mit Markdown organisieren, und fand dort viel Nachahmenswertes bei der Informationsklassifizierung und -darstellung. Aber bei den von mir ausprobierten Ansätzen mussten einige Dateien in jeder Runde gelesen werden, während andere Dateien bei Bedarf vollständig geladen wurden.

Bei wenig Material war das sehr direkt. Als das Material allmählich mehr wurde, begann ich mir Sorgen zu machen, dass ich jedes Mal nur einen kleinen Teil der Informationen brauchte, aber zuerst die ganze Datei laden musste.

Deshalb behielt ich beim Refactoring die Basismaterialien bei und zerlegte feinere Informationen in eigenständige Einträge, um später Abruf nach Frage zu unterstützen. Hier verwaltet die Datenbank die Zugehörigkeit, Kategorisierung und Zeit der Einträge, während der Textinhalt die Semantik ausdrückt, die das Modell verstehen muss.

Aber mit Vektor-Retrieval verschwanden die Probleme nicht von selbst.

Früher hing der Abruf hauptsächlich von der semantischen Distanz ab. Später fügte ich nach und nach Geschäftsbereichsfilter, Wichtigkeitsgewichtungen und zeitliche Abschwächung für einige Informationen hinzu. Denn „dem Problem sehr ähnlich“ und „für die aktuelle Antwort geeignet“ sind nicht dasselbe.

Besonders bei der Zeit.

Ich hatte einmal nur eine „aktuelle Zeit“ im System-Prompt, bis ich erkannte, dass sie nicht sagen kann, wann die historischen Nachrichten jeweils stattgefunden haben. Weiter stromaufwärts betrachtet: Selbst wenn die Datenbank eine Erstellungszeit hat, kann das Modell, wenn der extrahierte Text Jahr, Zeitraum oder Phase aus dem ursprünglichen Material verloren hat, immer noch leicht ähnliche Dinge aus verschiedenen Zeiten vermischen.

Die späteren Anpassungen teilten sich in zwei Teile: Dialognachrichten tragen explizit Zeitstempel; bei der Extraktion von Informationen werden bestätigbare Zeitanker aus dem Material im Haupttext erhalten, während nicht bestimmbare Zeiten nicht ergänzt werden.

Das ist früher anzusetzen als das bloße Anpassen von Sortierformeln. Wenn Zeitinformationen bei der Extraktion verloren gehen, sind sie in der Retrieval-Phase kaum aus dem Nichts zurückzuholen.

Außerdem habe ich versucht, den Wissensabruf als Tool zu kapseln, damit das Modell entscheidet, wann ergänzende Materialien nötig sind, und nicht jede Runde mechanisch die komplette Retrieval-Kette durchläuft.

Aber der Tool Call legte eine weitere Grenze offen: Das Modell kann die ID des aktuellen Geschäftsobjekts nicht stabil erzeugen. Diese ID ist bereits im Laufzeitkontext des Systems vorhanden, und trotzdem verlange ich vom Modell, sie noch einmal zu raten.

Schließlich injiziere ich vor der Ausführung des Tools die im aktuellen Kontext bereits feststehenden Parameter. Das Modell kann entscheiden, ob ein Abruf nötig ist und wonach gesucht wird; wer der aktuelle Nutzer ist, welches Objekt gerade bearbeitet wird und ob Zugriffsrechte bestehen, sollte das Programm festlegen und prüfen.

Nach all diesen Problemen wandelte sich mein Verständnis von Kontext allmählich von „so viel wie möglich sammeln“ zu: die notwendigen Informationen für die aktuelle Aufgabe bewahren und sie in geeigneter Form in das Modell bringen.

Wie viel jede Änderung tatsächlich bewirkt hat, dafür habe ich keine ausreichend systematischen Evaluationsdaten und möchte hier keine Prozentzahl erfinden. Bestätigen kann ich, dass ich allmählich weiß, entlang welcher Kette ich suchen sollte, statt nur auf die endgültige Antwort zu starren und Prompts anzupassen.

Viertens: Ein Verzeichnis aufzuteilen bedeutet nicht, wirklich entkoppelt zu haben

Früher war ich bei Web-Projekten gewohnt, zuerst das Backend zu schreiben, dann HTTP-Schnittstellen zu verpacken und schließlich das Frontend aufrufen zu lassen. Dieser Agent folgte anfangs einer ähnlichen Struktur, wobei Geschäftsfähigkeiten und Web-Service sehr nah beieinander lagen.

Später lief das Produkt hauptsächlich über IM-Interaktion, und ich fügte außerdem eine CLI hinzu, um Konfiguration, Verwaltung und Diagnose auszuführen. Zu diesem Zeitpunkt wirkte es unpassend, dass die Geschäftsschicht weiterhin vom Web-Framework abhing.

Also zog ich den Service heraus, ließ ihn Geschäfts- und Datenzugriffsfähigkeiten tragen und von verschiedenen Einstiegspunkten aufrufen.

Klingt schon entkoppelt, oder? Die Realität hat mir wieder einen Schlag versetzt.

Einmal gab ein Hilfebefehl der CLI tatsächlich die Hilfe des Web-Frameworks aus.

Der Grund war, dass das Befehlsmodul den Service importierte und der Service auf oberster Ebene den Request-Typ des Web-Frameworks importierte. Ursprünglich war das nur eine Typannotation, doch zur Laufzeit brachte sie das gesamte Framework mit und beeinflusste die Parsing der Kommandozeilenargumente.

Die Korrektur war nicht kompliziert: reine Typabhängigkeiten unter TYPE_CHECKING verschieben, die Befehlsregistrierungsphase möglichst leichtgewichtig halten und notwendige Module erst bei der tatsächlichen Ausführung laden.

Aber diese Kleinigkeit ließ mich erkennen, dass die Abhängigkeitspfeile im Architekturdiagramm letztlich auf Modulimporte und Initialisierungsverhalten herunterbrechen. Ein Service, der sauber aussieht, aber beim Import Framework mitbringt, Argumente liest oder externe Verbindungen startet, wird beim Aufruf über einen anderen Einstiegspunkt trotzdem Probleme verursachen.

Später versuchte ich, um die Nutzerkonfiguration zu vereinfachen, einen Teil der Datenfähigkeiten in die Ferne zu verlagern. Stellen, die zuvor ORM-Objekte nahmen, mussten nun klare Rückgabestrukturen konsumieren; verstreute Datenbankoperationen in Einstiegspunkten und Graph mussten weiter in den Service wandern.

Ich fügte eine einheitliche Verteilungsschicht hinzu: Im lokalen Modus wird der Service aufgerufen, im Remote-Modus die entsprechende HTTP-API. Auch die Serialisierung wird an dieser Grenze behandelt, damit die Konvertierung von Enums, Zeitobjekten und optionalen Parametern nicht überall verstreut ist.

Zum Beispiel ist es in einer Python-Funktion ganz natürlich, für einen fehlenden Abfrageparameter None zu übergeben, aber bei der HTTP-Query-Kodierung kann das direkt einen Fehler verursachen. Die Korrektur sollte an der Request-Grenze erfolgen und dabei aussagekräftige Werte wie 0 und False erhalten; auch darf man nicht nebenbei ein explizites null im JSON-Request-Body mit entfernen.

Das sind keine komplexen Algorithmen, aber sie entscheiden darüber, ob eine „lokal aufrufbare Funktion“ zu einer zuverlässigen Remote-Schnittstelle werden kann.

Fünftens: Wenn Nutzer eine Datenbank weniger konfigurieren, trägt das System eine weitere Verantwortung

CLI und IM-Einstiegspunkte wurden ursprünglich geschaffen, um den Entwicklungsaufwand für ein eigenständiges Frontend zu reduzieren und Nutzern die Interaktion an vertrauten Orten zu ermöglichen.

Aber als ich den Installationsablauf zusammenführte, merkte ich, dass ich nur das Frontend eingespart hatte; die Nutzer mussten weiterhin Datenbank, Modellkonfiguration und Bot-Konfiguration vorbereiten. Dass der Code läuft, ist noch ein langer Weg davon entfernt, dass Nutzer ihn gerne verwenden.

Deshalb versuchte ich, den Datenbankzugriff vom Server übernehmen zu lassen, um die Last des eigenen Datenbankaufbaus für Nutzer zu verringern.

Die erste Einschränkung war klar: Man darf nicht aus Bequemlichkeit die Verbindungsdaten der gemeinsamen Datenbank an den Client senden. Normale Datenoperationen können über eine authentifizierte API abgewickelt werden, aber der Checkpoint des Workflows hängt von der Datenbankverbindung ab; er erhält nicht automatisch Remote-Speicherfähigkeit, nur weil ich eine HTTP-Route hinzugefügt habe.

Damals bestand die Lösung darin, zwei Verhaltensweisen beizubehalten: Der lokale Modus persistiert Checkpoints weiterhin mit PostgreSQL; der experimentelle gemeinsame Modus verwendet stattdessen Prozessspeicher.

Der Preis war ebenfalls klar: Nach einem Prozessneustart geht in diesem Teil des gemeinsamen Modus das Kurzzeitgedächtnis verloren.

Ich habe dieses Problem nicht vollständig gelöst, sondern eine Verschlechterung akzeptiert, um eine Betriebsart zu erhalten, die keine Datenbankverbindung an den Client preisgibt. Das bedeutet auch nicht, dass Checkpoints niemals remote werden können; nur konnte die damalige Verteilungsschicht das nicht abdecken, und die Kosten weiterer Abstraktion überstiegen das Ziel dieser Runde.

Das unangenehmere Problem kam noch später.

Bestimmte Services, die wie „Datensynchronisation“ aussehen, rufen intern tatsächlich das Modell auf. Wenn man sie auf den Server verschiebt, wessen Modellkonfiguration sollte dann verwendet werden? Wie wird die Konfiguration des Nutzers übergeben? Wer trägt die Aufrufkosten?

Früher, auf einem einzelnen Rechner, lagen Datenbank, Modellkonfiguration und Ausführungsumgebung am selben Ort, sodass diese Fragen leicht übersehen wurden. Sobald man das Netzwerk überschreitet, muss jede einzelne neu beantwortet werden.

Dasselbe gilt für den Login-Zustand. Um zu vermeiden, dass Hintergrundaufgaben durch ablaufende Tokens unterbrochen werden, verwendete ich zeitweise eine Methode ohne Ablaufzeit. Aber die daraus resultierenden Probleme der Rotation, Widerrufung und Ungültigkeitsverwaltung bestehen weiterhin; nur weil die Hauptkette weiterläuft, kann man nicht sagen, dass die Authentifizierung vollständig entworfen ist.

Letztendlich habe ich, obwohl einige Ketten des gemeinsamen Modus bereits funktionierten, den öffentlichen Konfigurationseinstieg dennoch verborgen. Solange die Zugehörigkeit der Modellkonfiguration und die Grenze der serverseitigen Ausführung im Auftrag nicht sauber geklärt sind, sollte man Nutzern das nicht als bereits vorbereitete Option anbieten.

Das war auch ein Wandel auf Produktebene: Nutzungskosten zu senken bedeutet, dass jemand die zuvor an die Nutzer delegierte Komplexität übernehmen muss. Wenn Nutzer die Datenbank nicht mehr konfigurieren müssen, muss der Server die entsprechenden Rechte, Konfigurationen und Betriebsverantwortung übernehmen. Ein „Easy Mode“ ist weit mehr als nur ein paar weniger angezeigte Eingabefelder.

Die Konfiguration auf dem Desktop des Nutzers wird einfacher, während der Server dahinter Rechte, Speicher, Konfiguration und Betriebsverantwortung übernimmt.
Wenn Nutzer einen Punkt weniger konfigurieren, muss das System die entsprechende Verantwortung übernehmen.

Sechstens: Ein Prompt-Service-Ausfall ließ mich Laufzeitabhängigkeiten neu betrachten

Es gab noch eine Lektion, die fast nichts mit den Fähigkeiten des Modells zu tun hatte.

Um die Optimierung zu erleichtern, legte ich die Prompts auf eine externe Plattform und lud sie zur Laufzeit in Echtzeit. Prompts mussten nicht neu veröffentlicht werden, was die Entwicklungserfahrung tatsächlich sehr angenehm machte.

Dann fiel der Plattformdienst aus.

Ich hatte weder ein lokales Backup behalten noch einen Fallback für Lesefehler entworfen, und die Ketten, die Prompts betrafen, fielen auf einen Schlag alle aus. Der externe Dienst erholte sich nach etwa zwei Tagen, aber diese zwei Tage reichten, um mir klarzumachen: Ich hatte ein Entwicklungs-Komfortwerkzeug zu einer harten Laufzeitabhängigkeit gemacht.

Die Lektion war sehr konkret. Ein Prompt ist zwar nur ein Text, trägt im System aber tatsächliche Ausführungslogik; seine Version, Sicherung und Verfügbarkeit müssen ernst genommen werden. Ihn remote zu verwalten lässt diese Verantwortung nicht verschwinden.

Im späteren Entwicklungsverlauf begann ich auch, wiederkehrende Anforderungen an die Zusammenarbeit in Skills zu gießen: Qualitätskontrolle nach Änderungen, Änderungen protokollieren, die Graph-Dokumentation synchronisieren und Korrekturen in die Regeln zurückschreiben.

Diese Prozeduren können Tests nicht ersetzen und auch nicht garantieren, dass der Agent jedes Mal korrekt ausführt. Aber zumindest habe ich, wenn dieselbe Auslassung erneut auftritt, die Möglichkeit, die kontinuierlich konsumierten Regeln zu ändern, statt nur noch einmal daran zu erinnern.

Zum Schluss

Rückblickend war dieses Rewrite nicht so, dass ich an einem Tag alle Probleme durchdacht hätte, dann einen neuen Architekturplan gezeichnet und es in einem Zug abgeschlossen hätte.

Zuerst habe ich den Checkpoint missverstanden und dann den Zustand neu entworfen; zuerst strebte ich feingranulare Eingaben an und kehrte dann zur Semantik zurück, die die Downstream-Seite tatsächlich braucht; zuerst habe ich die Geschäftsschicht aufgeteilt und unnötige Einstiegspunkte gelöscht, später für die neue Deployment-Art den HTTP-Service wieder ergänzt. Neue Probleme tauchen ständig auf, und früher getroffene Entscheidungen werden erneut überprüft.

Ich zerbreche mir nicht mehr besonders den Kopf darüber, ob ich damals das falsche Framework gewählt habe. Was mich wirklich auf Umwege geschickt hat, war, dass ich einige grundlegendere Grenzen nicht geklärt hatte: Was muss persistiert werden, was muss ins Modell gelangen, welche Parameter entscheidet das Programm, und welche Verantwortlichkeiten bringt eine Fähigkeit mit sich, wenn sie ihren Ausführungsort wechselt.

Wenn ich jetzt eine neue Funktion zu schreiben beginne, nehme ich mir etwas mehr Zeit als früher, um diese Fragen zu stellen. Sie mögen mir nicht dabei helfen, es beim ersten Mal richtig zu machen, aber sie helfen mir, weniger Code zu schreiben, der scheinbar schon fertig ist und in einem anderen Szenario doch wieder umgestoßen werden muss.

Was dieses Rewrite betrifft, so sind die Ergebnisse, die ich am liebsten behalten möchte, wohl genau diese Fragen, die auch künftig beeinflussen werden, wie ich Code schreibe.