KI-Agenten für Jakarta EE

KI-gestützte Werkzeuge werden für die Jakarta-EE-Entwicklung zunehmend wertvoll – insbesondere dann, wenn sie mit laufenden Servern interagieren, Upgrades automatisieren und die Anwendungsleistung optimieren können, anstatt lediglich Code zu generieren.

Dieser Artikel untersucht praxisnahe Anwendungsfälle von KI-Agenten, die mit Jakarta-EE-Servern kommunizieren, asadmin-Befehle ausführen, Metriken analysieren und konkrete Empfehlungen für die Entwicklung und Wartung von Unternehmensanwendungen liefern.

Warum Jakarta EE einen KI-Agenten benötigt

Jakarta EE definiert die Spezifikation. Der Betrieb auf einem realen Anwendungsserver erfordert jedoch zwei Arten von Spezialwissen: das Verständnis der Spezifikation selbst – einschließlich API-Änderungen zwischen EE 8, 9, 10 und 11, CDI-Discovery-Regeln und Persistenzsemantik – sowie Wissen über die Laufzeitumgebung. Bei Payara umfasst dies Hunderte von asadmin-Unterbefehlen, die Struktur der domain.xml, JMX-MBean-Namenskonventionen und den Monitoring-REST-Baum.

Früher befand sich dieses Wissen oft nur in den Köpfen einiger weniger erfahrener Teammitglieder. Ein LLM, das über strukturierte Tool-Aufrufe mit einem laufenden Payara Server verbunden ist, verändert diesen Ansatz grundlegend. Statt Dokumentationen und Administrationswerkzeuge manuell zu durchsuchen, können Entwickler Fragen in natürlicher Sprache stellen. Der Agent wählt die passenden Werkzeuge aus, führt die erforderlichen Aktionen aus und liefert die Antwort.

Die beiden Werkzeuge

Dieser Artikel behandelt zwei Werkzeuge der Payara-Plattform:

• Payara AI Agent (payara/ecosystem-ai) ist ein Tool-Calling-Agent mit zahlreichen Werkzeugen für Analyse laufender Server, Quellcodebearbeitung, Projektgenerierung und semantische Dokumentationssuche. Er kann als CLI-REPL, browserbasierte Chat-Oberfläche, MCP-Server für Werkzeuge wie Claude oder Gemini, eingebettete Java-Bibliothek oder über das Payara Server Maven Plugin verwendet werden.
• AdvisorTool (payara/AdvisorTool) ist ein Maven-Plugin für Payara Enterprise, das zwei Ziele verfolgt. „advise“ führt eine statische Analyse im reinen Lesezugriff durch. „upgrade“ (geplant für eine zukünftige Version von Payara Enterprise) ist ein Agent, der nach dem Prinzip „Wahrnehmen – Handeln – Überprüfen“ arbeitet: Er wendet Empfehlungen direkt auf den Quellcode an, kompiliert diesen zur Überprüfung der Änderungen und setzt den Vorgang fort, bis das Projekt bereinigt ist.
  Während „advise“ bereits verfügbar ist, steht die KI-gestützte „upgrade“-Funktion noch nicht allgemein zur Verfügung.

Der eine Ansatz ist dialogorientiert, der andere deterministisch. Gemeinsam decken sie viele der Aufgaben ab, die mir bei der Arbeit mit Jakarta-EE-Anwendungen regelmäßig begegnen. Um ihren Nutzen zu verstehen, lohnt es sich jedoch zunächst zu betrachten, warum diese Projekte überhaupt entstanden sind.

Die ursprüngliche Idee hinter dem Payara AI Agent war nicht, Administrationswerkzeuge oder Dokumentationen zu ersetzen. Diese existieren bereits und erfüllen ihren Zweck sehr gut. Ziel war vielmehr, die ständigen Kontextwechsel zu reduzieren, die den Arbeitsalltag vieler Entwickler prägen.

