ALBERT l AI Coding Agents anpassen

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins ALBERT l AI Coding Agents. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Diese Dokumentation richtet sich an Entwickler. Sie beschreibt, wie Sie das Plugin um weitere Coding Agents erweitern, wie Sie die Berechtigungsprüfung in eigenem JavaScript verwenden, welche Dienste die Einrichtung bereitstellt und wie Sie die Erkennung der Sitzungen weiterer Coding Agents ergänzen.

Die Liste der Coding Agents

Welche Coding Agents es gibt, steht in der MetaDB unter:

MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/coding-agents

Jeder Coding Agent ist dort ein eigener Eintrag mit Unterwerten. Alle Werte sind Zeichenketten.

Wert	Beschreibung
displayName	Anzeigename im Menü, in der Abfrage und im Stand-Hinweis, zum Beispiel Claude Code. Ohne Angabe wird die Kennung angezeigt.
urlTemplate	Pflicht. Die Adresse, über die der Browser den Coding Agent startet. Der Platzhalter `${prompt}` nimmt den Übergabetext auf, zum Beispiel `claude://code/new?q=${prompt}` oder `codex://new?prompt=${prompt}`.
acl	Pflicht. Die ACL, die festlegt, wer den Coding Agent starten darf. Ein Benutzer darf ihn starten, wenn er die ACL sehen darf.
icon	Symbol im Menü. Vorgabe: `ionicon:open-outline`.
maxPromptLength	Höchstlänge des Übergabetextes in Zeichen, damit die Startadresse nicht zu lang wird. Sie gilt für den ganzen Text, also für den festen Kopf (Chat-ID, Hinweis auf den Skill, Anweisungen) und den Benutzertext; gekürzt wird nur der Benutzertext. Gezählt wird vor der URL-Kodierung, die Adresse selbst wird also länger. Der vollständige Text steht im Chat. Vorgabe: 10000.
active	Nur der Wert `false` schaltet den Coding Agent ab. Diesen Wert setzt auch die Konfigurationsmaske Coding Agents.

Neben den Coding Agents liegen im selben Eintrag zwei einzelne Werte: defaultAgent (Standardziel: Kennung eines Coding Agents, albert für ALBERT | AI oder leer) und askAgainAfterMinutes (Ruhezeit in Minuten). Beide pflegen Sie üblicherweise über die Konfigurationsmaske, siehe ALBERT l AI Coding Agents einrichten.

Achtung: Die Kennung albert ist für ALBERT | AI selbst reserviert und darf keinen Coding Agent benennen. Benennen Sie die Kennung eines Coding Agents außerdem nicht um: Sie steht in jedem Chat, der an diesen Coding Agent übergeben wurde.

Einen weiteren Coding Agent ergänzen

Mitgeliefert werden Claude Code und Codex. Weitere Coding Agents ergänzen Sie ohne Änderung am Programmcode. Oberfläche, Übergabetext und Zustandsführung sind agentenübergreifend angelegt.

Legen Sie eine Benutzergruppe für den Coding Agent an.
Legen Sie eine ACL an, die dieser Gruppe Leserecht gibt. Setzen Sie an der ACL die Einstellung, dass sie auch für Administratoren gilt – so halten es die mitgelieferten ACLs, und nur so steuert die Gruppe den Zugang wirklich.
Legen Sie in der MetaDB unter dem oben genannten Pfad einen Eintrag mit der Kennung des Coding Agents an, mindestens mit urlTemplate und acl.
Ein Eintrag ohne diese beiden Werte gilt als unvollständig, wird übergangen und im Server-Log gemeldet. Einträge, deren Kennung mit # beginnt, gelten als Kommentar.
Nehmen Sie die Benutzer in die Gruppe auf.

Ergebnis: Der Coding Agent erscheint in der Konfigurationsmaske und – für die Mitglieder der Gruppe – im Menü am Übergabe-Knopf und in der Abfrage beim Absenden, sobald ein Chat-Fenster neu geöffnet wird.

Hinweis: Die Einrichtung per Download (Claude Code einrichten) gibt es nur für Claude Code. Ein weiterer Coding Agent muss beim Benutzer von Hand über MCP mit agorum core pro verbunden werden und die Werkzeuge zum Lesen und Rückmelden eines Chats sehen. Ein Update des Plugins lässt eigene Einträge unberührt.

Sitzungen weiterer Coding Agents erkennen

