Entwicklung eines agierenden API-Assistenten: Vom Hackathon bis zur Beta-Version.

Ein Team, das eine Flottenverwaltungs-API für ein Zahlungsdienstleistungsunternehmen betreibt, verwandelte ein Prototyp aus einem Hackathon in einen Beta-Assistenten, der innerhalb seines Entwicklerportals vorhanden ist. Die Idee: Die Integratoren müssen nicht mehr Referenzseiten durchlesen und in Code umwandeln, sondern ein konversationaler Assistent übernimmt die Integration für sie. Hier wird gezeigt, wie ein solcher Assistent erstellt wird, was er absichtlich nicht tut, und wie seine Qualität gemessen wird.

Der Assistent erklärt Endpunkte, schreibt Code in der von den Entwicklern verwendeten Sprache, plant mehrstufige Workflows und führt ausschließlich Leseabfragen an Live-Systeme durch. Er ersetzt sprachspezifische statische Dokumentationen sowie Suchindizes, die lediglich auf Seiten verweisen.

Warum statische Dokumentationen nicht mehr ausreichen

Software für Flotten- und Mobilitätsmanagement muss mit einem hohen Datenstrom umgehen: Fahreraktivitäten, Tankstellen, Kartentransaktionen sowie Fahrzeugtelemetriedaten. Jeder, der solche Software integriert, muss sich mit fortgeschrittenen REST-Endpunkten, Filtersyntaxen, Fachbegriffen sowie langen Abfolgen von abhängigen Aufrufen auseinandersetzen. All diese Herausforderungen erschwerten es Partnern, mit der Plattform mitzuwachsen.

Entwickler stützten sich auf fertige Dokumentationswerkzeuge, um Endpunktdefinitionen zu lesen, sowie auf Testwerkzeuge, um Aufrufe manuell auszuprobieren. Das Team führte außerdem „Rezepte“ ein – feste Abfolgen von Aufrufen, die zeigten, wie mehrstufige Aufgaben wie die Erstellung eines Kontos, die Onboarding-Prozedur für Fahrer oder das Anbringen einer Karte abgewickelt werden. Diese Ansätze funktionierten, doch es traten stets drei Schwächen auf:

• Begrenzt auf eine Sprache. Die Darstellung jedes Workflows in cURL, Python, .NET, Java und Go erforderte kontinuierliche manuelle Arbeit von Autoren und Ingenieuren.
• Brechig an den Rändern. Es ist unmöglich, jede Kombination jedes Workflows zu dokumentieren, weshalb die Anleitungen oft den genauen Fall eines Partners übersehen.
• Ständige Wartungskosten. Sobald sich das API-Schema änderte, wurden die Seiten veraltet, was die Einführung verzögerte und die Support-Queue überlastete.

Von einer Hackathon-Idee zu zwei Modi

Das Konzept entstand aus einem internen Hackathon im Dezember 2025 und einer Frage: Warum sollen Entwickler Dokumente in Code umwandeln, wenn ein Modell ihre Absichten direkt verstehen kann? Das Ergebnis verhält sich wie ein stets verfügbarer Integrationsexperte und nicht wie ein Suchfeld.

Zur Betriebssicherheit teilt das Design den Assistenten in zwei separate Verarbeitungspfade auf.

Advisor-Modus kümmert sich um Erklärungen für einzelne Schritte, tiefergehende Dokumentationen sowie um die Codegenerierung für jedes Framework, einschließlich von Änderungsanfragen wie POST, PUT und DELETE. Er erzeugt Code, führt ihn jedoch niemals aus, sodass eine Person weiterhin für alle Änderungen an den Daten zuständig ist.

Plan-und-exekutier-Modus nimmt komplexe, mehrstufige Leseanfragen entgegen und führt sie über read-only Tools des Model Context Protocol (MCP) auf der Live-Plattform aus.

Was Partner tatsächlich sehen

Fragen Sie den Advisor-Modus nach einem Python-Snippet, das einen Driver erstellt – er gibt dabei einen requests-Aufruf mit dem richtigen Endpunkt, den erforderlichen Headern, dem Body-Schema sowie einem Kommentar zu den benötigten Berechtigungen zurück. Dabei wird die Produktions-API nicht berührt.

