Breadcrumbs

executePrompt

Die AIUtils stehen nur zur Verfügung, wenn man das Modul "KI-Assistent" lizenziert hat.

Version 2026.6

Code

Groovy
IAIResult executePrompt(String promptDefinitionPlainKey, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars);
IAIResult executePrompt(String promptDefinitionPlainKey, AIStructuredOutputConfig structuredOutput, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars);
IAIResult executePrompt(String promptDefinitionPlainKey, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars, String entryPk);
IAIResult executePrompt(String promptDefinitionPlainKey, AIStructuredOutputConfig structuredOutput, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars, String entryPk);

Beschreibung

Führt eine in der Eingabe-Verwaltung definierte Prompt-Vorlage mit einem KI-Modell aus. Die Platzhalter im System-Prompt und User-Prompt der Vorlage werden dabei mit den übergebenen Werten aus den Maps gefüllt.

Optional kann zusätzlich ein Datensatzkontext über entryPk übergeben werden, damit die Prompt-Vorlage auf einen konkreten Datensatz zugreifen kann.

Optional kann außerdem eine AIStructuredOutputConfig übergeben werden. Damit wird die KI-Antwort in ein strukturiertes JSON-Format geführt, das anschließend programmatisch weiterverarbeitet werden kann.

Die Methode liefert immer ein IAIResult zurück. Im Erfolgsfall enthält es die Antwort der KI. Im Fehlerfall enthält es einen Fehlerstatus und eine auswertbare Fehlermeldung.

Parameter

  • promptDefinitionPlainKey: Der Plain Key der Prompt-Vorlage aus der Eingabe-Verwaltung, die für den KI-Aufruf verwendet werden soll.

  • systemPromptVars: Map mit den Werten für die Platzhalter im System-Prompt der Vorlage.

  • userPromptVars: Map mit den Werten für die Platzhalter im User-Prompt der Vorlage.

  • structuredOutput: Optionale AIStructuredOutputConfig, die das erwartete strukturierte Antwortformat vorgibt. Erzeugbar z. B. über AIUtils.createStructuredConfig.

  • entryPk: Optionaler Primärschlüssel eines Datensatzes, auf den innerhalb der Prompt-Vorlage zugegriffen werden soll.

Rückgabe

Die Methode gibt immer ein IAIResult zurück.

  • Im Erfolgsfall enthält das Ergebnis die Antwort der KI.

  • Im Fehlerfall enthält das Ergebnis keinen verwertbaren KI-Inhalt, sondern einen Fehlerstatus sowie eine Fehlermeldung, die standardisiert ausgewertet werden kann.

Prüfen Sie das Ergebnis deshalb immer mit AIUtils.isAIResponseSuccessful(result).

Typischer Ablauf:

  1. IAIResult entgegennehmen

  2. Erfolg prüfen

  3. bei Erfolg Antwort auslesen

  4. bei Fehler Fehlermeldung auslesen und geeignet anzeigen oder weiterverarbeiten

Beispiele

1. Einfacher Aufruf mit Prompt-Vorlage
Groovy
Map<String, Object> systemVars = [:]
Map<String, Object> userVars = ["Thema": "Projekt-Update"]

IAIResult result = AIUtils.executePrompt("MailVorlage", systemVars, userVars)

if (AIUtils.isAIResponseSuccessful(result)) {
    String message = AIUtils.getAIResponseMessage(result)
} else {
    String errorMessage = AIUtils.getAIResponseError(result)
}
2. Aufruf mit Datensatzbezug über entryPk
Groovy
Map<String, Object> systemVars = [:]
Map<String, Object> userVars = ["Anrede": "Herr"]
String kundenPk = "fvvvvvvkarpvi1ium3j2qcAc"

IAIResult result = AIUtils.executePrompt("IndividuellesAngebot", systemVars, userVars, kundenPk)

if (AIUtils.isAIResponseSuccessful(result)) {
    String message = AIUtils.getAIResponseMessage(result)
} else {
    String errorMessage = AIUtils.getAIResponseError(result)
}
3. Aufruf mit strukturierter Antwort
Groovy
AIStructuredOutputConfig config = AIUtils.createStructuredConfig()
AIUtils.addString(
    config,
    "status",
    false,
    "Klassifizierung der Anfrage"
)

Map<String, Object> systemVars = [:]
Map<String, Object> userVars = ["text": "Ich habe mein Passwort vergessen."]

IAIResult result = AIUtils.executePrompt("AnalyseCheck", config, systemVars, userVars)

if (AIUtils.isAIResponseSuccessful(result)) {
    Map<String, Object> data = AIUtils.getAIStructuredResponse(result)
    String status = data.get("status")
} else {
    String errorMessage = AIUtils.getAIResponseError(result)
}
4. Ergebnis als ScriptReturn weitergeben

Falls ein KI-Ergebnis in einem Skript standardisiert zurückgegeben werden soll, kann das IAIResult in ein ScriptReturn überführt werden:

Groovy
Map<String, Object> systemVars = [:]
Map<String, Object> userVars = ["Thema": "Projekt-Update"]

IAIResult result = AIUtils.executePrompt("MailVorlage", systemVars, userVars)

return AIUtils.toScriptReturn(result)

Version 2026.5

Code

Groovy
IAIResult executePrompt(String promptDefinitionPlainKey, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars);
IAIResult executePrompt(String promptDefinitionPlainKey, StructuredOutputConfig structuredOutput, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars);
IAIResult executePrompt(String promptDefinitionPlainKey, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars, String entryPk);
IAIResult executePrompt(String promptDefinitionPlainKey, StructuredOutputConfig structuredOutput, Map<String, Object> systemPromptVars, Map<String, Object> userPromptVars, String entryPk);

