Hinzufügen von KI-Agenten zu Spring Boot-Mikroservices mit Spring AI

Stellen Sie sich drei Spring Boot-Mikroservices vor, die bereits Produktivlast tragen: Sechs Wochen Arbeit waren nötig, um ihnen Agentenfunktionen hinzuzufügen – zwei davon wurden reibungslos bereitgestellt, während der dritte zu einer langwierigen und kostspieligen Lektion wurde. Dieses Szenario, das die Erfahrungen vieler Java-Teams widerspiegelt, gibt den Rahmen für das Folgende vor. Es handelt sich um einen praktischen Überblick darüber, wie agierende Pipelines in bestehende Services integriert werden können, die Latenzgrenzen haben, von abhängigen Teams und echten Nutzern betroffen sind – geschrieben für Java-Backend-Entwickler, die Spring Boot kennen und KI-Funktionen ohne Aufgabe ihrer bestehenden Architektur wünschen.

Die folgenden Seiten erläutern, was ein KI-Agent in einem Spring Boot-Umfeld tatsächlich ist (und was nicht), warum Teams sie einsetzen, wie Toolaufrufe mit Spring AI umgesetzt werden können, drei Fehlermuster, die in der Regel erst nach der Veröffentlichung auftreten, sowie wie der Tokenverbrauch als wichtige Betriebsmetrik betrachtet werden sollte.

Was ein Agent ist und was er nicht ist

Bevor Code geschrieben wird, muss das mentale Modell korrekt sein. Die meisten Ingenieure, die bei der Integration von Agenten in Java Schwierigkeiten haben, werden nicht durch das Framework behindert – sie wenden einfach das falsche Modell darauf an.

Ein Agent ist keine clevere API-Aufrufmethode. Es handelt sich um einen Reasoning-Loop: Ein Sprachmodell erhält eine Aufgabe, wählt aus, welche Tools aufgerufen werden sollen, erhält die Ergebnisse zurück, überlegt über alles nach, was es nun weiß, und gibt entweder eine endgültige Antwort oder startet einen weiteren Durchlauf.

Vier Bestandteile bilden diesen Loop:

• Das Modell ist der Reasoning-Engine – sei es GPT-4o, Claude, Gemini oder eine open-source Alternative über Ollama.
• Die Tools sind die Funktionen, APIs oder Serviceaufrufe, die das Modell aufrufen darf.

Die Schleife ist der mehrfach wiederholte Zyklus, der einen Agenten von einem einzelnen Aufruf einer LLM-Techologie trennt.

Der Kontext ist der stetig wachsende Bestand an Konversationsgeschichte, Tool-Ergebnissen und Anweisungen, der jedem Schlussfolgerungs Schritt zugrunde liegt.

In einem Spring Boot-Mikroservice bedeutet das, dass man keinen RestTemplate-ähnlichen Wrapper um einen KI-Endpunkt anbringt. Stattdessen wird ein mehrschrittiger, zustandsbehafteter und nicht-deterministischer Workflow in einen für begrenzte, synchrone und vorhersehbare Ausführungen konzipierten Service eingebettet. Genau diese Unpassung ist der Grund, warum die meisten Java-KI-Integrationen Probleme bekommen. Ein kurzer Merkspruch: Das Tool ist nicht der Agent, die Schleife ist es – und solange man das nicht versteht, baut man letztendlich nur Endpunkte und keine Agenten.

Gründe für die Einführung von Agenten in Spring Boot-Diensten

Die Tutorials überspringen in der Regel diesen Teil. Sie zeigen, wie ein Agent integriert wird, sagen aber wenig darüber, warum eine Organisation dies tun sollte, welches Problem es löst oder welche Kosten durch eine zu frühe Einführung entstehen.

Jenseits fester Regeln

Klassische Microservices automatisieren bekannte Verfahren, bei denen eine Eingabe A durch einen Regelwerk-B läuft, um eine Ausgabe C zu erzeugen – was sich hervorragend für deterministische Abläufe eignet. Agenten erweitern dieses Konzept auf unklare, mehrschrittige Aufgaben, bei denen die richtige nächste Aktion von Zwischenergebnissen abhängt. Einige Beispiele, die zu bestehenden Spring Boot-Architekturen passen:

• Bestellverarbeitung. Ein Agent überprüft den Bestand, bewertet Preisregeln, wendet kundenbezogene Rabatte an und erstellt in einer einzigen Anfrage eine Lieferempfehlung, sodass die Frontend-Anwendung keine vier aufeinanderfolgenden Aufrufe koordinieren muss.
• Dokumentverständnis. Ein Agent liest ein hochgeladenes PDF, extrahiert strukturierte Felder, überprüft sie anhand von Geschäftsregeln und bestätigt sie oder leitet den Fall an einen menschlichen Prüfer weiter – ohne vorgefertigte Extraktionsregeln.
• Kundenservice. Innerhalb eines bestehenden Support-Dienstes holt ein Agent den Kontostand, die Bestellhistorie sowie Richtliniedokumente ab und erstellt eine kontextgerechte Antwort, wodurch die Bearbeitungszeit verkürzt wird, ohne den Menschen aus dem Prozess zu entfernen.
• Code-Review und Unterstützung bei CI-Prozessen. In einem Platform-Engineering-Pipeline analysiert ein Agent fehlerhafte Tests, konsultiert interne Dokumentationen und schlägt gezielte Korrekturen vor.

In jedem dieser Fälle ist der Wert nicht einfach „AI“. Stattdessen wird eine brüchige, manuell erstellte Orchestrierungslogik durch eine Schlussfolgerungsschicht ersetzt, die sich an das Vorhandene anpasst, anstatt auszufallen, wenn die Eingabe nicht dem erwarteten Ablauf folgt.

Warum Spring Boot für diese Aufgabe geeignet ist

Python dominiert die AI-Tutorials, während Java in Unternehmensproduktionsystemen vorherrscht – der Unterschied zwischen den beiden bietet echte Möglichkeiten. Spring Boot bietet strukturelle Vorteile, die leichte Python-Frameworks nicht standardmäßig bieten:

• Dependency Injection sorgt dafür, dass Tool-Beans verwaltet, testbar und komponierbar bleiben, ohne zusätzliche Konfiguration.
• Actuator und Micrometer wandeln die Nutzung von Tokens, die Latenz zwischen Agenten sowie die Fehlerraten der Tools in übliche Betriebsmetriken um.
• Asynchrone Primitiven wie @Async und CompletableFuture kommen gut mit Agenten-Schleifen zurecht, deren Laufzeit variabel ist.
• Resilience4j umhüllt Tool-Aufrufe mit Circuit Breakern und Wiederholungsversuchen, um kaskadierende Ausfälle zu verhindern.
• Spring Security ermöglicht es, Authentifizierung und Autorisierung für an Agenten gerichtete Tool-Endpunkte in das bestehende Zugriffsmanagement einzubinden.
• Entwickelte Tools für Operationen bedeuten, dass bestehende Stacke wie Prometheus, Grafana oder Datadog ohne neue Infrastruktur um Metriken für Agenten erweitert werden können.

Dazu bietet Spring AI innerhalb desselben Ökosystems LLM-Klienten, Integrationen mit Vektorlagern sowie funktionale Aufrufe mithilfe der @Tool-Anmerkung, sodass die Entwicklung eines produktionsreifen Agents nicht das Verlassen des Spring-Workflows erfordert.

Wann sich ein Agent lohnt

Agenten erlangen ihre Bedeutung, wenn:

• Der Workflow Entscheidungen auf der Grundlage von während der Ausführung gewonnenen Informationen benötigt, nicht auf der Grundlage von Informationen, die bereits bei Eingang der Anfrage vorlagen.
• Die aktuelle Implementierung dazu führt, dass die Frontend-Oberfläche oder ein Orchestrierungsdienst mehrere Backend-Aufrufe koordinieren muss, wobei der Agent diese Koordination auf dem Server übernehmen könnte.
• Die Eingabe in Form natürlicher Sprache mit variabler Struktur vorliegt, wobei Klassifizierung, Extraktion, Zusammenfassung oder Routing durch den Inhalt und nicht durch ein Schema gesteuert werden.
• Das aktuelle System auf die Weise „falsch, aber nicht abstürzend“ versagt, und ein Agent könnte so konzipiert werden, dass Unsicherheiten sichtbar gemacht werden, anstatt stumm die wahrscheinlichste falsche Antwort zurückzugeben.

Sie eignen sich nicht, wenn der Workflow vollständig deterministisch ist, die Eingaben strukturiert sind und die regelbasierte Logik wartbar ist. Agenten fügen Komplexität hinzu, und das lohnt sich nur, wenn die Alternative schlechter ist.

Der Geschäftsargument in einfachen Worten

Für Engineering-Leiter und Produktbeteiligte basiert der Argumentationsansatz auf drei Faktoren:

1. Schnellere Bereitstellung neuer Funktionen. Funktionen, für die früher wochenlange Entwicklung von Backend-Orchestrierungskodern erforderlich waren, können oft bereits innerhalb weniger Tage prototypiert werden, wenn ein Agent die mehrstufige Koordination übernimmt. Teams berichten häufig von dieser Beschleunigung nach einer ersten erfolgreichen Integration, wobei die Zahlen variieren können.
2. Kleinere Herausforderungen bei der Wartung von Regeln. Jede fest programmierte Regel in einem Service stellt eine Art Schuldenlast dar, die zunimmt, wenn sich die Geschäftslogik ändert. Anweisungen, die in natürlicher Sprache verfasst sind, lassen sich in der Regel leichter aktualisieren als Code, der dieselbe Logik imperativ ausdrückt.
3. Grundlage für komplexe KI-Systeme. Ein gut integrierter Agent bildet die Basis für mehragentige Workflows, Generierungspipelines mit Informationsabrufunterstützung sowie KI-optimierte Produktfunktionen.

Warum die Dringlichkeit und der Wandel im Ausführungsmodell?

Bis 2023 und in das Jahr 2024 hinein bedeutete KI in Java im Grunde nichts anderes, als an einen LLM-Endpunkt zu senden und den zurückgegebenen Text einfach weiterzugeben: reiner HTTP-Verkehr über einen WebClient, eine Zeitüberschreitung – und das war’s.

Dieses Modell gilt nicht mehr. Das Funktionsset von Spring AI (Aufruf von Tools und Funktionen, Integration mit einem Vektorlagers sowie eine ChatClient-API, die unter Berücksichtigung agenter Workflows entwickelt wurde) zeigt an, dass sich das Ausführungsmodell selbst geändert hat.

• Die alte Struktur bestand aus einer einzigen Anfrage, die zu einem LLM-Aufruf und einer einzigen Antwort führte.
• Die neue Struktur besteht aus einer Anfrage, die sich in N Tool-Aufrufe und M Überlegungsschritte aufteilt, bevor schließlich eine einzige Antwort entsteht.

Viele Spring Boot-Entwickler wenden weiterhin das alte Modell an und behandeln ChatClient wie RestTemplate. Dieser Kategorienfehler verursacht Produktionsprobleme Wochen nach dem Go-Live, und diese sind selten sofort offensichtlich, wenn sie auftreten.

Der Loop ist der Agent

Engenieure, die erstmals mit der Integration von Agenten arbeiten, stellen sich in der Regel einen Dienst vor, der einen Controller ersetzt: ein @Service-Bean, ein injizierter ChatClient – und schon ist alles erledigt. Das ist jedoch ein Autocomplete-Endpunkt, kein Agent. Ein echter Agent führt einen Zyklus durch, bei dem zunächst eine Aufgabe empfangen, anschließend ein Werkzeug ausgewählt, dieses ausgeführt, das Ergebnis erhalten, über den neuen Zustand nachgedacht und schließlich entschieden wird, ob weitergemacht oder geantwortet werden soll. Das Modell ist der Reasoning-Engine innerhalb dieses Zyklus; der Zyklus selbst ist der Agent.

Warum die übliche Architektur die Kosten falsch einschätzt

Die gängige Annahme ist, dass der Aufruf des LLM der teure, komplexe Teil ist und ein Spring-@Service-Wrapper sich um den Rest kümmert. In Wirklichkeit ist „der Rest“ nun verteilt: wie langsam die Werkzeuge sind, welchen Zustand der Kontext von einer Runde zur nächsten überträgt, wie Fehler in mehrstufigen Abläufen weitergeleitet werden und welche Wiederholungsversuche notwendig sind, um unvollendete Arbeiten zu bearbeiten.

Betrachten wir einen hypothetischen Service zur Klassifizierung von Bestellungen. Er beginnt mit einem Endpunkt POST /orders/classify, der eine Anfrage an ein LLM sendet. Anschließend wird er in einen Agenten umstrukturiert, der die Bestellung klassifiziert, ein Lagerverwaltungstool aufruft, je nach Lagerbestand ein Preistool aufruft und schließlich eine Empfehlung zur Ausführung gibt. Jeder Aufruf eines Tools stellt einen tatsächlichen Serviceaufruf mit eigener Latenzzeit dar.

Nehmen wir an, der Agent schafft 80 % der Anfragen in weniger als zwei Sekunden, während bei den verbleibenden 20 % ein langsames upstream-Lagerverwaltungstool die Antwortzeiten auf 8 bis 14 Sekunden verlängert. Das ist kein KI-Problem – es handelt sich um ein Problem von verteilten Systemen, das durch den Agenten-Loop offengelegt wird.