Der Plan-und-Ausführen-Modus wird für fünf Fahrer mit dem Vornamen John angefordert, wobei ein Planer den mehrfachen Filteraufruf auf eine einzige Aufgabe reduziert: das Abrufen der nach dem Vornamen gefilterten Fahrer. Ein Ausführender wählt das passende MCP-Tool aus, erstellt die OData-Argumente ($filter=first_name eq 'John', $top=5), führt einen nur zum Lesen geeigneten GET-Aufruf durch und legt die vollständige Antwort in einen Artefaktspeicher ab. Das Modell erhält lediglich eine kompakte Zusammenfassung wie eine Artefakt-ID, eine Anzahl von fünf sowie eine kurze Vorschau. Anschließend erstellt ein Synthesizer eine saubere Liste der fünf passenden Fahrer.

Architektur: ein Zyklus kooperierender Agenten

Der Assistent basiert auf LangGraph als zyklischer Zustandsautomat. Ein Planer, Ausführende, Validatoren und ein Synthesizer wechseln sich ab dabei ab, jeden Schritt zu planen, auszuführen und zu überprüfen, wobei gemeinsamer Zustand und Speicher weitergegeben werden, bis die Aufgabe abgeschlossen ist. Vier Gestaltungsentscheidungen heben sich hervor.

1. Ein nur zum Lesen geeigneter Proxy zur Sicherheit

Die Sicherheit prägte von Anfang an die Gestaltung. Der Assistent kann keine ändernden Aufrufe in seinem eigenen Laufzeitumfeld ausführen. Wenn ein Benutzer „Erstelle eine neue Karte für Fahrer X“ sagt, sendet ein Router die Anfrage an den Beratungsnode, der einen strukturierten Auszug zurückgibt, den der Entwickler kopieren, überprüfen und lokal ausführen kann. Alles, was tatsächlich ausgeführt wird, beschränkt sich auf GET-Anfragen. Schreibfähige Tools existieren im MCP-Server-Code, werden aber bereits vor dem Zugriff des Modells gefiltert.

2. Orchestrierung im Stil eines Supervisors

Das Denken und die Ausführung finden auf unterschiedlichen Ebenen statt und werden von einem einzigen Supervisor koordiniert, der entscheidet, welcher Spezialist im Rahmen einer globalen Schleife als Nächstes vorgeht:

• Ein Mode Router klassifiziert die Absicht und sendet jede Nachricht entweder an den Beratungsnode oder an den Plan-und-Ausführungs-Node.
• Ein Planer zerlegt eine komplexe Anfrage in eine Checkliste von Aufgaben, die mit den Zielparametern verknüpft sind.
• Ein Outführender wählt für jede Aufgabe das passende MCP-Tool, stellt die Argumente zusammen (einschließlich OData-Filter) und arbeitet sich schrittweise mit der Tool-Schicht voran, bis die Aufgabe abgeschlossen ist oder die Versuche erschöpft sind.
• Ein Synthesizer fügt die Ausgaben aller Aufgaben – egal ob echte Daten oder Ersatzcodeausschnitte – zu einer einzigen Antwort zusammen.

3. Eine Schleife, die ihren eigenen OData repariert

Modelle neigen dazu, bei der Verarbeitung einer strukturierten Filtersprache wie OData eigene Abfragemöglichkeiten zu erfinden oder die Syntax zu verfälschen. Das Team wählte OData, weil es flexible Teilmatch-Abfragen an komplexen Mobilitätsobjekten ohne manuelles Kodieren jeder Kombination ermöglicht, doch diese Flexibilität führt zu Fehlern, weshalb eine mehrschichtige Reparaturschleife hinzugefügt wurde.

Falls ein Präflug-Parser ein Syntaxproblem meldet oder ein Live-Aufruf mit einem API-Fehler zurückkommt, erfasst das System dieses Ereignis, setzt einen Wiederholungszähler pro Aufgabe frei und gibt die genaue Fehlermeldung wieder in den Kontext des Modells ein. Der Ausführer liest seinen eigenen Fehler und erstellt einen korrigierten Aufruf. Wenn die Wiederholungsversuche aufgebraucht sind, wechselt die Aufgabe in den Beratungsmodus, damit der Benutzer dennoch etwas Nützliches erhält.

4. Speicher in Artefakte aufgeteilt