Eine typische Fehlersuche erfordert oft den Wechsel zwischen Terminalfenstern, Server-Logs, JMX-Metriken, Dokumentationsseiten, GitHub-Issues, Monitoring-Dashboards und dem Quellcode. Jede dieser Aufgaben ist für sich genommen überschaubar, doch das wiederholte Wechseln zwischen den verschiedenen Werkzeugen kostet Zeit und unterbricht den Arbeitsfluss.

Der Agent fungiert daher als zentraler Einstiegspunkt für all diese Systeme. Anstatt sich merken zu müssen, wo bestimmte Informationen zu finden sind, können Entwickler ihre Fragen einfach in natürlicher Sprache stellen. Der Agent sammelt anschließend den relevanten Kontext aus den verfügbaren Werkzeugen und stellt die benötigten Informationen gebündelt bereit.

Arbeiten mit asadmin

Die Unterstützung für die Generierung von asadmin-Befehlen entstand aus einem ganz praktischen Grund: Ich hatte es satt, ständig die Syntax nachschlagen zu müssen. Selbst nach vielen Jahren mit Payara gibt es Befehle, die so selten verwendet werden, dass ich regelmäßig wieder zur Dokumentation greifen muss.

Jeder, der schon einmal mit asadmin gearbeitet hat, kennt dieses Problem. Die exakten Unterbefehle, Optionen und Eigenschaftsformate sind nicht immer leicht zu merken. Statt die Dokumentation immer wieder zu durchsuchen, kann der Agent den benötigten Befehl direkt aus einer natürlich formulierten Anfrage erzeugen.

Die Referenzdokumentation wird beim Start indexiert und an die tatsächlich installierte Payara-Version angepasst. Dadurch entsprechen die vorgeschlagenen Befehle exakt der verwendeten Serverversion.

payara > Erstelle einen JDBC-Connection-Pool für PostgreSQL mit maximal 20 Verbindungen

asadmin create-jdbc-connection-pool \
    --datasourceclassname=org.postgresql.ds.PGConnectionPoolDataSource \
    --restype=javax.sql.ConnectionPoolDataSource \
    --property user=myuser:password=secret:serverName=localhost:portNumber=5432:databaseName=mydb \
    --maxpoolsize=20 --steadypoolsize=5 myPostgresPool

asadmin create-jdbc-resource --connectionpoolid=myPostgresPool jdbc/myDS

Sie erhalten die korrekten Optionen und die richtige Syntax für die Property-Strings (durch Doppelpunkte getrennt – ein Punkt, bei dem man sich manuell leicht vertut). Statt auf möglicherweise ungenaue Vorschläge aus Trainingsdaten zurückzugreifen, basieren die generierten Befehle auf der tatsächlichen Dokumentation und Konfiguration der verwendeten Payara-Version.

Generierung neuer Jakarta EE-Projekte

Das Erstellen eines neuen Projekts ist zwar nicht schwierig, aber es handelt sich um eine repetitive Aufgabe. Die meisten Entwickler haben schon unzählige Male denselben REST-Endpunkt, dieselbe Persistence Unit und denselben Health Check erstellt. Der Agent automatisiert genau diesen Ausgangspunkt.

Anstatt mit einem leeren Projekt zu beginnen und die erforderlichen Abhängigkeiten sowie Konfigurationsdateien selbst zusammenzustellen, können Sie die gewünschte Anwendung beschreiben und den Agenten die Grundstruktur generieren lassen.

payara > Erstellen Sie einen Jakarta EE 11-REST-Service für Payara 7 mit JPA und MicroProfile Health.

Sie erhalten ein fertiges Projekt: eine pom.xml mit den passenden Maven-BOMs, eine @ApplicationPath JAX-RS-Anwendungsklasse, eine CDI-Bean mit einer JPA-@Entity-Annotation, eine persistence.xml-Datei und eine sofort einsatzbereite HealthCheck-Implementierung.