Der übersehene Kompromiss

Ein Agent-Loop ist nicht zustandslos. Jedes Ergebnis eines Tools wird der Konversation hinzugefügt und beim nächsten Schritt erneut an das Modell gesendet. Bei hoher Durchsatzrate steigt der Speicherverbrauch pro Anfrage mit der Anzahl der Schritte, die der Agent durchläuft, wobei die Gesamtanzahl der Anfragen weniger wichtig wird. Ein Service, der 1.000 Anfragen pro Minute mit durchschnittlich vier Schritten verarbeitet, führt effektiv 4.000 LLM-Aufrufe durch, wobei sich die Kontextgrößen addieren.

Bevor Sie also Code für einen Agent schreiben, listen Sie alle Tool-Aufrufe auf, schätzen Sie die p95-Latenzzeit jedes Aufrufs ein und berechnen Sie die größtmögliche Kontextgröße bei der maximalen Anzahl an Schritten. Planen Sie den Kontextbedarf bereits vor der Gestaltung des Loops ein. Die meisten Fehlfälle bei Agenten in Java-Backends sind in Wirklichkeit Timeout-Fehler, die sich als Modellfehler ausgeben.

Spring AI bietet die Infrastruktur – nicht den Plan.

Spring AI ist eine ernsthafte, produktionsorientierte Abstraktionsschicht. Sie bietet ChatClient, ToolCallback, VectorStore sowie eine Agenten-Exekutions-API, die mit Dependency Injection, Moduswechseln über application.properties und reaktiver Unterstützung durch Flux arbeitet. Als Ausgangspunkt für die Integration von LLMs in Spring Boot ist sie die richtige Wahl.

Was sie jedoch nicht bietet, ist eine Strategie für agierende Pipelines – und genau diese Lücke trennt Prototypen von Produktivdiensten. Das Framework kümmert sich um einzelne Toolaufrufe und Modellinteraktionen. Es handhabt nicht:

• Verträge an der Servicegrenze zwischen dem Agenten und den nachgelagerten Diensten.
• Die Persistenz des Agentenzustands über mehrere Anfragen hinweg, also Sitzungsspeicher.
• Circuit-Breaker-Logik für Fehler, die mehrere Schritte umfassen.

Überwachung auf Workflow-Ebene, beispielsweise um zu verstehen, warum der Agent eine bestimmte Abfolge von Tools gewählt hat.

Erstellen Sie eine Tool-Fehlermatrix

Vor der Veröffentlichung sollten Sie für jede @Tool-Methode definieren, was in drei Situationen geschieht:

• Das Tool gibt die erwartete Ausgabe zurück. Der Agent geht zum nächsten Überlegungsschritt über.
• Das Tool gibt einen Fehler zurück. Der Agent erhält das Fehlersignal und entscheidet, ob er es erneut versucht, auf einen Ersatz zurückgreift oder den Benutzer informiert.
• Das Tool läuft aus. Ein Circuit Breaker wird aktiviert, ein Ersatzwert wird zurückgegeben und dem Agenten wird mitgeteilt, dass die Daten nicht verfügbar sind.

Falls die zweite und dritte Fallgruppe für ein Tool leer sind, ist die Integration noch nicht abgeschlossen. Der „happy path“ ist dabei nicht der Service selbst. Spring AI kümmert sich um die Umsetzung; die Gründe, die Zeitpunkte sowie die Handlungspläne im Falle eines Fehlers bleiben Ihre Verantwortung.

Context-Windows verhalten sich wie ungeschriebene Verträge

In einem gewöhnlichen Spring Boot-Dienst führt das Verletzen eines Vertrags zur Auslösung einer Ausnahme. Bei einem Agenten führt das Überschreiten des Context-Windows weder zu einer Ausnahme noch zu einer Warnung oder zu einem Fehlerprotokoll. Das Modell löscht einfach leise den ältesten Inhalt des Gesprächs – und das ist oft der Systemhinweis, der Ihre Geschäftsregeln enthält. Eine REST-API antwortet mit 400, wenn der Vertrag verletzt wird; ein Context-Window fängt einfach an, Dinge zu vergessen, was einen weitaus schwierigeren Fehler darstellt.

Ein illustratives Beispiel