Das Hineinschicken eines großen JSON-Pakets, beispielsweise Tausender Asset-Einträge, in das Gespräch verbraucht den Token-Budget, beeinträchtigt die Genauigkeit der Schlussfolgerungen und erhöht die Kosten. Deshalb bleiben die Rohantworten in einem isolierten Backend-Artefakt-Speicher, und dem Modell werden nur kurze Zusammenfassungsmetadaten angezeigt, die auf die Artefakt-IDs verweisen. Nachfragen ermöglichen es, auf spezifische Einträge zuzugreifen, indem die IDs in der Anwendungslogik abgefragt werden – dadurch bleibt der Kontext des Modells klein und fokussiert.

Qualitätsmessung

Um einen Prompt oder ein Modell ohne Rückfälle ändern zu können, ist ein automatisierter Vergleichswert erforderlich. Der Pipeline des Teams verwendet ein LLM als Bewertungsinstrument und beantwortet für jede Änderung eine Frage: Ist es besser oder schlechter als zuvor?

Das Datensatz enthält handgefertigte Testfälle in vier Kategorien: Codegenerierung, faktisches Wissen, Schlussfolgerungsfähigkeit und Sicherheit. Jeder Fall verfügt über eine explizite Bewertungskriterienliste und nicht nur über eine Frage, sodass der Bewertende den Inhalt einer Antwort bewertet anstatt nur eine starre erwartete Zeichenfolge abzugleichen. Der Bewertende ist stets ein anderes Modell als das, das getestet wird, und bewertet auf einer dreistufigen Skala von 10 für richtig, 5 für teilweise richtig und 0 für falsch. Jeder Durchlauf fügt eine Zeile zu einer Historie-Datei hinzu, die mit dem Git-Commit, dem getesteten Modell, dem Bewertungsmodell, dem OpenAPI-Hash, dem Datensatz-Hash sowie der Prompt-Version versehen ist, sodass jede Bewertung auf den genauen Code, die Spezifikationen und den Prompt zurückverfolgt werden können.

Laut dem Team erreicht der Assistent im Durchschnitt etwa 9,4 von 10 Punkten nach dieser Bewertungskriterie bei verschiedenen Tests, und diese Zahl dient als Ausgangswert, der vor dem Veröffentlichen verteidigt werden muss. Genauigkeit ist jedoch nicht das einzige Kriterium. Jeder Test erfasst außerdem die Latenzzeit, um eine reaktionsfähige Benutzererfahrung zu gewährleisten, sowie den Tokenverbrauch, der direkt mit den Kosten für das Modell zusammenhängt. Änderungen, die eines dieser Aspekte verschlechtern, werden bereits vor der Veröffentlichung markiert.

Schutz des Budgets und der Kapazitäten

Ein ständig verfügbarer Assistent, der auf eine Produktions-API zugreift, benötigt Grenzen, die sowohl das Modellbudget als auch die zugrundeliegenden Dienste schützen. Es gibt drei Schutzschichten:

• Quoten pro Benutzer. Demo-Konten erhalten 10 Nachrichten pro Tag, was neugierigen Partnern ermöglicht, das System auszuprobieren, ohne unbegrenzte Kosten für das Modell, und motiviert sie dazu, zu einem Partnerkonto überzugehen, wenn sie echte Arbeit leisten möchten.
• Gerichtete und nachvollziehbare Anrufe. Der Verkehr der Partner läuft unter deren eigenen Anmeldedaten, sodass jeder Anruf ihre Quote beeinflusst und in ihrer eigenen Prüfprotokollliste erscheint. Der Assistent gibt sich niemals als gemeinsames Servicekonto aus, was die Zuordnung der Nutzung sowie die Erkennung von Missbrauch ermöglicht.
• Wiederholungsversuche, die Ausfälle erkennen. Wenn eine Anfrage fehlschlägt – einschließlich einer vorübergehenden Drosselungsantwort – leitet der Reparaturzyklus den Fehler zurück an das Modell, erhöht den Wiederholungszähler und plant bis zu einem konfigurierten Maximum weitere Versuche. Wenn alle Wiederholungsversuche ausgeschöpft sind, wechselt das System in den Beratungsmodus.

Einfacher Zugang

Der Aufbau des Assistenten war nur die halbe Arbeit. Ein sicherer und unkomplizierter Zugang war genauso wichtig.