Da der Agent auf der offiziellen Dokumentation basiert, werden Jakarta EE 8- und EE 11-Annotationen nicht vermischt.

Aktualisierung bestehender Anwendungen

Die Umbenennung von javax.* zu jakarta.* erfolgt rein mechanisch. Bei den übrigen Änderungen ist das nicht der Fall. CDI 4.0 hat den Standardmodus für die Bean-Erkennung in EE 10 geändert; dadurch ist ein POJO, das unter EE 9 implizit als @Dependent galt, plötzlich nicht mehr injizierbar, ohne dass dies explizit gemeldet wird. Jakarta Persistence 3.1 hat Eigenschaften umbenannt. PolicyContext.getContext verwendet nun einen generischen Rückgabetyp. In EE 11 wurden zudem mehrere als veraltet markierte APIs vollständig entfernt.

Das Ziel des anstehenden AdvisorTool-Upgrades ist es, dies mithilfe eines Maven-Befehls zu bewältigen, den Sie in Ihre CI-Pipeline integrieren können:

mvn fish.payara.advisor:advisor-maven-plugin:2.1-SNAPSHOT:upgrade

Intern arbeitet das Upgrade mit einer Schleife:

Beim ersten Projekt, für das ich dieses Verfahren anwandte, gab es 287 Advisor-Meldungen in 42 Quelldateien. Der Prozess war nach vier Durchläufen abgeschlossen, und die Test-Suite lief erfolgreich durch. In der Praxis ist nicht entscheidend, dass der Agent bei jeder Änderung sofort alles richtig macht. Vielmehr kommt es auf die Feedback-Schleife an: Wenn eine Migration ein Kompilierungsproblem verursacht, deckt der Build-Prozess dieses umgehend auf. So kann der Agent den Fehler analysieren und einen Korrekturversuch unternehmen, bevor er mit der Arbeit fortfährt.

Migrationspfade:

Jeder Tool-Aufruf wird in der Datei payara-ai-agent.log protokolliert, sodass Sie nachvollziehen können, welche Änderungen vorgenommen wurden.

Diagnose von Problemen auf einem laufenden Server

Diese Tools sind für die Analyse laufender Server ausgelegt: runAsadmin, fetchMonitoringEndpoint, queryJmxMbean, getDomainXml, tailServerLog, summarizeRecentErrors, fetchJvmThreadDump und einige weitere.

payara > Der Heap ist zu 90 % belegt – was verbraucht den Speicher?

Der Agent ruft generate-jvm-report --type=summary auf, ruft das MBean java.lang:type=Memory ab und liest die letzten 200 Zeilen der server.log im „Tail“-Modus, um nach einem OutOfMemoryError zu suchen. Anschließend fügt er diese drei Signale zu einer Diagnose zusammen.

payara > Beim jdbc/myDS-Pool kommt es ständig zu Timeouts.

Hier wird getConnectionPoolStats aufgerufen, die Warteschlangenlänge und die maximale Wartezeit ausgelesen und eine von drei Maßnahmen vorgeschlagen: die Poolgröße erhöhen, die Verbindungsvalidierung aktivieren oder nach einem Speicherleck suchen. (Es kann anhand einer einzigen Abfrage nicht sagen, welche Maßnahme die richtige ist, aber es zeigt an, wo man als Nächstes suchen sollte.)

payara > Anfragen sind langsam und ich sehe Thread-Pool-Warnungen im Log

Er ruft das Thread-Pool-MBean ab, liest die Konfiguration des HTTP-Listeners aus und gleicht Log-Fingerabdrücke mit dem Issue-Tracker von Payara auf GitHub ab. Oftmals findet sich dabei ein bereits geschlossenes Ticket, das genau die passende Lösung enthält.

Wenn Sie PAYARA_AI_ASADMIN_AUTOEXEC=all setzen, kann der Agent die Fehlerbehebung direkt anwenden. Die meisten Nutzer belassen es jedoch bei der Standardeinstellung „readonly“.