Stellen Sie sich einen Dokumentverarbeitungsdienst vor, dessen Systemanweisung etwa 800 Token umfasst. Bei Tests liegen die Antworten der Tools im Durchschnitt bei rund 1.600 Token pro Anfrage, was deutlich innerhalb der Grenzen des Modells liegt. In der Produktion löst ein bestimmter Workflow alle drei Toolaufrufe mit großen Datenmengen aus, darunter eine verschachtelte Bestellhistorieantwort, die allein bereits etwa 1.800 Token umfasst. Der Gesamtkontext überschreitet damit 6.000 Token, die Systemanweisung wird stillschweigend abgeschnitten und der Agent gibt eine plausibel klingende Antwort zurück, bei der eine wichtige Geschäftsregel weggelassen wird.

Es wird nichts ausgeworfen und es gibt keine Warnungen. Der Fehler zeigt sich erst bei einer wöchentlichen Prüfung drei Tage später.

Die Lösung: Token-Metriken von Anfang an

Verbrauch des Kontexts des Instruments vor dem Versand. Mit Micrometer bedeutet das, die Zählwerte für Anfragen und Generierungstoken aus dem Nutzungselement der Antwortmetadaten abzulesen und diese beispielsweise unter Namen wie agent.context.input_tokens und agent.context.output_tokens als Anzeigen zu veröffentlichen. Die genauen Namen der Zugriffsfunktionen unterscheiden sich je nach Spring AI-Version, daher sollten Sie die Nutzung-API der von Ihnen genutzten Version überprüfen. Geben Sie anschließend bei etwa 80 Prozent der Kontextgrenze des Modells einen Alarm aus. Das entspricht in etwa zwei Beans sowie einer Konfigurationseigenschaft, und diese sollten bereits vor dem Go-Live bereitstehen. Der Versand eines Agents ohne Token-Metriken ist wie der Betrieb einer Datenbank ohne Überwachung der Abfristunden – das endet meist um 2 Uhr morgens.

Schritt für Schritt aufbauen

Voraussetzungen: Spring Boot 3.2 oder neuer, Spring AI 1.0 oder neuer zusammen mit dem Starter für Ihren Modellanbieter (in diesem Beispiel ein OpenAI Starter), eine solide Kenntnis von @Async und CompletableFuture, ein internes Service, der als Tool bereitgestellt werden soll, sowie Micrometer, das in Ihr Observability-Stack integriert ist. Die Namen der Starter-Artefakte haben sich bei den verschiedenen Spring AI-Versionen geändert, daher sollten Sie die aktuelle Version in den Referenzdokumenten überprüfen.

Schritt 1: Abhängigkeiten hinzufügen

In der pom.xml sollten Sie den Spring AI Starter für Ihren Anbieter hinzufügen, sowie das Artefakt resilience4j-spring-boot3, falls Sie Unterstützung für Circuit-Breaker bei Tool-Aufrufen wünschen. Die Anmeldeinformationen des Modells werden in application.properties gespeichert. Die API-Schlüssel werden über eine Umgebungsvariable wie OPENAI_API_KEY über die Eigenschaft spring.ai.openai.api-key abgerufen, das Chat-Modell wird ausgewählt (im Beispiel wird gpt-4o verwendet) und die Temperatur sollte auf einem niedrigen Wert von etwa 0,2 liegen, damit die Nutzung der Tools vorhersehbar bleibt.

Schritt 2: Definieren Sie die Tools, bevor Sie den Agenten konfigurieren

Die Reihenfolge ist wichtig, da die Gestaltung der Tools das Verhalten des Agents bestimmt. Ein Systemprompt sollte auf konkrete Fähigkeiten der Tools verweisen; seine Erstellung vor dem Bestehen der Tools führt zu unklaren Anweisungen, die das Modell verwirren.

In dem Beispiel erhält ein OrderTools-Komponente über ihren Konstruktor einen InventoryService sowie einen PricingService und stellt zwei mit Annotationen versehene Methoden zur Verfügung. checkInventory(String sku) gibt die verfügbare Menge zurück oder -1, wenn der SKU unbekannt ist. getPrice(String sku, String customerTier) gibt den Preis in US-Dollar-Cents an. Jede Methode trägt eine @Tool-Annotation mit einer Beschreibung.

Der häufige Fehler besteht darin, diese Beschreibungen vage zu formulieren. Das Modell liest sie, um zu entscheiden, wann jede Methode aufgerufen werden soll; daher führen präzise und vollständige Beschreibungen zu weniger unnötigen Aufrufen und genaueren Ergebnissen. Beschreiben Sie Einheiten, Rückgabewerte sowie den Fall, wenn etwas nicht gefunden wird, genauso wie in den obigen Beispielen.