Ist die Protokollierung der Sitzungen eingeschaltet, ordnet agorum core pro jeden MCP-Aufruf, soweit möglich, der Sitzung zu, aus der er stammt. Viele Coding Agents schicken dazu im Feld _meta jedes MCP-Aufrufs eine eigene Kennung mit. Welche Schlüssel das sind, legen Erkennungsregeln fest. Ein Aufruf mit einer solchen Kennung gehört eindeutig zur Sitzung dieses Coding Agents und seines Benutzers.

Mitgeliefert werden Regeln für Claude Code, Codex, VS Code, OpenCode und ChatGPT. Claude Code schickt nur die Kennung des Werkzeugaufrufs; zu welcher Sitzung er gehört, melden dort die Hooks, und agorum core pro führt beides zusammen.

Weitere Regeln ergänzen Sie in der MetaDB, je Regel ein eigener Eintrag unter:

MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/sessions/rules/<Name der Regel>

Wert	Beschreibung
harness	Pflicht. Die Kennung des Coding Agents, unter der seine Sitzungen geführt werden, zum Beispiel `codex`. Ein Eintrag ohne diesen Wert wird übergangen.
session	Die Schlüssel in `_meta`, die die Kennung der Sitzung enthalten, durch Komma getrennt, zum Beispiel `sessionId,threadId`. Es zählt der erste gefundene. Ein Schlüssel wird wörtlich genommen: `vscode.conversationId` ist ein Schlüssel, kein Pfad.
call	Der Schlüssel in `_meta`, der die Kennung des Werkzeugaufrufs enthält, zum Beispiel `callId`.
displayName	Der Name des Coding Agents für Menschen, zum Beispiel Codex. Er steht im Usage-Protokoll an jedem Eintrag der Sitzung und erscheint so in der ALBERT \| AI Kostenkontrolle. Ohne Namen erscheint die Kennung aus `harness`.

Hinweis: Eine Regel aus der MetaDB mit dem Namen einer mitgelieferten Regel ersetzt diese, etwa codex. Ein Eintrag, dessen Name mit # beginnt, wird übergangen. Eine mitgelieferte Regel lässt sich damit nicht abschalten: #codex lässt die Regel codex aktiv.

So sähe die mitgelieferte Regel für Codex als MetaDB-Einträge aus. Tragen Sie sie so ein, ersetzen Sie damit nur die gleichnamige mitgelieferte Regel:

MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/sessions/rules/codex/harness codex
MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/sessions/rules/codex/session sessionId,threadId
MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/sessions/rules/codex/call callId
MAIN_MODULE_MANAGEMENT/customers/agorum.ai.codingagents/sessions/rules/codex/displayName Codex

Die Berechtigungsprüfung im eigenen Code verwenden

Die Liste der Coding Agents lesen Sie über die Bibliothek des Plugins ALBERT | AI:

let codingAgents = require('/agorum/roi/customers/agorum.ai/js/lib/coding-agents');

Funktion	Beschreibung
list()	Liefert alle vollständigen und aktiven Coding Agents, sortiert nach Anzeigename – ohne Prüfung der Berechtigung.
listAllowed(sessionController)	Liefert alle aktiven Coding Agents, die der Benutzer starten darf.
getAllowed(id, sessionController)	Liefert einen bestimmten Coding Agent, sofern er aktiv ist und der Benutzer ihn starten darf, sonst `null`.
listTargets(sessionController)	Liefert die Ziele, die die Chat-Eingabe anbietet: die erlaubten Coding Agents und zuletzt ALBERT \| AI.
readSettings()	Liefert Standardziel und Ruhezeit.

Die Bibliothek liest nur. Zum Schreiben der Einstellungen – aktiv, Standardziel, Ruhezeit – gibt es im Plugin die Bibliothek /agorum/roi/customers/agorum.ai.codingagents/js/lib/config.js mit read(), validate() und write(); write() prüft die Berechtigung für die ALBERT | AI Einstellungen.

Die Angabe sessionController ist optional. Ohne sie gilt der angemeldete Benutzer; mit ihr wird die Berechtigung mit den Rechten des Benutzers dieser Sitzung geprüft.

Tipp: Damit lässt sich die Rechteprüfung auch für einen anderen Benutzer absichern als den, der den Code gerade ausführt – etwa in einem Dienst, der unter einer administrativen Sitzung läuft.

ALBERT | AI selbst ist kein Coding Agent: list(), listAllowed() und getAllowed() liefern es nie. Eine Übergabe an die Kennung albert ist deshalb nicht möglich.

Die Einrichtungsdienste

Die Einrichtung von Claude Code läuft über zwei Dienste des Plugins:

Dienst Beschreibung