Verständnis von Metriken und Überwachungsdaten

payara > Gib mir eine Zusammenfassung des Gesundheitszustands der laufenden Anwendung

Hinter der Gesundheitsübersicht steckt keine Magie. Sie fasst im Wesentlichen Informationen zusammen, die man auch selbst aus /health, /metrics, JMX und Server-Monitoring-Daten abrufen könnte. Der Unterschied besteht darin, dass sie all diese Daten in einer einzigen Ansicht bündelt. Ist das Monitoring deaktiviert, werden die entsprechenden Aufrufe zur Aktivierung angezeigt.

Aktivierung der bedarfsgesteuerten Überwachung:

payara > Vollständige Überwachung für diese Domain aktivieren

Der Agent setzt pro Modul einen asadmin-Aufruf ab. Die durch Kommas getrennte Variante (ein Aufruf für mehrere Module) funktioniert bei aktuellen Payara-Versionen nicht, was zu Problemen bei vielen Skripten führt, die aus älteren Dokumentationen übernommen wurden:

asadmin set-monitoring-service-configuration \
    --mbeanEnabled=true --monitoringEnabled=true --target=server-config

asadmin set-monitoring-level --level=HIGH --module=jvm                --target=server-config
asadmin set-monitoring-level --level=HIGH --module=jdbcConnectionPool --target=server-config
asadmin set-monitoring-level --level=HIGH --module=threadPool         --target=server-config
# … one call per module

Untersuchung von Fehlern

payara > Welche Fehler sind in der letzten Stunde aufgetreten?

„summarizeRecentErrors“ wertet die letzten Logeinträge aus, gruppiert Exceptions anhand eines Fingerabdrucks – bestehend aus der Exception-Klasse und dem ersten charakteristischen Stack-Frame –, sortiert sie nach Häufigkeit und gleicht die Spitzenreiter mit dem Issue-Tracker von Payara auf GitHub ab. Die Antwort liest sich wie eine Triage-Notiz:

3 verschiedene Fehlermuster gefunden:

1. NullPointerException in MyService.processOrder, 47 Vorkommen. Wahrscheinlich ein Fehler bei der CDI-Injection; prüfen Sie, ob MyService eine Bean-definierende Annotation besitzt.
2. EJBException: Transaktion zurückgesetzt (Rollback), 12 Vorkommen. Ursache ist eine ConstraintViolationException bei Order.customerId. Bekanntes Problem: payara/Payara#6234, behoben in Version 6.2025.6.
3. Connection refused: localhost:5432, 3 Vorkommen. Datenbank zeitweise nicht erreichbar.

Was normalerweise das manuelle Durchsuchen von Protokollen, die Überprüfung von Stack-Traces und das Durchforsten von Issue-Trackern erfordern würde, lässt sich oft auf ein kurzes Gespräch mit dem Agenten reduzieren. Dieser trägt Informationen aus verschiedenen Quellen zusammen und präsentiert die wahrscheinlichsten Ursachen sowie Vorschläge für die nächsten Schritte.

So funktioniert es

Der Agent nutzt die „Tool-Calling“-Schleife von LangChain4j AiServices. Jede Funktion ist als Java-Methode mit der Annotation @Tool definiert, und das LLM entscheidet, welche Tools in welcher Reihenfolge aufgerufen werden. Es gibt keine fest programmierte Routing-Logik.

Der RAG-Index wird auf Basis des Payara-Dokumentations-Repositorys und des Jakarta EE-Tutorials erstellt. Die Erstellung der Embeddings erfolgt direkt im Prozess mittels AllMiniLmL6V2EmbeddingModel (ONNX); es wird also keine externe Embedding-API benötigt. Beim ersten Start wird ein vorgefertigter Index heruntergeladen, der auf die Jakarta-EE-Version des laufenden Servers abgestimmt ist: EE 8 für Payara 5, EE 10 für Payara 6 sowie EE 10 und 11 für Payara 7.

