Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht
Navigation: Dokumentationen agorum core > agorum core Module und Plugins > ALBERT agorum core ai
Hinweise:
Die JavaScript-Bibliothek agorum.ai/js/lib/ai ermöglicht es Entwicklern, leistungsfähige, KI-gesteuerte Konversationsanwendungen zu erstellen und zu implementieren.
Sie können mit dem Plugin agorum core ai KI-Sprachmodelle in agorum core pro anbinden und die KI in Dokumentenmanagementprozesse integrieren.
Mit der Bibliothek können Sie eigene Anwendungen und Prozesse unter Verwendung der konfigurierten KI-Sprachmodelle einrichten und Ihren Benutzern zur Verfügung stellen. Es werden synchrone und asynchrone Chat-Anfragen unterstützt.
Hinweis: Die Verarbeitung erfolgt in einer eigenen Transaktion. Wenn Sie auf Objekte zugreifen wollen, die kurz zuvor erst angelegt oder geändert worden sind, müssen Sie die Transaktion vorher committen.
Binden Sie dazu die Bibliotheken stets am Anfang eines Skripts ein:
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai');
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); // synchronous call of ai chat let response = ai.chat( // ai preset 'openai-test', // data { text: 'Hello World. What a wonderful day this is. How are you doing?', /* attachments: [ // 'uuid of attachment' ], context: null, // 'Optional context', images: [ // 'uuid of image or base64 content of image' ], */ }, // parameters { // timeout: 123456, // max_tokens: 1000, // temperature: 1, }, // history [], // callback function is called while streaming // finished is true when chat is done (streamResponse, finished) => { console.log('stream response', streamResponse, finished); }, // customErrorHandling: if true, no exception is thrown. Error is returned in response. true ); response;
Dieses Beispiel zeigt, wie die Bibliothek agorum.ai/jb/lib/ai verwendet wird, um eine synchrone Kommunikation mit dem KI-Modell names "openai-test" aufzubauen und eine einfache Anfrage mit den Standardeinstellungen an die KI zu schicken, ohne zusätzliche Kontextinformationen anzugeben. Während des Streamings wird eine Callback-Funktion ausgeführt, um auf die Antworten des KI-Modells zu reagieren. Falls ein Fehler auftritt, wird keine Exception ausgelöst, weil das benutzerdefinierte Fehlermanagement aktiviert ist, wodurch der Fehler als Teil der Antwort ausgegeben wird.
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); // example callback function for response handling function handleStreamResponse(streamResponse, finished) { // Logging of the current piece of the response console.log('Current stream response:', streamResponse); // Check whether the chat has been completed if (finished) { console.log('Chat response was returned: ' + streamResponse.text); } } // asynchronous call of ai chat // does the same as the synchronous call, but returns the // callback immediately and has to be used to handle the response ai.chatAsync( // ai preset 'openai-test', // data { text: 'Hello World. What a wonderful day this is. How are you doing?', attachments: [ // 'uuid of attachment' ], context: null, // 'Optional context', images: [ // 'uuid of image or base64 content of image' ], }, // parameters { timeout: 123456, }, // history [], // callback function is called while streaming // finished is true when chat is done handleStreamResponse );
Dieses Beispiel zeigt, wie die Bibliothek agorum.ai/jb/lib/ai verwendet wird, um eine asynchrone Kommunikation mit dem KI-Modell names "openai-test" aufzubauen und eine einfache Anfrage an die KI zu schicken, ohne zusätzliche Kontextinformationen anzugeben. Die Anfrage soll innerhalb des angegebenen Timeouts von 123456 Millisekunden verarbeitet werden. Eine Callback-Funktion namens handleStreamResponse wird verwendet, um die KI-Antworten kontinuierlich zu verarbeiten. Diese Funktion protokolliert jeden Teil der Antwort während des Streamings in die Konsole und zeigt an, wenn die gesamte Chat-Antwort abgeschlossen wurde, mit einer Ausgabe des vollständigen Antworttexts.
In diesem Beispiel erhalten Sie als Antwort Informationen nach folgendem Muster:
{ "finishReason" : "stop", "tokens" : { "output" : 28, "input" : 35, "total" : 63.0 }, "parsed" : { "code" : [ ], "xml" : [ ], "json" : [ ] }, "text" : "Hello! I'm just a computer program, so I don't have feelings, but I'm here to help you. How can I assist you today?", "history" : [ { "dateTime" : "2025-06-23T12:42:31.828Z", "role" : "system", "text" : "Voreinstellung: *openai-test*" }, { "dateTime" : "2025-06-23T12:42:31.828Z", "environment" : "chat", "role" : "user", "text" : "Hello World. What a wonderful day this is. How are you doing?" }, { "dateTime" : "2025-06-23T12:42:33.114Z", "environment" : "chat", "role" : "assistant", "text" : "Hello! I'm just a computer program, so I don't have feelings, but I'm here to help you. How can I assist you today?", "toolCalls" : [ ] } ], "toolCalls" : [ ] }
Die Antwort enthält den Antworttext, die vollständige Übersicht über die KI-Interaktion in der Historie, einen Überblick über die verwendeten Ressourcen (Tokens) und ggf. eine Struktur, die geparste Teile der Antwort als JavaScript-Code, XML oder JSON enthält.
Response-Komponente | Beschreibung |
---|---|
finishReason (string) | Zeigt den Grund an, warum die Interaktion beendet wurde: "stop" bedeutet, dass die AI geantwortet hat, ohne unterbrochen zu werden oder einen Fehler zu verursachen. |
tokens (object) | Enthält Informationen über die Anzahl der Tokens in der Anfrage und Antwort:
|
parsed (object) | Beinhaltet Arrays für geparste Datenstrukturen:
|
text (string) | Der Text der generierten Antwort des KI-Sprachmodells. |
history (array of objects) | Der Verlauf der Konversation:
|
toolCalls (array) | Der Abschnitt toolCalls ist nur relevant, wenn Sie KI-Tools im Workflow-Knoten verwenden. Der Inhalt ist abhängig von den verwendeten Tools. |
Wenn Sie mit der KI über einen Benutzerchat sprechen, können Sie Informationen direkt im Text angeben oder Dateien zusätzlich hochladen. Wenn Sie die KI programmatisch aufrufen, geben Sie diese Daten über das data-Objekt an, wenn Sie zusätzlich zu den KI-Voreinstellungen verwendet werden sollen.
Außerdem können Sie Aufrufparameter über das parameters-Objekt angeben. Die Aufrufparameter überschreiben die entsprechenden data-Einstellungen: Wenn Sie einen Kontext für parameters angeben, überschreibt dieser Kontext die Angaben aus der KI-Voreinstellung und dem data-Objekt.
Struktur des data-Objekts für den Chat
// data { text: 'Hello World. What a wonderful day this is. How are you doing?', attachments: [ // 'uuid of attachment' ], // Optional context. // This context is added to/combined with the context specified by the preset. context: 'You use formal language and are always polite.', images: [ // 'uuid of image or base64 content of image' ], },
Parameter | Beschreibung | Pflicht |
---|---|---|
text (string) | Der Text der Anfrage bzw. des Befehls (Prompts) an die KI. | ja |
attachments (array) | Eine optionale Liste von Anhängen, die an die KI übergeben werden (vollständiger Pfad, ID oder UUID). | nein |
context (string) | Ein optionaler Text als Kontext für den gesamten Chat. Der hier angegebene Kontext wird zum Kontext aus der KI-Voreinstellung hinzugefügt und zusammen mit dem Kontext aus dem Preset an die KI übergeben. Der Kontext erscheint in der Historie im Abschnitt system. Beispiel: "Verwende ausführliche Formulierungen und eine förmliche Sprache." Wenn bei den Aufrufparametern ein Kontext mitgegeben wird, wird der hier angegebene Kontext damit überschrieben. Im Kontext können Sie folgende Variablen verwenden:
|
nein |
images (array) | Eine optionale Liste von Bildern (vollständiger Pfad, ID oder UUID) oder Base64-Bildern. | nein |
Struktur des parameters-Objekts
// parameters { // If a context is defined here, this context overrides the context defined in the preset and the data object context: 'You use informal language and are very funny.', timeout: 123456, max_tokens: 1000, temperature: 1, },
Parameter | Beschreibung | Pflicht |
---|---|---|
timeout | Definiert den Zeitraum in Millisekunden, nach welcher Zeit die API die Verbindung zum Service abbricht, wenn das System keine Verbindung zum Service herstellen kann. | nein |
max_tokens | Die maximale Anzahl von Tokens (Wörtern oder Phrasenfragmenten), die die KI in ihrer Antwort verwenden darf. Dies wird oft dazu verwendet, die Länge der generierten Antwort zu kontrollieren. | nein |
temperature | Ein Wert, der die Kreativität oder Zufälligkeit der KI-Antwort beeinflusst. Ein höherer Wert führt zu weniger vorhersehbaren, aber kreativeren Antworten, während ein niedrigerer Wert die Antwort deterministischer macht. | nein |
historyLimit | Die Einstellung historyLimit in einem Sprachmodell (LLM) kann dazu verwendet werden, die Anzahl der vorhergehenden Interaktionen oder Nachrichten zu begrenzen, die das Modell bei der Generierung von Antworten berücksichtigt. Dies kann hilfreich sein, um den Kontext der Unterhaltung zu steuern oder die Rechenleistung zu optimieren. Zum Beispiel könnte man das historyLimit auf 5 setzen, um sicherzustellen, dass nur die letzten fünf Nachrichten in den Kontext einbezogen werden. | nein |
context | Ein optionaler Text als Kontext für die Anfage. Der hier angegebene Kontext überschreibt den Kontext aus den KI-Voreinstellungen und dem data-Objekt. Beispiel: "Verwende informelle Sprache mit lockeren Formulierungen." Im Kontext können Sie folgende Variablen verwenden:
|
nein |
Der Chat-Verlauf wird gespeichert und hat folgende Struktur.
{ "dateTime": "2025-06-23T12:06:27.520Z", "attachmentsTexts": [ "Filename: Willkommen.pdf\nuuid: 24e790a0-6c6f-11ef-b01a-00007f000101\nContent of file:\n```Text in deutscher Sprache```" ], "environment": "chat", "role": "user", "attachments": [ "24e790a0-6c6f-11ef-b01a-00007f000101" ], "text": "Übersetze den Text des Dokuments in die englische Sprache." },
{ "dateTime": "2025-06-23T12:06:31.257Z", "environment": "chat", "role": "assistant", "text": "Filename: Welcome.pdf\nuuid: 24e790a0-6c6f-11ef-b01a-00007f000101\nContent of file:\n\n```Text in English language```", "toolCalls": [] }
{ "dateTime": "2025-06-23T12:06:27.505Z", "role": "system", "text": "Sei ein Englischübersetzer" },
{ "dateTime": "2025-06-23T14:39:21.432Z", "toolResponses": [ { "response": { "isError": true, "content": [ { "text": "Error creating image", "type": "text" } ] }, "name": "create_image", "id": "call_Du7WgnglHZ4vYOA3DIMNI76L" } ], "environment": "chat", "role": "tool" },
Die Bibliothek agorum.ai/js/lib/ai enthält Funktionen, die zur Interaktion mit KI-Sprachmodellen eingesetzt werden, insbesondere können Sie synchron über die chat-Funktion und asynchron über die chatAsync-Funktion Anfragen an die KI richten.
Die chat-Funktion ist eine synchrone Funktion, die einen Chat mit dem angegebenen KI-Sprachmodell startet und eine Antwort nach dem Ende des Chats zurückgibt.
Syntax
chat(preset, data, parameters, history, callback, customErrorHandling, shouldStopCallback)
Parameter
Parameter | Beschreibung | Pflicht | Standard |
---|---|---|---|
preset (string) | Der Name der KI-Konfiguration, die verwendet werden soll. | ja | - |
data (object) | Das data-Objekt enthält die Informationen, die in Ergänzung zu den Voreinstellungen an die KI gesendet werden. Für weitere Informationen siehe Struktur des data-Objekts. |
ja | - |
parameters (object) | Zusätzliche Einstellungen zur Feinabstimmung der Anfrage, auch abhängig von der verwendeten KI. Für weitere Informationen siehe Struktur des parameters-Objekts. |
nein | - |
history (array) | Der bisherige Kommunikationsverlauf. Dieser kann auch bei einer neuen Anfrage mitgegeben werden, um den entsprechenden Kontext herzustellen. | nein | - |
callback (function) | Eine optionale Funktion, die bei Verwendung von Stream während des Empfangs aufgerufen wird:
|
nein | - |
customErrorHandling (boolean) | Wenn true, wird das benutzerdefinierte Fehlermanagement aktiviert, wodurch der Fehler als Teil der Antwort ausgegeben wird. | nein | false |
shouldStopCallback | Eine optionale Funktion, die regelmäßig aufgerufen wird, um festzustellen, ob der Chat gestoppt werden soll. | nein | - |
Beispiel
Im folgenden Beispiel wird der Inhalt der Datei Willkommen.pdf, die als Anhang über die UUID angegeben ist, in die englische Sprache übersetzt. Außerdem wird über den Kontext festgelegt, dass die Zielsprache amerikanisches Englisch ist.
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); let settings = require('/agorum/roi/customers/agorum.ai/js/lib/settings'); let objects = require('common/objects'); // synchronous call of ai chat let response = ai.chat( // ai preset 'openai-test', // data { text: 'Übersetze den Text des Dokuments in die englische Sprache.', attachments: ['e551e840-b6de-11ef-812f-02420a0a000e'], context: 'Use American English', // 'Optional context', /*images: [ // 'uuid of image or base64 content of image' ], */ }, // parameters { timeout: 6000, max_tokens: 100, temperature: 0.1, }, // history [], // callback function is called while streaming // finished is true when chat is done (streamResponse, finished) => { console.log('stream response', streamResponse, finished); }, // customErrorHandling: if true, no exception is thrown. Error is returned in response true ); response;
Rückgabewert
Die Funktion chat gibt ein chat.response-Objekt zurück, das die Antwort des KI-Sprachmodells als Text, den Nachrichtenverlauf und zusätzliche Informationen enthält, siehe Response-Struktur.
Die chatAsync-Funktion ist eine asynchrone Funktion, die sofort eine Rückmeldung gibt und die Bereitstellung einer Callback-Funktion erwartet, um Streaming-Daten zu verarbeiten.
Syntax
chatAsync(preset, data, parameters, history, callback)
Parameter
Parameter | Beschreibung | Pflicht | Standard |
---|---|---|---|
preset (string) | Der Name der KI-Konfiguration, die verwendet werden soll. | ja | - |
data (object) | Das data-Objekt enthält die Informationen, die an die KI gesendet werden. | ja | - |
parameters (object) | Zusätzliche Einstellungen zur Feinabstimmung der Anfrage, auch abhängig von der verwendeten KI. Für weitere Informationen siehe Struktur des parameters-Objekts. |
nein | - |
history (array) | Der bisherige Kommunikationsverlauf. Dieser kann auch bei einer neuen Anfrage mitgegeben werden, um den entsprechenden Kontext herzustellen. | nein | - |
callback (function) | Eine optionale Funktion, die bei Verwendung von Stream während des Empfangs aufgerufen wird, mit folgenden Parametern:
|
nein | - |
Beispiel
Im folgenden Beispiel wird der Inhalt der Datei Willkommen.pdf, die als Anhang über die UUID angegeben ist, in die englische Sprache übersetzt. Außerdem wird über den Kontext festgelegt, dass die Zielsprache amerikanisches Englisch ist.
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); let settings = require('/agorum/roi/customers/agorum.ai/js/lib/presets-settings'); let objects = require('common/objects'); // callback function for handling the ai response function handleStreamResponse(streamResponse, finished) { // Protokollierung des aktuellen Teils der Antwort console.log('Current stream response:', streamResponse); // Überprüfung, ob der vollständige Chat abgeschlossen ist if (finished) { console.log('Chat response: ' + streamResponse.text); } } // asynchronous call of ai chat ai.chatAsync( // ai preset 'openai-test', // data { text: 'Übersetze den Text des Dokuments in die englische Sprache.', attachments: ['e551e840-b6de-11ef-812f-02420a0a000e'], context: 'Use American English', // Optionaler Kontext // images: [ // 'uuid of image or base64 content of image' // ], }, // parameters { timeout: 6000, max_tokens: 100, temperature: 0.1, }, // history [], // callback function is called while streaming handleStreamResponse );
Rückgabewert
Die Funktion chatAsync gibt ein chat.response-Objekt zurück, das die Antwort des KI-Sprachmodells als Text, den Nachrichtenverlauf und zusätzliche Informationen enthält, siehe Response-Struktur.
Die Funktion chatWithToolCalls ermöglicht eine interaktive Kommunikation mit einem KI-Chat-Modell, das in der Lage ist, während des Chats zusätzliche KI-Tools aufzurufen. Die Funktion führt einen Chatvorgang durch, bei dem eine KI-Voreinstellung mit voreingestellten Konfigurationen genutzt wird. Parallel dazu werden Tools dynamisch aufgerufen, falls dies im Verlauf des Chats notwendig ist oder explizit angefordert wird.
Hinweis: Sie können diese Funktion nur verwenden, wenn Sie zusätzlich zum Plugin agorum core ai das Plugin agorum core ai agents installiert und lizenziert haben.
Syntax
chatWithToolCalls(preset, data, parameters, history, callback, customErrorHandling, shouldStopCallback)
Parameter
Parameter | Beschreibung | Pflicht | Standard |
---|---|---|---|
preset (string) | Der Name der KI-Konfiguration, die verwendet werden soll. | ja | - |
data (object) | Das data-Objekt enthält die Informationen, die an die KI gesendet werden. | ja | - |
parameters (object) | Zusätzliche Einstellungen zur Feinabstimmung der Anfrage, auch abhängig von der verwendeten KI. Für weitere Informationen siehe Struktur des parameters-Objekts. |
ja | - |
history (array) | Der bisherige Kommunikationsverlauf. Dieser kann auch bei einer neuen Anfrage mitgegeben werden, um den entsprechenden Kontext herzustellen. | nein | - |
callback (function) | Eine optionale Funktion, die bei Verwendung von Stream während des Empfangs aufgerufen wird, mit folgenden Parametern:
|
nein | - |
customErrorHandling (boolean) | Wenn true, wird das benutzerdefinierte Fehlermanagement aktiviert, wodurch der Fehler als Teil der Antwort ausgegeben wird. | nein | false |
shouldStopCallback (function) | Eine optionale Funktion, die regelmäßig aufgerufen wird, um festzustellen, ob der Chat gestoppt werden soll. | nein | - |
Beispiele
Im folgenden Beispiel wird durch den Aufruf von chatWithToolCalls mit der angegebenen KI-Voreinstellung agorum_doc_test_toolsquery eine vollständige Liste aller KI-Tools angefordert, die in der vorhandenen Installation von agorum core ai agents verfügbare sind. Da tools direkt nicht angegeben wird, werden die in der KI-Voreinstellung konfigurierten Tools genutzt, um die Anfrage zu erfüllen.
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); ai.chatWithToolCalls( 'agorum_doc_test_toolsquery', { text: 'Erstelle eine vollständige Liste aller KI-Tools', //tools: tools, // presets configured in the preset are being used }, {}, null, null, true );
Rückgabewert
Die Funktion chatWithToolCalls gibt ein chat.response-Objekt zurück, das die Antwort des KI-Sprachmodells als Text, den Nachrichtenverlauf und zusätzliche Informationen enthält, siehe Response-Struktur.
Die Funktion models wird verwendet, um alle verfügbaren Modelle eines KI-Anbieters unter Verwendung der jeweiligen Voreinstellungen abzufragen, also etwa alle Modell von OpenAI, wenn schon eine Voreinstellung für OpenAI mit API-Key existiert.
Syntax
models(preset, parameters)
Parameter
Parameter | Beschreibung | Pflicht | Standard |
---|---|---|---|
preset (string) | Der Name der KI-Voreinstellung, deren Modelle abgerufen werden sollen. | ja | - |
parameters (object) | Zusätzliche Parameter für die Anforderung (kann leer sein). | ja | - |
Beispiele
Im folgenden Beispiel werden alle verfügbaren Modelle für die KI-Voreinstellungen namens "openai-test" abgerufen:
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); // sample call for the models function let availableModels = ai.models('openai-test', {}); // log available models to console console.log('Available models:', availableModels);
Im nächsten Beispiel wird für die Modelle zusätzlich ein Timeout-Parameter angegeben:
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); // sample call for the models function let availableModels = ai.models('openai-test', { timeout: 1000 }); // log available models to console console.log('Verfügbare Modelle:', availableModels);
Rückgabewert
Die Funktion models gibt ein Array von Strings zurück, bei dem jeder String den Namen eines verfügbaren Modells darstellt, sortiert in lexikographischer Reihenfolge.
Die Funktion loadPrompt wird verwendet, um den Inhalts eines Prompts, also eines Befehls für die KI, aus einer Datei oder einem Objekt zu laden, das anhand einer ID spezifiziert wird.
Syntax
loadPrompt(id)
Parameter
Parameter | Beschreibung | Pflicht | Standard |
---|---|---|---|
id (string) | Der vollständige Pfad, die ID oder UUID des Objekts um den Inhalt zu laden. | ja | - |
Beispiele
Im folgenden Beispiel wird der Inhalt der Datei, die hier über den Platzhalter prompt-file-id beschrieben wird, geladen und anschließend wird der Inhalt auf der Konsole ausgegeben:
let ai = require('/agorum/roi/customers/agorum.ai/js/lib/ai'); // Beispiel ID eines Prompt-Datei let promptId = 'prompt-file-id'; // Laden des Prompt-Inhalts let promptContent = ai.loadPrompt(promptId); // Protokolliere den Inhalt des Prompts zur Konsole console.log('Prompt content:', promptContent);
Rückgabewert
Die Funktion loadPrompt gibt einen String zurück, der den Inhalt der angegebenen Prompt-Datei darstellt.