Schritt 3: Geben Sie dem ChatClient eine kurze Systemanweisung.

Die Klasse AgentConfig definiert ein ChatClient-Objekt mithilfe des injizierten Builders sowie von OrderTools. Die Standard-Anweisung des Systems ist kurz und direkt: Handeln Sie als Assistent für die Auftragsverarbeitung, überprüfen Sie stets den Bestand, bevor Sie die Verfügbarkeit bestätigen, holen Sie immer die Preise ab, bevor Sie einen Preis nennen, geben Sie ein JSON-Objekt zurück, das einen booleschen Wert available, einen ganzzahligen price in US-Dollar-Cents sowie einen recommendation-String enthält, und erfinden Sie niemals Bestandsstände oder Preise. Die Tools werden unter defaultTools registriert.

Hier zahlt Disziplin bei der Verwendung von Tokens. Jeder Token in der Systemanweisung verringert den Platz für die Ergebnisse der Tools, daher sollten Sie sich auf unter 300 Tokens konzentrieren und ohne Gnade editieren.

Schritt 4: Führen Sie den Agenten asynchron aus und protokollieren Sie die Tokens

Ein OrderAgentService enthält einen ChatClient sowie eine MeterRegistry. Seine processOrder-Methode gibt einen CompletableFuture<String> zurück und führt den Agentenaufruf innerhalb von supplyAsync aus: Es werden die Eingaben des Benutzers gesendet, das Modell aufgerufen, die Chatantwort entgegengenommen, die Zählungen der Eingangs- und Ausgabetoken gelesen und diese als Messwerte erfasst, anschließend wird der Text des Ergebnisses zurückgegeben.

Warum asynchron? Die Laufzeit eines Agenten skaliert mit der Anzahl der Tool-Aufrufe und nicht mit der scheinbaren Komplexität der Anfrage. Ein synchroner Controller-Thread, der in einem stark belasteten Service 8 bis 14 Sekunden lang blockiert ist, erschöpft den Threadpool. Behandeln Sie die Ausführung eines Agenten von Anfang an als Hintergrundaufgabe.

Schritt 5: Ein Circuit Breaker für jedes Tool einrichten

Markieren Sie jede Tool-Methode mit @CircuitBreaker von Resilience4j, geben Sie dem Circuit Breaker einen Namen (zum Beispiel inventoryTool) sowie eine Fallback-Methode an. Der Fallback für das Inventory-Tool protokolliert eine Warnung mit dem SKU und gibt -1 zurück, was dem Agent mitteilt, dass die Inventardaten nicht verfügbar sind. Schwellenwerte sollten in application.properties definiert werden: ein Zeitfenster von 10 Aufrufen, ein Schwellenwert von 50 % Ausfallrate sowie eine Wartezeit von 10 Sekunden im offenen Zustand.

Falls die Circuit Breakers scheinbar nie aktiviert werden, denken Sie daran, dass Spring AOP nur dann funktioniert, wenn die Aufrufe über den Spring-Proxy laufen. injizieren Sie die Tool-Komponenten ordnungsgemäß und erstellen Sie sie nicht direkt.

Schritt 6: Einen Endpunkt mit einem asynchronen Antwortmuster bereitstellen

Ein OrderAgentController, der auf /agent verknüpft ist, nimmt eine POST-Anfrage an /orders entgegen, generiert eine Anfrage-ID, startet den Agenten und speichert den zukünftigen Zustand in einem koncurrenten Speicher, antwortet anschließend mit 202 Accepted zusammen mit der ID. Eine GET-Anfrage an /orders/{requestId}/result ruft diesen zukünftigen Zustand ab. Es wird 404 zurückgegeben, wenn die ID unbekannt ist, 202 zusammen mit einer „Processing“-Meldung, solange der Vorgang noch nicht abgeschlossen ist, 200 mit dem Ergebnis, sobald der Vorgang abgeschlossen ist, und 500 mit einer Fehlermeldung, falls die Ausführung fehlschlug. Für Anwendungen jenseits einer Demo sollte der in-Memory-Speicher durch einen Speicher ersetzt werden, der auch nach Neustarts erhalten bleibt und alte Einträge abläuft.

Eine Entscheidungshierarchie gilt für die Tools selbst. Bei internen Serviceaufrufen mit geringer Latenz sollten die Tools synchron bleiben, während asynchrone Abläufe auf der Serviceebene gehandhabt werden. Bei externen APIs mit unvorhersehbarer Latenz sollten die Tools asynchron gestaltet werden, wobei ein dedizierter Threadpool sowie eine feste Timeout-Frist verwendet werden, damit eine langsame Abhängigkeit niemals unbegrenzte Latenz in den Zeitrahmen des Agents einbringt.

