Dokumentation von Agent-Abläufen: was Sie vor der Umsetzung festhalten sollten
Eskalationsregeln gehören ins Design, Timer für Wiederholungsversuche in die Plattform. Ziehen Sie diese Linie, und das Design bleibt der Nachweis dessen, was vereinbart wurde.
Die Dokumentation von Agent-Abläufen ist die schriftliche Aufzeichnung der Entscheidungen, die ein KI-Agent verkörpert: die Abläufe, denen er folgt, Beispiel-Turns für jede Situation, die Stellen, an denen sich das Gespräch verzweigt, die Schnittstellen der Tools, die er aufruft, und die Bedingungen, unter denen er an einen Menschen übergibt. Sie ist ein anderes Dokument als die Implementierung, die diese Entscheidungen ausführt, und an der Grenze zwischen beiden sterben die meisten Dokumentationsvorhaben still.
Warum veraltet die Dokumentation von Chatbot-Abläufen?
Sie veraltet, weil sie meist eine Kopie der Implementierung ist und keine Aufzeichnung von Entscheidungen, und eine Kopie verliert immer gegen ihr Original. Die Abfolge ist so vertraut, dass sie sich wie ein Naturgesetz anfühlt. In der Discovery-Phase erstellt jemand einen Ablauf: ein Diagramm, einen Foliensatz, eine Tabelle mit Intents. Alle nicken. Die Umsetzung beginnt. Innerhalb von zwei Wochen weichen Umsetzung und Ablauf voneinander ab: Eine Abzweigung wurde zusammengeführt, die Rechtsabteilung hat einen Satz direkt in der Plattform geändert, ein Tool wurde umbenannt. Niemand aktualisiert danach das Diagramm, weil das Aktualisieren nichts bringt; nichts prüft es, und nichts hängt davon ab. Sechs Monate später stößt eine neue Person aus der Analyse dazu, liest die Dokumentation und lernt einen Agenten kennen, den es nicht mehr gibt.
Die Schlussfolgerung, die Teams daraus ziehen, lautet, Dokumentation sei eine Steuer, die sich nicht rechnet. Diese Schlussfolgerung ist halb richtig. Die Dokumentation ist gescheitert, weil sie die falschen Dinge auf der falschen Ebene festhielt. Ein Diagramm aus Kästchen bildet die Form der Umsetzung nach, ohne eine Entscheidung zu enthalten, die nicht ohnehin in ihr steckt, und wenn ein Dokument nur nachbildet, was umgesetzt wurde, gewinnt die Umsetzung, und der Spiegel wird blind.
Die Lösung ist eine Arbeitsteilung: Entscheidungen im Design, Implementierung in der Plattform, jeweils mit eigenem Maßstab für Aktualität.
Was gehört ins Designdokument?
Das Design enthält jede Entscheidung, die eine Person außerhalb des Entwicklungsteams lesen und per Veto stoppen können muss. In der Praxis sind das vier Dinge.
- Beispiel-Turns. Wie der Agent mit jeder Situation umgeht, als Beispiele gezeigt, auch mit den undankbaren: die Absage, die Entschuldigung, die Nachricht auf dem Weg zu einem Menschen. Jeder Moment, gegen den Stakeholder Einwände erheben könnten, gehört ins Design. Vollständig gelesen, sind die Beispiel-Turns zugleich die einzige Fassung des Agenten, die sich für Prüfende aus Recht oder Marke sinnvoll abnehmen lässt.
- Abzweigungen. Welche Situationen einen eigenen Pfad bekommen, wo jeder Pfad endet und welche Szenarien bewusst außerhalb des Umfangs liegen. Der Regelfall ist davon nur ein kleiner Teil; die Entscheidungen, auf die es ankommt, liegen auf den Fehlerpfaden, ein Argument, das wir ausführlich in Der Regelfall ist kein Design vertreten.
- Tool-Schnittstellen. Welche Daten der Agent in jedem Schritt liest oder schreibt: das System, das er berührt, die Parameter, die er braucht, woher jeder Parameter stammt (im Gespräch erfragt, aus dem Kontext abgeleitet oder fest vorgegeben), und was die Kundschaft zu hören bekommt, wenn der Aufruf scheitert. Das ist die Vereinbarung, von der das Gespräch abhängt; die Interna der API bleiben auf der Plattformseite der Grenze.
- Eskalation. Die genauen Bedingungen, unter denen der Agent aufhört und ein Mensch übernimmt, und was er sagt, wenn er beiseitetritt. Die Eskalation ist ein gestaltetes Ergebnis und wird geprüft wie jeder andere Turn.
Was gehört in die Plattform?
Alles, was dafür sorgt, dass das Modell das vereinbarte Verhalten tatsächlich zeigt: Prompts, Modellwahl und -konfiguration, Retrieval-Einrichtung, Werte für Wiederholungsversuche und Timeouts, Trainingsäußerungen, Deployment-Anbindung. Das alles ist Implementierung. Sie ändert sich wöchentlich, sie wird von den Menschen justiert, die bauen, und niemand außerhalb der Entwicklung nimmt eine Temperatur-Einstellung ab.
Der Test, auf welcher Seite der Grenze etwas liegt: Müssten Stakeholder einer Änderung daran zustimmen? Wenn ja, gehört es ins Design. Wenn eine Änderung daran unsichtbar bleibt, solange das Verhalten stimmt, gehört es in die Plattform.
Prompt Engineering ist in dieser Sicht das Handwerk, die Implementierung auf das Design auszurichten, weshalb beides so oft verwechselt wird und so unterschiedlich verantwortet ist. Diese Trennung erläutern wir in Gesprächsdesign vs. Prompt Engineering.
| Entscheidung oder Einstellung | Gehört in | Warum |
|---|---|---|
| Wie der Agent eine abgelehnte Erstattung behandelt | Design | Stakeholder können ein Veto einlegen |
| Welche Szenarien eine eigene Abzweigung bekommen | Design | Der Umfang ist eine Vereinbarung, der jemand zugestimmt hat |
| Die Parameter eines Werkzeugaufrufs und woher jeder stammt | Design | Das Gespräch hängt von dieser Vereinbarung ab |
| Wann der Agent an einen Menschen übergibt | Design | Ein Ergebnis, für das jemand einstehen muss |
| Der Systemprompt | Plattform | Wird frei umgeschrieben, um das Design zu erfüllen |
| Modell, Temperatur, Retrieval-Einrichtung | Plattform | Unsichtbar, solange das Verhalten stimmt |
| Anzahl der Wiederholungen und Timeout-Werte | Plattform | Justierung; was die Kundschaft beim Timeout zu hören bekommt, ist Design |
Wie halten Sie Design und Umsetzung im Einklang?
Indem Sie das Design zur geprüften Quelle der Absicht machen und jede Änderung darüber laufen lassen. Der Einklang ist eine Eigenschaft des Arbeitsablaufs, und er stützt sich auf vier Mechanismen.
- Das Design ist das, was geprüft wird. Die Abnahme erfolgt anhand der Beispiel-Turns, der Abzweigungen, der Tool-Schnittstellen und der Eskalationsbedingungen. Sobald die Abnahme am Design hängt, gewinnt es das Gewicht, das es aktuell hält; Menschen pflegen, was Folgen hat.
- Änderungen laufen über das Design. Wenn jemand will, dass sich der Agent anders verhält, kommt die Bitte als Änderung am Design an: Der Turn wird bearbeitet, die Abzweigung ergänzt, das Delta geprüft, und dann folgt die Umsetzung. Die umgekehrte Reihenfolge, die Umsetzung jetzt zu ändern und das Dokument später nachzutragen, hat eine Erfolgsquote, die in der Praxis alle kennen.
- Es ist versioniert und wird verglichen. Benannte Prüfpunkte und ein Versionsvergleich Turn für Turn, jede Version gegen die vorherige. „Was hat sich seit der Version geändert, die das Kundenunternehmen abgenommen hat?“ wird zu einer Frage, die Sie in Minuten aus der Versionshistorie beantworten.
- Die Entwicklung baut nach dem Design. Niemand muss den Workshop aus dem Gedächtnis rekonstruieren. Wo ein Coding-Agent einen Teil der Umsetzung übernimmt, kann er das Design auf dieselbe Weise lesen; in Klate ist dieser Zugang MCP.
Manche Entscheidungen entstehen erst in der Umsetzung: Das Modell kann etwas nicht zuverlässig leisten, oder die Latenz erzwingt eine andere Form, und das Design muss nachziehen. Bei der Absicht führt das Design, bei Entdeckungen manchmal die Umsetzung; in beiden Fällen gilt keine Änderung als erledigt, bevor das Design sie festhält.
Wer gewinnt, wenn sich Design und Umsetzung widersprechen?
Das Design, und das ergibt sich schon aus der Definition: Das Design ist die Aufzeichnung dessen, was vereinbart wurde; die Umsetzung ist der Versuch, es zu verwirklichen. Wenn beide auseinanderlaufen, trifft genau eines von zwei Dingen zu. Entweder ist die Umsetzung falsch, dann ist die Korrektur ein Ticket für die Entwicklung, oder die Vereinbarung hat sich geändert, dann wird das Design aktualisiert und das Delta von der Person, die diese Entscheidung verantwortet, erneut abgenommen. Einen dritten Zustand, in dem die Umsetzung die Vereinbarung stillschweigend umdeutet, während die Aufzeichnung mit den Schultern zuckt, gibt es nicht.
Angenommen, das Design für einen Erstattungsagenten sieht vor, dass eine abgelehnte Erstattung mit dem Angebot endet, an einen Menschen zu eskalieren; im Produktivbetrieb entschuldigt sich der Agent und hört auf. Welches Verhalten ist richtig? Ohne ein geprüftes Design klärt diese Frage, wer im Raum den höchsten Rang hat und wer sich am sichersten an den Workshop erinnert. Mit einem geprüften Design reicht es nachzulesen: Der Turn zur Eskalation bei Ablehnung steht in der abgenommenen Version, und eine Zeitleiste, die niemand bearbeiten kann, zeigt, wer wann abgenommen hat. Die Umsetzung hat einen Fehler, die Korrektur ist eindeutig, und das Gespräch dauert vier Minuten statt eines Meetings. Wie Sie diese Abnahme vor Beginn der Umsetzung einholen, ist ein eigenes Handwerk; wir beschreiben es im Beitrag zur Abnahme eines Agent-Designs durch das Kundenunternehmen.
Die Grenze, die kein Tool beseitigt
Kein Tool synchronisiert Absichten. Ein Export der Plattform kann Ihnen sagen, was die Umsetzung gerade tut; was sie tun soll, können nur Menschen sagen, die Entscheidungen treffen und aufschreiben, und jemand muss die Umsetzung trotzdem gegen das Design prüfen. Wer eine automatische Synchronisierung von Design und Umsetzung verkauft, beschreibt einen weiteren Spiegel der Umsetzung, und Spiegel werden blind.
Was ein Tool verändern kann, ist der Preis der Disziplin. Entscheidungen festzuhalten gelingt nur, wenn es günstig ist: Einen Turn zu bearbeiten muss eine Minute dauern, der Versionsvergleich muss automatisch erstellt werden, die Abnahme muss ein per E-Mail versandter Link sein, und die gesamte Aufzeichnung muss von der am wenigsten technischen Person mit Vetorecht von Anfang bis Ende lesbar sein. Wenn das Aktualisieren der Aufzeichnung weniger kostet als der Streit, den eine veraltete Aufzeichnung auslöst, halten Teams sie aktuell.
In Klate sind Beispiel-Turns, Abzweigungen, Tool-Schnittstellen und Eskalation versionierte Objekte, die sich abnehmen lassen, und die Abnahme begleitet das Design. Wenn diese Entscheidungen bei Ihnen derzeit in einem Diagramm stehen, das seit Beginn der Umsetzung niemand mehr geöffnet hat, fangen Sie kleiner an: Schreiben Sie einen Ablauf ordentlich auf, anhand der Abschnitte in unserer Vorlage für Gesprächsdesign. Der Tarif Free genügt für diesen ersten Ablauf. Die Abnahme durch das Kundenunternehmen gibt es in den kostenpflichtigen Tarifen.
