.MSG

Steuert den Nachrichtenaustausch zwischen Nutzer und Bot (RAGAI.MSG).

Hintergrund

Zwei Achsen bestimmen das Verhalten jeder Methode:

• Sichtbarkeit: prompt()/userMessage()/botMessage() erscheinen im Chatverlauf; userBypass()/botBypass() landen unsichtbar im Thread-Kontext (die KI "sieht" sie, der Nutzer nicht) - nützlich, um der KI zusätzlichen Kontext mitzugeben, ohne den sichtbaren Chat zu verändern.
• Run-Auslösung: Nur prompt() löst einen vollständigen KI-Antwort-Run aus. Alle anderen Methoden fügen Nachrichten nur zum Verlauf hinzu, ohne dass der Bot antwortet.

prompt() und userMessage() laufen durch alle registrierten RAGAI.BEFORE_SEND-Hooks (siehe MsgProcessingService), bevor die Nachricht tatsächlich verarbeitet wird - ein Hook kann den Text ändern oder das Senden per null-Rückgabe komplett unterdrücken.

Events

onBotToUser

Feuert mit dem Bot-Text, sobald eine Bot-Nachricht in den Chatverlauf eingefügt wird.

RAGAI.MSG.onBotToUser.subscribe((value) => {
  console.log(value);
});

onUserToBot

Feuert mit dem Nutzer-Text, sobald eine Nutzer-Nachricht in den Chatverlauf eingefügt wird.

RAGAI.MSG.onUserToBot.subscribe((value) => {
  console.log(value);
});

userMessageEmitter

Feuert mit dem Nutzer-Text, sobald userMessage() aufgerufen wird.

RAGAI.MSG.userMessageEmitter.subscribe((value) => {
  console.log(value);
});

runCompleteEmitter

Feuert, sobald ein durch prompt() ausgelöster KI-Antwort-Run abgeschlossen ist.

RAGAI.MSG.runCompleteEmitter.subscribe((value) => {
  console.log(value);
});

runRequestEmitter

Feuert mit dem Prompt-Text, sobald prompt() einen KI-Antwort-Run auslöst.

RAGAI.MSG.runRequestEmitter.subscribe((value) => {
  console.log(value);
});

Methoden

.prompt(text)

Sendet einen Text als Nutzereingabe an den Bot und löst einen vollständigen Antwort-Run aus.

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der zu sendende Text, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: void

.userMessage(text)

Fügt eine sichtbare Nutzer-Nachricht zum Chatverlauf hinzu, ohne eine Bot-Antwort auszulösen.

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der anzuzeigende Text, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: void

.botBypass(text)

Sendet eine Nachricht direkt als Bot in den Thread, ohne einen KI-Antwort-Run auszulösen (Bypass-Modus).

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der Nachrichtentext, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: Promise<HistoryItemResponse[]>

Die gespeicherten Verlaufsnachrichten.

.userBypass(text)

Sendet eine Nachricht direkt als Nutzer in den Thread, ohne einen KI-Antwort-Run auszulösen (Bypass-Modus).

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der Nachrichtentext, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: Promise<HistoryItemResponse>

Die gespeicherte Verlaufsnachricht.

.overwriteSystemPrompt(prompt)

Überschreibt den Systemprompt des Bots für die aktuelle Sitzung.

Parameter	Typ	Beschreibung
prompt	string | z.input<typeof msgPromptSchema>	Der neue Systemprompt, oder ein Objekt gemäß msgPromptSchema.

Objekt-Form (validiert über msgPromptSchema):

Feld	Typ	Pflicht	Beschreibung
prompt	string	✔	Der neue Systemprompt für die aktuelle Sitzung.

Rückgabewert: Promise<void>

Nichts.

.overwriteWebsearchEnabled(enabled)

Aktiviert oder deaktiviert die Websuche des Bots für die aktuelle Sitzung.

Parameter	Typ	Beschreibung
enabled	boolean | z.input<typeof msgWebsearchSchema>	true aktiviert die Websuche, oder ein Objekt gemäß msgWebsearchSchema.

Objekt-Form (validiert über msgWebsearchSchema):

Feld	Typ	Pflicht	Beschreibung
enabled	boolean	✔	true aktiviert die Websuche, false deaktiviert sie.

Rückgabewert: Promise<void>

Nichts.

.botMessage(text)

Sendet eine Bot-Nachricht inklusive Sprachausgabe (bei Audio-/Avatar-Modus).

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der Nachrichtentext, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: Promise<HistoryItemResponse | undefined>

Die gespeicherte Verlaufsnachricht.

.userMessageDirect(text)

Fügt eine normale (nicht-bypass) Nutzer-Nachricht direkt in den Thread ein, ohne dafür eine reguläre KI-Chat-Anfrage auszulösen (kein Aufruf von prompt() oder userMessage(), welche den normalen Sende-Flow erneut anstoßen würden). Wird z.B. vom Freitext-Quiz genutzt, um die vom Nutzer eingegebene Antwort sichtbar im Verlauf zu protokollieren.

Parameter	Typ	Beschreibung
text	string | z.input<typeof msgTextSchema>	Der zu protokollierende Nutzertext, oder ein Objekt gemäß msgTextSchema.

Objekt-Form (validiert über msgTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der Text, der an den Bot gesendet bzw. angezeigt wird.

Rückgabewert: Promise<HistoryItemResponse | undefined>

Die gespeicherte Verlaufsnachricht.