Tools, die man kennen sollte

• Spring AI ist das Kern-Agent-Framework für Spring Boot.
• LangChain4j ist eine native Java-Alternative, die oft als stärker in der Multi-Agent-Koordination angesehen wird.
• Resilience4j bietet Circuit Breaker- und Wiederholungsmechanismen für Tool-Aufrufe.
• Micrometer gibt die Token-Nutzung sowie Agent-Metriken wieder.
• Ollama läuft Open-Source-Modelle lokal für Entwicklung und Testing.

Drei Fehler, die Zeit und Glaubwürdigkeit verschwenden

Die Anfängerfalle: Nur mit „happy-path“-Eingaben testen. Tutorials verwenden saubere, kooperative Testdaten, doch echte Nutzer übermitteln Eingaben, die lange laufen, unklar bleiben oder ungewöhnliches Toolverhalten auslösen – wie es nur in Produktionsdaten vorkommt. Erstellen Sie ein Tool, das vor jeder Veröffentlichung anonymisierte Beispiele aus Produktionsanfragen, und nicht synthetische, gegen den Agenten in der Staging-Umgebung ausführt, und testen Sie zumindest mit feindlichen Eingaben, die das erwartete Kontextbudget überschreiten.

Der gefährliche Blindpunkt: Über-Engineering vor dem Veröffentlichen. Ingenieure, die sich intensiv mit der Literatur zu mehreren Agenten beschäftigt haben, entwickeln manchmal Orchestrierungsmechanismen, Unteragenten, Speicherschichten sowie RAG-Pipelines, noch bevor ein einziger Agent einen echten Benutzer erreicht hat. Das ist die „Compound-AI“-Variante davon, ein Service-Mesh zu bauen, bevor ein Monolith validiert wurde. Veröffentlichen Sie zunächst einen Agenten mit einem Satz an Tools in einem Service, messen Sie dessen Leistung und fügen Sie Komplexität nur dort hinzu, wo die Daten es erfordern. Die Teams, die am schnellsten in die Produktion gelangen, verzichten darauf, eine Plattform zu entwerfen, bevor sie ein Produkt haben.

Das systemische Versagen: Niemand ist für das Verhalten des Agents verantwortlich. Ein herkömmliches Versagen hinterlässt eine Protokolzanzeige, eine Metrik und eine Warnung. Eine falsche, aber plausibel klingende Antwort des Agents hinterlässt keines davon: keine Ausnahme, keine Warnung, nur eine Antwort, die die Schema-Validierung besteht, aber an der Geschäftslogik scheitert. Man muss einen Verantwortlichen für das, was der Agent sagt, benennen – nicht nur dafür, ob er geantwortet hat – und wöchentlich eine Stichprobe der Antworten überprüfen, anstatt sich nur auf die Fehlerraten zu konzentrieren. Das ist eher eine organisatorische als eine technische Entscheidung.

Was die Einführungsanleitungen weglassen

Laut den meisten Angaben liegt der schwierigste Teil der Integration von Spring Boot Agents nicht in der KI. Das Verhalten von Modellen, Prompt-Engineering sowie die Schnittstelle zur Aufrufung von Tools lassen sich in etwa einer Woche erlernen. Der schwierige Teil besteht darin, dass Javas synchrones Erbe mit der asynchronen, mehrstufigen Art der Agentausführung kollidiert.

Das Anfrage-Antwort-Modell von Spring Boot setzt voraus, dass die Ausführungsdauer begrenzt ist. Ein Agent tut das nicht – er führt so viele Tool-Aufrufe durch, wie die Aufgabe erfordert, und führt so viele Überlegungsschritte aus, wie nötig, ohne Kenntnis von der 30-sekündigen Gateway-Timeout-Zeit. Agentenbasierte Pipelines passen nicht in das Anfrage-Antwort-Muster, sondern in ein ereignisgesteuertes Muster, und je früher man diesem Ansatz folgt, desto schneller kann die Integration implementiert werden.

Teams, die am meisten Schwierigkeiten haben, versuchen, die Verarbeitung synchron bis zur Antwort des Agents fortzusetzen. Diejenigen, die am schnellsten fertig werden, führen den Agenten als Hintergrundjob aus, starten ihn auf Anfrage, liefern das Ergebnis über Polling oder WebSocket und gestalten den Servicevertrag entsprechend. Diese Neuperspektive fehlt in den Einführungsmaterialien zu Spring AI – und sollte vermutlich auch nicht enthalten sein.