Die APIs der Plattform verwendeten traditionell Standard-Kundenanmeldedaten, was eine manuelle Einrichtung für jeden neuen Kunden bedeutete. Für einen Assistenten, der externen Partnern diente, war das Vorgehen „einen Antrag stellen und auf die Freigabe durch die Entwicklungsabteilung warten“ nicht akzeptabel. Es war auch nicht besser, die Entwickler zu bitten, Token in das Chat-Fenster einzufügen, denn dadurch ließ sich nicht unterscheiden, ob Anrufe vom Assistenten oder von Hand durchgeführt wurden, was die Zuordnung der Nutzung sowie die Sicherheitsüberwachung erschwerte. Das Team benötigte eine Strategie, die zwei Arten von Nutzern bedienen konnte: Partner, die einen reibungslosen Sandbox-Modus wollten, sowie solche, die sofort auf Live-Daten zugreifen wollten, ohne dass dazwischen manuelle Einrichtungsanfragen nötig wären.

Die Lösung war ein zweistufiges, selbstbedienungsfähiges Modell hinter dem regulären Entwickler-Anmeldesystem.

• Demo-Modus ist Standard. Neue Nutzer können sofort mit dem Assistenten über synthetische Daten kommunizieren, ohne Einrichtung, Wartezeit oder Anfragen.
• Partner-Modus wird aktiviert, wenn ein Entwickler eine Live-Integration wünscht. Die Anmeldeinformationen stammen aus einem einmaligen, selbstbedienbaren Autorisierungsprozess, der mit dem eigenen Konto und den Berechtigungen des Entwicklers verknüpft ist. Nach der Verbindung wird jede Anfrage dieser Identität zugeordnet und vollständig nachverfolgbar, sodass klar ist, wer aufruft und über welchen Weg.

Dadurch wurde das Hauptengpass bei der Einführung beseitigt. Der Übergang von „Ich bin neugierig“ zu „Ich integriere“ erfordert nicht mehr eine Warteschlange in der Ingenieurabteilung.

Was kommt als Nächstes?

Das Projekt begann als interner Experiment und ist nun in der Beta-Phase, wodurch die Integration für Entwicklerteams in Unternehmen verkürzt wird. Es läuft im Entwicklerportal und hat bereits die erste Gruppe an Partnern aufgenommen.

Der Orchestrierer liest standardmäßige OpenAPI-Schemata, wodurch die Architektur für eine horizontale Skalierung konzipiert ist. Derzeit konzentriert sich die Arbeit auf die Validierung im Bereich Mobilität, doch der Routing-Kern ist absichtlich generisch gehalten. Zum Fahrplan gehört es, dieselbe Konversationsschicht auch in andere Abteilungen wie Unternehmenszahlungs- und Vorteilsplattformen zu übertragen, reichhaltigere, deterministische OData-Validierungen hinzuzufügen, um mehr fehlerhafte Abfragen bereits vor dem Verlassen des Assistenten abzuwehren, sowie die Verwendung einer menschlichen Überprüfung bei Schreibvorgängen zu prüfen, damit der Assistent letztendlich auch sicher bei der Änderung von Workflows helfen kann.

Verwandte Artikel

• Von Prototyp bis Produktion: Agentic AI mit LangChain, LangGraph und Azure — Hybrid-Suche, Embedding-Caches, LangGraph-Routing, Circuit Breakers, Regressionstests mit einem „Golden-Dataset“ sowie Tracing für einen Agenten zur Verarbeitung von Steuerdokumenten, inklusive dargestellter Ergebnisse.
• Wissensgraphen für Agentic AI: Vier Muster, die über Vector RAG hinausgehen — Vector-Suche findet ähnlichen Text, nicht miteinander verbundene Fakten. Vier Graph-Muster für Agenten: grounded Prompting, Planung, Ausführungsvalidierung und Selbstkorrektur.

Wie LangGraph einen Graph ausführt: Von graph.invoke() bis zum Pregel Loop — Eine detaillierte Erläuterung auf Quellcodeebene von graph.invoke, stream, SyncPregelLoop, tick, der Vorbereitung von Aufgaben sowie run_with_retry, zusammen mit einem funktionierenden parallelen Beispiel, das durch Channel-Versionen gesteuert wird.