Felder und Regeln

Diese Seite erklärt jede Einstellung im Modus Formular. Dieselben Einstellungen stehen im Modus JSON als Text, in dem du ein ganzes Szenario kopieren oder einfügen kannst.

Verbindungen und API-Zugänge

Einstellung	Bedeutung
Technischer Name	Kennung, mit der Tools auf die Verbindung verweisen. Kleinbuchstaben, Ziffern, Unterstrich.
Basis-URL	Adresse deiner API, nur `https://`, ohne Pfad, Query oder Zugangsdaten.
API-Zugang	Referenz auf einen gespeicherten Zugang oder Ohne Authentifizierung.

Gespeicherte API-Zugänge gelten für die ganze Organisation: eine Referenz als Name, ein Header-Name, Voreinstellung Authorization, und der Wert. Der Wert wird nie an die KI übergeben und erscheint nicht in Vorschau oder Protokoll.

Gesprächsdaten

Jedes Feld hat einen technischen Namen, einen Typ, eine Quelle und eine Sichtbarkeit.

Typ	Beispiele
Text, Ganzzahl, Zahl, Ja/Nein	Name, Menge, Preis, Zustimmung
Datum, Uhrzeit, Datum und Uhrzeit	Liefertermin, Terminbeginn. Zeiten gelten in der Zeitzone deiner Organisation.
Liste	Warenkorb, Speisekarte. Eine Liste hat Max. Einträge und eigene Felder pro Eintrag, etwa `product_id`, `quantity`, `extras`.

Quelle	Wer das Feld füllt
Anrufer (setzt die KI)	Der Agent speichert, was der Anrufer sagt. Dafür bekommt er pro Feld eine Funktion, die nur echte Angaben speichert, nie Vermutungen.
API (nur Backend)	Nur die Antwort eines Tools füllt das Feld. Die KI kann es nicht setzen.
Berechnet (aus Regeln)	Der Wert ergibt sich aus Fällen, siehe unten.

Sichtbarkeit: Für KI sichtbar bedeutet, der Agent kennt den Wert und kann ihn nennen. Intern bedeutet, nur das Backend kennt ihn und setzt ihn in Aufrufe ein. Kunden-IDs, Buchungsnummern und ähnliche Kennungen gehören auf Intern.

Für Felder eines Listeneintrags kannst du Werte nur aus einem anderen Listenfeld erlauben, etwa Produkt-IDs nur aus der zuvor geladenen Speisekarte. Für Zahlen gibt es Min und Max.

Berechnete Felder

Ein berechnetes Feld hat Fälle: je eine Bedingung und einen Wert, dazu optional Sonst (Standardwert). Es gilt der erste zutreffende Fall. Der Wert wird bei jedem Lesen neu berechnet, also immer zur aktuellen Uhrzeit, und nie gespeichert. Berechnete Felder sind Text oder Ja/Nein.

Beispiel aus der Terminabsage, Feld cancellation_window:

Ist appointment_start leer, dann unknown.
Ist jetzt kleiner oder gleich appointment_start mit Versatz minus 24 Stunden, dann open.
Ist jetzt kleiner als appointment_start, dann too_late.
Sonst past.

Ein Tool “Termin absagen” verlangt dann als Voraussetzung Feld hat erlaubten Wert open, und Absagen sind nur bis 24 Stunden vorher möglich, ohne dass der Agent selbst rechnen muss.

Tools

Allgemein

Einstellung	Bedeutung
Anzeigename	Name in der Oberfläche und im Ablauf.
Beschreibung für die KI	Wofür das Tool da ist und was der Agent beachten soll. Der wichtigste Text des Tools: Der Agent entscheidet danach, wann er es aufruft.
Operation	Lesen oder Schreiben (mit Bestätigung).
Tool aktiv	Inaktive Tools bleiben gespeichert, der Agent kennt sie nicht.
Max. Fehlversuche pro Anruf	Optional, 1 bis 10. Abgelehnte Antworten zählen, also Erfolgsprüfung nicht erfüllt oder HTTP 4xx. Danach ist das Tool bis zum Ende des Anrufs gesperrt.

Eingaben

Parameter, die der Agent beim Aufruf liefern muss, zum Beispiel ein Suchbegriff. Jede Eingabe hat Name, Typ, Pflicht und eine Beschreibung, aus der der Agent erkennt, was er einsetzen soll. Werte aus Gesprächsdaten brauchst du hier nicht, sie kommen direkt aus den Feldern.

Voraussetzungen

Alle Voraussetzungen eines Tools müssen erfüllt sein, sonst wird der Aufruf blockiert und der Agent erhält die Meldung an die KI bei Blockierung. Schreibe die Meldung als Anweisung: “Zuerst die Postleitzahl erfragen.”

Bedingung	Erfüllt, wenn
Feld ist bekannt	Das Feld hat einen Wert.
Feld ist nicht leer	Das Feld hat einen Wert, bei Listen mindestens einen Eintrag.
Feld hat erlaubten Wert	Der Wert steht in den Erlaubten Werten, kommagetrennt.
Systemwert verfügbar	Die Rufnummer des Anrufers wurde übertragen.
Tool zuvor erfolgreich	Das genannte Tool war in diesem Gespräch erfolgreich, und die Felder unter Seitdem unverändert haben sich seither nicht geändert. Ändert sich eines, muss das Tool erneut laufen.
Bedingung (Regel)	Eine frei zusammengesetzte Prüfung, siehe Bedingungen. Hier ist die Meldung Pflicht.