Das mentale Modell, das man beibehalten sollte

Alles oben Gesagte lässt sich in einem Satz zusammenfassen: Ein KI-Agent ist ein verteiltes System mit einem nicht-deterministischen Ausführungsmotor darin.

Die Prinzipien von verteilten Systemen, die ein Java-Entwickler bereits kennt – Fehler isolieren, Verhalten beobachten, Ausführungsdauer begrenzen, Fehlerkontrakte festlegen – gelten weiterhin, allerdings mit noch größerer Bedeutung, da Fehler hier subtiler auftreten und länger dauern, bis sie sichtbar werden. Ermutigend ist, dass Spring Boot hervorragend für diese Aufgabe geeignet ist. Dependency Injection, Beobachtbarkeit durch Actuator, asynchrone Primitiven sowie ein ausgereiftes Betriebsumfeld stellen echte Vorteile dar, und Spring AI ist ein ernstzunehmendes Framework. Der Unterschied liegt im mentalen Modell und nicht in den Werkzeugen.

Die praktischen Regeln:

• Betrachten Sie einen Agenten als Schlussfolgerungszyklus und entwerfen Sie den Servicekontrakt um diesen Zyklus herum, nicht um den Modellaufruf.
• Verwenden Sie Agenten, wenn der Workflow von Informationen abhängt, die während der Ausführung gefunden werden, oder wenn die bestehende Orchestrierung anfällig und schwer zu warten ist. Vermeiden Sie sie, wenn der Workflow deterministisch ist und die regelbasierte Version funktioniert.
• Spring AI stellt das Framework bereit; Sie legen die Strategie für Tool-Fehler, Kontextbudgets und Observabilität fest.
• Betrachten Sie Kontextfenster als Verträge und überwachen Sie den Tokenverbrauch vor dem Go-Live, nicht erst nach dem ersten Incident.
• Führen Sie die Ausführung der Agenten von Anfang an asynchron durch, da ein ereignisgesteuertes Design dort hilft, wo request-response-Modelle Probleme verursachen.

Häufige Fragen

Welches Framework eignet sich am besten für Agenten in Spring Boot? Spring AI ist die am besten geeignete Option für Spring Boot-Anwendungen. LangChain4j ist eine starke Alternative mit umfassenderer Unterstützung für die Koordination mehrerer Agenten, und beide werden aktiv gewartet.

Müssen bestehende Microservices umgeschrieben werden? Nein. Der Ansatz erweitert einen Service mithilfe der @Tool-Anmerkung von Spring AI, eines ChatClient-Beans sowie der @Async-Ausführung, ohne die bestehende Service-Logik zu berühren.

Wie sollten Fehlfälle von Agenten in der Produktion behandelt werden? Jede @Tool-Methode sollte in einen Resilience4j-Circuit-Breaker eingebettet werden, der Tokenverbrauch über Micrometer erfasst werden, vor dem Go-Live eine Fehlerrate-Matrix für die Tools definiert werden und jemand dafür verantwortlich sein, die Qualität der Antworten zu überprüfen – nicht nur die Fehlerraten.

Worin unterscheidet sich ein Agent von einem einfachen LLM-Aufruf? Ein einfacher Aufruf umfasst eine Anfrage und eine Antwort. Ein Agent ist ein Schleifenmechanismus, bei dem das Modell Tools aufrufen, die Ergebnisse lesen, darüber nachdenken und entscheiden kann, ob es fortfahren oder über mehrere Schritte hinweg antworten soll.

Ist Spring Boot für Produktivumgebungen mit Agentenlasten bereit? Ja, sofern die richtigen architektonischen Entscheidungen getroffen werden. Asynchrone Ausführung, Circuit Breaker, Token-Metriken sowie explizite Verwaltung des Kontextfensters sind alle mit vorhandenen, stabilen Bibliotheken realisierbar.

Wo passt RAG hinein? RAG ist nur eines von mehreren Tool-Modellen: Der Agent holt relevante Dokumente aus einem Vektorlagerraum, um seinen Kontext vor der Logikverarbeitung zu erweitern. Es hilft, wenn ein Agent auf eine umfangreiche Wissensbasis angewiesen ist, ist aber nicht für jede Integration erforderlich und fügt nur dann Komplexität hinzu, wenn eine Begrenzung des Kontextfensters echte Probleme verursacht.