Beschreibung

Führt eine in der Eingabe-Verwaltung definierte Prompt-Vorlage aus. Die Methode füllt die Platzhalter der User- und System-Prompts mit den übergebenen Werten aus den entsprechenden Maps. Je nach Überladung kann ein Datensatz-Kontext (entryPk) für die Vorlage mitgegeben oder ein festes Antwortschema (StructuredOutputConfig) definiert werden.

Parameter

  • promptDefinitionPlainKey: Der PlainKey einer Eingabe-Verwaltung, welche für den Aufruf der KI verwendet werden soll.

  • systemPromptVars: Die Map mit Werten für die Platzhalter im System-Prompt der Vorlage.

  • userPromptVars: Die Map mit Werten für die Platzhalter im User-Prompt der Vorlage.

  • structuredOutput: [optional] Ein StructuredOutputConfig Objekt, welches die gewünschte JSON-Struktur der Antwort definiert.

  • entryPk: [optional] Der Primärschlüssel eines Datensatzes, auf den innerhalb der Prompt-Vorlage zugegriffen werden soll.

Rückgabe

Das IAIResult, welches die Antwort der KI enthält. Nutzen Sie AIUtils.isAIResponseSuccessful(result), um den Erfolg zu prüfen.

Beispiele

  1. Einfacher Aufruf (Freitext)

Groovy
// 1. Variablen vorbereiten
Map userVars = ["Thema": "Projekt-Update"]
Map systemVars = [:]

// 2. Prompt ausführen
IAIResult result = AIUtils.executePrompt("MailVorlage", systemVars, userVars)

// 3. Ergebnis prüfen
if (AIUtils.isAIResponseSuccessful(result)) {
    String message = AIUtils.getAIResponseMessage(result)
}

  1. Aufruf mit Datensatz-Bezug (entryPk)

Groovy
// 1. Variablen und PK definieren
Map userVars = ["Anrede": "Herr"]
String kundenPk = "fvvvvvvkarpvi1ium3j2qcAc"

// 2. Prompt ausführen (Vorlage greift auf Daten des Kunden-PKs zu)
IAIResult result = AIUtils.executePrompt("IndividuellesAngebot", [:], userVars, kundenPk)

  1. Aufruf mit strukturiertem Output

Groovy
// 1. Schema definieren
def config = AIUtils.createStructuredConfig()
AIUtils.addExpectedReturn(config, "status", String.class, false, "Klassifizierung der Anfrage")

// 2. Variablen vorbereiten
Map userVars = ["text": "Ich habe mein Passwort vergessen."]

// 3. Prompt ausführen (mit Schema und ohne PK)
IAIResult result = AIUtils.executePrompt("AnalyseCheck", config, [:],userVars)

// 4. Strukturierte Daten auslesen
if (AIUtils.isAIResponseSuccessful(result)) {
    Map data = AIUtils.getAIStructuredResponse(result)
    String status = data.get("status")
}

Version 2025.5

Code

Groovy
IAIResult executePrompt(String promptDefinitionPlainKey, Map<String, Object> userPromptVars, String systemPromptVars, String entryPk)

Beschreibung

Führt die Eingabe-Verwaltung mit dem angegebenen Namen aus und füllt die System- bzw. User-Prompt-Vorlage mit den übergebenen Werten. Die userPromptVars und systemPromptVars sollten für jeden in der Prompt angegebenen Platzhalter Werte enthalten. Die Prompt-Vorlage erfordert möglicherweise einen Datensatz, für den der PK angegeben werden muss.

Parameter

  • promptDefinitionPlainKey - Der PlainKey einer Eingabe-Verwaltung, welche für den Aufruf der KI verwendet werden soll..

  • userPromptVars - Die Map welche die Werte für die Platzhalter in der User-Prompt enthält.

  • systemPromptVars - Die Map welche die Werte für die Platzhalter in der System-Prompt enthält.

  • entryPk - [optional] Der PK eines Datensatzes, welcher in die Prompt übergeben wird.

Returns

Das IAIResult, welches die Antwort der KI enthält.

Beispiele

Groovy
Map userPromptVars = new HashMap();
userPromptVars.put("Ansprechform", "Siezen");
userPromptVars.put("ThemaDesTermins", "Brandneues Produkt");
userPromptVars.put("AgendaDesTermins", "Funktionen, KI, Günstiger Preis");

List<String> dates = new ArrayList<String>();
Date date = DateUtils.parseDate("01.04.1987 10:00", "dd.MM.yyyy HH:mm");
dates.add(DateUtils.convertDateTimePattern(date, "yyyy-MM-dd'T'HH:mm:ssX"));
date = DateUtils.setDateField(date, DateUtils.HOUR, 12);
dates.add(DateUtils.convertDateTimePattern(date, "yyyy-MM-dd'T'HH:mm:ssX"));
userPromptVars.put("Datum", dates);

userPromptVars.put("Dauer", "1 Stunde");
userPromptVars.put("Ort", "vor Ort");

Map systemPromptVars = new HashMap();

IAIResult result = AIUtils.executePrompt("Terminvereinbarung", userPromptVars, systemPromptVars, "fvvvvvvkarpvi1ium3j2qcAc");

if (AIUtils.isAIResponseSuccessful(result)) {
    String aiResponse = AIUtils.getAIResponseMessage(result);
} else {
    String errorMessage = AIUtils.getAIResponseError(result);
}