Wenn Sie den Agenten in einen MCP-kompatiblen Client (Claude Code, Claude Desktop, Cursor, Gemini CLI) einbinden, steuert das LLM des Clients die Tools. In diesem Fall benötigen Sie keinen PAYARA_AI_API_KEY, da die IDE das Modell bereitstellt.

Zwei sich ergänzende Werkzeuge

Beide lesen dieselbe Provider-Konfiguration:

export PAYARA_AI_PROVIDER=ANTHROPIC       # OPEN_AI, GOOGLE, OLLAMA, LM_STUDIO, …
export PAYARA_AI_API_KEY=sk-ant-…
export PAYARA_AI_MODEL=claude-sonnet-4-6  # optional

Ein einziger Satz an Zugangsdaten deckt die gesamte Toolchain ab.

Erste Schritte

Payara AI Agent (CLI / browser / MCP/ Payara Server Maven Plugin)

Die veröffentlichte JAR-Datei ist auf Maven Central verfügbar; der schnellste Weg ist daher, sie direkt zu beziehen:

curl -LO https://repo1.maven.org/maven2/fish/payara/tools/payara-ai-agent/1.0.0-Alpha3/payara-ai-agent-1.0.0-Alpha3.jar

# CLI REPL
java -cp payara-ai-agent-1.0.0-Alpha3.jar fish.payara.tools.ai.cli.PayaraAgentMain

# Browser-Benutzeroberfläche unter http://localhost:8088
java -cp payara-ai-agent-1.0.0-Alpha3.jar fish.payara.tools.ai.web.PayaraWebMain

# MCP-Server für Claude Code
claude mcp add payara java -- -jar payara-ai-agent-1.0.0-Alpha3.jar

Wenn Sie bereits das Payara Server Maven Plugin verwenden, können Sie den Agenten gemeinsam mit dem Server starten lassen. Fügen Sie das Plugin zu Ihrer pom.xml hinzu:

<plugin>
    <groupId>fish.payara.maven.plugins</groupId>
    <artifactId>payara-server-maven-plugin</artifactId>
    <version>1.2.0</version>
    <configuration>
        <payaraServerVersion>6.2025.11</payaraServerVersion>
    </configuration>
</plugin>

Starten Sie dann den Server auf die übliche Weise, und der Agent startet mit ihm:

set PAYARA_AI_AGENT=true
set PAYARA_AI_API_KEY=sk-svc ... ...
mvn payara-server:dev

AdvisorTool for Payara Enterprise

# Nur Analyse
mvn fish.payara.advisor:advisor-maven-plugin:2.0:advise -DadviseVersion=11

# Vollständiges KI-gestütztes Upgrade (interaktiver Modus pausiert vor jedem Schreibvorgang einer Datei)
mvn fish.payara.advisor:advisor-maven-plugin:2.1-SNAPSHOT:upgrade \
    -DadvisorVersion=11 -Dpayara.advisor.maxRounds=5 -Dpayara.ai.interactive=true

Zusammenfassung

Nachdem ich diese Tools eine Zeit lang genutzt habe, bin ich zu der Erkenntnis gelangt, dass ihr größter Vorteil nicht in der Codegenerierung liegt. Vielmehr geht es darum, den Zeitaufwand für die Informationssuche zu verringern. Ob es nun darum geht, den richtigen asadmin-Befehl zu finden, die Ursache für einen erschöpften Connection-Pool zu verstehen oder eine Jakarta-EE-Migration durchzuführen – ein Großteil der Arbeit besteht darin, den nötigen Kontext zu erfassen, anstatt die eigentliche Lösung umzusetzen. Genau hier erweist sich die Kombination aus Payara AI Agent und AdvisorTool als besonders wertvoll.

Sie machen zwar kein fundiertes Verständnis von Jakarta EE überflüssig, reduzieren jedoch den wiederkehrenden Aufwand auf dem Weg von einem Problem zur Lösung.