/api/rest/custom/agorum.ai.codingagents.setup/ Mit Anmeldung. Liefert den Stand für die Oberfläche (status) und die Einrichtungsdatei (connect.cmd, connect.sh, jeweils mit ?variant=use oder ?variant=dev). Die Einrichtungsdatei enthält ein frisch ausgestelltes Einrichtungstoken. Die Berechtigung wird hier geprüft, nicht nur über den Menüeintrag.

/api/rest/custom/agorum.ai.codingagents.setup.noauth/ Ohne Anmeldung, weil Claude Code und das Einrichtungsskript keine Sitzung haben. Liefert Inhalte ohne Geheimnis: Marketplace (marketplace.json), Plugin-Archive (plugin/<Name>.zip) und Einrichtungsskripte (setup.ps1, setup.sh). Einzige Ausnahme ist redeem (POST): Es tauscht das Einrichtungstoken gegen das Zugriffstoken, prüft dabei die Berechtigung erneut und ergänzt fehlende Mitgliedschaften in den Werkzeuggruppen. Die Plugin-Archive heißen agorum-core-use.zip und agorum-core-coding.zip.

Dienst	Beschreibung
/api/rest/custom/agorum.ai.codingagents.setup/	Mit Anmeldung. Liefert den Stand für die Oberfläche (`status`) und die Einrichtungsdatei (`connect.cmd`, `connect.sh`, jeweils mit `?variant=use` oder `?variant=dev`). Die Einrichtungsdatei enthält ein frisch ausgestelltes Einrichtungstoken. Die Berechtigung wird hier geprüft, nicht nur über den Menüeintrag.
/api/rest/custom/agorum.ai.codingagents.setup.noauth/	Ohne Anmeldung, weil Claude Code und das Einrichtungsskript keine Sitzung haben. Liefert Inhalte ohne Geheimnis: Marketplace (`marketplace.json`), Plugin-Archive (`plugin/<Name>.zip`) und Einrichtungsskripte (`setup.ps1`, `setup.sh`). Einzige Ausnahme ist `redeem` (POST): Es tauscht das Einrichtungstoken gegen das Zugriffstoken, prüft dabei die Berechtigung erneut und ergänzt fehlende Mitgliedschaften in den Werkzeuggruppen. Die Plugin-Archive heißen `agorum-core-use.zip` und `agorum-core-coding.zip`.

Token	Beschreibung
Einrichtungstoken	Gilt zehn Minuten und taugt nur zum Abholen des Zugriffstokens. Innerhalb dieser Zeit lässt es sich mehrfach einlösen. Es ist mit einem eigenen Geheimnis des Plugins signiert und nicht mit dem des Systems – an der MCP-Schnittstelle ist es damit wertlos. Die Variante, für die es ausgestellt wurde, steht im Token selbst und lässt sich beim Einlösen nicht ändern.
Zugriffstoken	Ein JWT des Benutzers ohne Ablaufdatum, ausgestellt auf demselben Weg wie über den JWT-Generator. Zurückziehen siehe ALBERT l AI Coding Agents berechtigen.

Hinweis: Das Einrichtungstoken wird beim Einlösen im eigenen Header X-Agorum-Setup-Token übergeben, nicht als Authorization: Bearer und nicht als Parameter. So landet es weder in Protokollen noch in Zwischenspeichern.

Welche Plugins das Marketplace anbietet, ergibt sich aus den Skills, die auf dem System vorhanden sind: Die Variante zum Arbeiten enthält den Skill agorum-core-ai-use, die Variante zum Entwickeln die Skills agorum-core-ai-coding und agorum-core-ai-backend. Fehlt ein Skill-Ordner, wird die Variante nicht angeboten. Die Version eines Plugins ist die Version seines ersten Skills.

Wo was liegt

Gegenstand	Ort
Konfigurationsprojekt	agorum.ai.codingagents
Bibliothek zur Liste der Coding Agents und Übergabe eines Chats	im Plugin ALBERT \| AI (agorum.ai), unter `js/lib/coding-agents.js` und `js/lib/chat-handover.js`
Protokollierung der Sitzungen	im Plugin selbst: Handler-Konfiguration `agorum_ai_codingagents_sessions` (Anzeigename Coding Agents: Sitzungen protokollieren), Erkennungsregeln unter `js/lib/sessions/session-rules.js`
KI-Wissen zum Plugin	im Plugin selbst, unter `ai/knowledge/agorum-core-development/project-infos/agorum.ai.codingagents`
Skills, Werkzeuge und Werkzeuggruppen	nicht hier, sondern in den Plugins ALBERT \| AI Agents und ALBERT \| AI Dev