Anfrage

Einstellung	Bedeutung
Verbindung und Methode	GET, POST, PUT, PATCH oder DELETE. GET hat keinen Body.
Pfad	Relativ zur Basis-URL, mit Platzhaltern wie `{customer_id}`.
Pfad-Platzhalter	Für jeden Platzhalter die Quelle des Werts.
Query-Parameter	Name und Quelle des Werts.
JSON-Body	Je ein Body-Pointer wie `/customer/name` und die Quelle des Werts. Verschachtelte Pointer ergeben verschachtelte Objekte.

Als Quelle eines Werts stehen zur Wahl: ein konstanter Wert, ein Gesprächsdatenfeld, eine Eingabe des Tools oder ein Systemwert. Systemwerte sind die Rufnummer des Anrufers, die Gesprächs-ID, das heutige Datum und der aktuelle Zeitpunkt.

Antwort

Einstellung	Bedeutung
Erfolgs-Statuscodes	HTTP-Codes im Bereich 200 bis 299, die als Erfolg zählen.
Erfolgsprüfung	Nur HTTP-Status: der Code genügt. Genau ein Treffer: Der Antwort-Pointer zeigt auf eine Liste, die genau einen Eintrag haben muss. Feld hat Wert: Ein Feld der Antwort muss einen bestimmten Wert haben, etwa `/status` gleich `accepted`.
Bei Mehrdeutigkeit nachfragen	Nur bei Lesen mit Genau ein Treffer: Findet die API mehrere Einträge, fragt der Agent den Anrufer nach einer Angabe, etwa dem Namen, und das Backend wählt anhand der Vergleichsfelder den passenden Eintrag. Die Trefferliste sieht die KI nie.
In Gesprächsdaten übernehmen	Je ein Antwort-Pointer, das Zielfeld, ob der Wert Pflicht ist, und der Modus: Ersetzen oder Eindeutig anhängen für Listen mit einem Schlüsselfeld gegen Dubletten. Fehlt ein Pflichtwert, gilt der Aufruf als fehlgeschlagen.
Hinweis bei Fehlschlag	Text für den Agenten, wenn der Aufruf scheitert. Er soll sagen, was der Agent dem Anrufer anbietet.
Fehler-Pointer	Optional: Pointer auf die Fehlermeldung in der Antwort, etwa `/error`. Der Agent bekommt sie zum Erklären, ohne technische Details vorzulesen.

Zielfelder müssen die Quelle API haben. Ein Feld, auf das eine Voraussetzung zeigt, muss von irgendeinem Tool befüllt werden, sonst meldet die Validierung einen Fehler.

Bestätigung

Nur bei Schreiben. Vorzulesende Werte sind die Felder, die der Agent vor der Aktion nennt. Die Bestätigungsfrage stellt er danach wörtlich. Erst das Ja des Anrufers löst den Aufruf aus. Verändert sich eines der Felder zwischen Vorlesen und Ja, gilt die Bestätigung nicht mehr.

System-Tools

Über System-Tool hinzufügen nutzt du fertige Prüfungen von novofon innerhalb des Szenarios:

Adressprüfung: prüft Straße, Hausnummer, PLZ und Ort. Erfolgreich, wenn: Adresse gültig und im Servicegebiet, oder nur PLZ im Servicegebiet, auch wenn Google nicht erreichbar ist. Mit Adresse durch die von Google korrigierte ersetzen übernimmt das Tool die korrigierte Schreibweise in die Gesprächsdaten.
Telefonnummer per SMS-Code bestätigen: schickt einen Code an eine Mobilnummer aus deinem Kundensystem und ist erfolgreich, wenn der Anrufer ihn richtig nennt. Die Nummer muss aus API-Daten kommen, nicht vom Anrufer.

Unter Eingaben aus Gesprächsdaten verknüpfst du die Parameter mit deinen Feldern. System-Tools laufen automatisch erneut, wenn sich eines der verknüpften Felder ändert. Ist ein System-Tool in den Agenteneinstellungen deaktiviert, ist es auch im Szenario nicht verfügbar, und Voraussetzungen darauf blockieren.

Bedingungen

Bedingungen stehen in Voraussetzungen vom Typ Bedingung (Regel) und in berechneten Feldern. Jede Prüfung hat eine Art:

Prüfung	Bedeutung
Vergleich	Zwei Werte mit Operator: gleich, ungleich, kleiner, kleiner gleich, größer, größer gleich. Optional ein Versatz nach ISO 8601, etwa `PT60M` für 60 Minuten, `P1D` für einen Tag, `-PT30M` für 30 Minuten früher.
Wert in Liste	Der Wert ist einer der genannten.
Wert ist bekannt, Wert ist leer	Ob ein Feld gefüllt ist.
Tool erfolgreich	Wie die gleichnamige Voraussetzung.
Alle (UND), Eine davon (ODER), Nicht	Verknüpfen andere Prüfungen.

Als Werte dienen Gesprächsdaten, Systemwerte, Konstanten oder ein Zeitpunkt aus Datum und Uhrzeit in der Zeitzone der Organisation. Ein Vergleich mit einem leeren Wert gilt als nicht erfüllt, auch unter Nicht.