Extraktionsfelder

Kurz gesagt: Extraktionsfelder (auch "Slots" genannt) sind strukturierte Datencontainer, die Informationen speichern, die vom LLM während Gesprächen extrahiert werden. Sie ermöglichen es Ihrem Bot, Benutzereingaben (Namen, Daten, Präferenzen) zu merken und in Skripten, Entscheidungszweigen und Ausgaben zu verwenden. Jedes Feld hat einen Datentyp, eine Beschreibung und eine optionale Validierung. Sie sind das Rückgrat dynamischer, kontextbewusster Gespräche.

Extraktionsfelder sind wiederverwendbare Datencontainer, die es Ihrem Bot ermöglichen, strukturierte Informationen aus Benutzernachrichten zu erfassen, zu speichern und zu nutzen. Stellen Sie sich diese als Variablen vor, die das LLM während Gesprächen automatisch ausfüllen kann – wie das Extrahieren der E-Mail-Adresse, des Geburtsdatums oder der Produktpräferenz eines Benutzers.

Sobald extrahiert, können diese Werte:

In Bot-Antworten mit Templating referenziert werden ({{field_name}})
In benutzerdefinierten Skripten für Geschäftslogik verwendet werden
In Verzweigungsknoten für bedingte Flusskontrolle ausgewertet werden
Zwischen Flows und Knoten übergeben werden
Von externen Systemen über die API abgerufen werden

Warum Extraktionsfelder verwenden?

Extraktionsfelder ermöglichen es Ihrem Bot, Kontext und Gedächtnis während eines Gesprächs aufzubauen. Ohne sie hätte Ihr Bot keine Möglichkeit, sich an Informationen zu erinnern oder auf Informationen zu reagieren, die Benutzer bereitstellen.

Anwendungsfälle umfassen:

Formularausfüllung - Sammeln strukturierter Daten wie Name, E-Mail, Telefonnummer
Personalisierung - Merken von Benutzerpräferenzen oder vorherigen Entscheidungen
Geschäftslogik - Verwenden extrahierter Werte, um Entscheidungen zu treffen (z.B. Alter überprüfen, bevor fortgefahren wird)
Datenpersistenz - Speichern von Gesprächsdaten für spätere Verwendung oder Analysen
Dynamische Antworten - Anpassen von Nachrichten basierend auf extrahierten Informationen

Verwaltung von Extraktionsfeldern

Alle Extraktionsfelder anzeigen

Um alle Extraktionsfelder für Ihren Bot anzuzeigen:

Navigieren Sie zu Inhalt → Extraktionsfelder in der Seitenleiste
Sie sehen eine Liste aller Extraktionsfelder mit ihren:
- Name - Der eindeutige Bezeichner für das Feld
- Beschreibung - Was das Feld darstellt
- Datentyp - Der Typ der Daten, die es speichert (String, Integer, etc.)
- Erstellungsdatum - Wann das Feld erstellt wurde

Sie können auf jedes Feld klicken, um es zu bearbeiten.

Ein Extraktionsfeld erstellen

Es gibt zwei Möglichkeiten, Extraktionsfelder zu erstellen:

Methode 1: Aus der Liste der Extraktionsfelder

Navigieren Sie zu Inhalt → Extraktionsfelder
Klicken Sie auf die Schaltfläche Erstellen
Füllen Sie die Felddetails aus (siehe Feldeigenschaften unten)
Klicken Sie auf Speichern

Methode 2: Inline in einem Formularknoten

Beim Erstellen eines Formularknotens können Sie Extraktionsfelder im Handumdrehen erstellen:

Erstellen oder bearbeiten Sie einen Formularknoten
Klicken Sie auf Extraktionsfeld hinzufügen
Definieren Sie die Feldeigenschaften inline
Das Feld wird global zur Wiederverwendung in anderen Knoten verfügbar

Feldeigenschaften

Jedes Extraktionsfeld hat die folgenden Eigenschaften:

Name (Erforderlich)

Der eindeutige Bezeichner für das Feld. So werden Sie es in Vorlagen, Skripten und Bedingungen referenzieren.

Anforderungen:

Mindestens 3 Zeichen
Nur alphanumerische Zeichen und Unterstriche (keine Leerzeichen oder Sonderzeichen)
Muss innerhalb des Bots eindeutig sein

Beispiel: user_email, birth_date, product_choice

Beschreibung (Erforderlich)

Eine klare, detaillierte Beschreibung, welche Informationen dieses Feld enthalten soll. Diese Beschreibung ist entscheidend – sie ist das, was das LLM verwendet, um zu verstehen, was extrahiert werden soll.

Best Practices:

Seien Sie spezifisch und detailliert
Geben Sie Formatierungsanforderungen an (z.B. "Muss im Format TT.MM.JJJJ sein")
Erwähnen Sie alle Einschränkungen (z.B. "Muss eine positive Zahl sein")
Verwenden Sie natürliche Sprache, die das LLM verstehen kann

Beispiel:

Das Geburtsdatum des Benutzers. Muss aus Tag, Monat und Jahr bestehen und im Format TT.MM.JJJJ geliefert werden.

Datentyp (Erforderlich)

Der Typ der Daten, die dieses Feld speichern wird. Verfügbare Typen:

Typ	Beschreibung	Beispiel
`str`	Zeichenkette (Text)	"John Doe", "hello@example.com"
`int`	Ganzzahl (ganze Zahlen)	1, 2, 3, 42
`float`	Gleitkommazahl	1.5, 3.14, 99.99
`bool`	Boolean (wahr/falsch)	true, false
`date`	Datum (JJJJ-MM-TT)	2024-01-15
`datetime`	Datum und Uhrzeit (ISO 8601)	2024-01-15T14:30:00

Das LLM wird automatisch extrahierte Werte auf den angegebenen Typ validieren und konvertieren.

Beispiele / Enums

Geben Sie Beispielwerte an, um dem LLM zu helfen, welche Art von Daten extrahiert werden sollen. Dieses Feld kann in zwei Modi funktionieren:

Beispielmodus (Standard): Fügen Sie Beispielwerte hinzu, die das erwartete Format demonstrieren. Diese sind Hinweise für das LLM – keine strengen Einschränkungen.

Beispiel:

john.doe@example.com
jane.smith@company.org
support@website.com

Enum-Modus: Aktivieren Sie "Als Enum interpretieren", um das Feld darauf zu beschränken, nur bestimmte vordefinierte Werte zu akzeptieren. Das LLM wird nur Werte extrahieren, die genau mit einer Ihrer Enum-Optionen übereinstimmen.

Beispiel (Produktkategorien):

Elektronik
Kleidung
Bücher
Haus & Garten

Hinweis: Für boolesche Felder, die als Enums verwendet werden, verwenden Sie nur true und false als Ihre Enum-Werte.

Validierungsskript (Optional)

Schreiben Sie benutzerdefinierten Python-Code, um extrahierte Werte zu validieren. Wenn aktiviert und der default-form-agent verwendet wird, wird dieses Skript ausgeführt, nachdem das LLM einen Wert extrahiert hat und bevor er im Slot gespeichert wird. Bei Verwendung eines custom-form-agent wird das Skript ausgeführt, wenn validate_slots aufgerufen wird.

Anwendungsfälle:

Überprüfen, ob eine E-Mail von einer erlaubten Domain stammt
Überprüfen, ob eine Zahl innerhalb eines akzeptablen Bereichs liegt
Validierung gegen externe Datenquellen
Anwenden komplexer Geschäftsregeln

Struktur des Validierungsskripts:

# Der extrahierte Wert ist als 'value' verfügbar
# Geben Sie True zurück, wenn gültig, False, wenn ungültig
# Optional eine Ausnahme mit einer Fehlermeldung auslösen

if "@example.com" not in value:
    raise ValueError("E-Mail muss von der Domain example.com stammen")

return True

Wichtig: Aktivieren Sie den Schalter "Validierungsskript aktiv", um die Validierung zu aktivieren.

Hinweis: Validierungsskripte auf Feldebene validieren einzelne Felder isoliert. Für Validierungslogik, die mehrere Feldwerte erfordert (z.B. Überprüfung, ob das Enddatum nach dem Startdatum liegt), verwenden Sie Formularvalidierungsskripte stattdessen.

Livechat Whitelisted

Wenn aktiviert, kann dieses Extraktionsfeld von Live-Chat-Operatoren während eines Gesprächs gelesen werden. Dies ermöglicht es menschlichen Agenten, Werte während einer Übergabe anzuzeigen und zu aktualisieren.

Anwendungsfälle:

Felder, die Agenten überprüfen müssen
Informationen, die Agenten möglicherweise referenzieren müssen
Daten, die in der Live-Chat-Oberfläche sichtbar sein sollten

Extern beschreibbar

Wenn aktiviert, können externe Systeme über die API in dieses Feld schreiben.

Anwendungsfälle:

Vor dem Start eines Gesprächs Felder über die API ausfüllen

Vertraulich (nur API)

Verwenden Sie diese Kennzeichnung für kurzlebige Geheimnisse, die eine benutzerdefinierte Aktion für eine Anfrage benötigt, z.B. Sitzungstoken, einmalige Zugriffstoken oder OTPs.

Wenn der Wert über die REST-API geliefert wird, wird der Klartext nur im Speicher für die aktuelle Runde gehalten. Er wird nicht in die Datenbank, den Tracker-Status, das Ereignisprotokoll oder die Servicelogs geschrieben.

Wichtig: Vertraulicher Schutz ist nur API-basiert. Formknoten, tracker_api.set_slot(), apply_slots() und payload.slots werden durch diese Kennzeichnung nicht blockiert. Wenn einer dieser Pfade in dasselbe Feld schreibt, wird der Wert wie ein regulärer Slot behandelt und im Klartext gespeichert.

Anforderungen:

Vertrauliche Werte nur über die REST-API liefern.
Extern beschreibbar auf dem Extraktionsfeld aktivieren.
Den Wert als einfachen String senden.
Vertrauliche Felder nicht an Formknoten anhängen oder von benutzerdefinierten Aktionen schreiben, wenn der Wert nicht gespeichert werden soll.

Persistenz und Verfügbarkeit:

Element	Verhalten
Klartextwert	Nur für benutzerdefinierte Aktionen während der ursprünglichen Runde verfügbar
Spätere Runden	Klartext ist verschwunden
Datenbank / Ereignisprotokoll	Klartext wird nie gespeichert
Tracker-Status (`state.slots`)	Klartext wird nie gespeichert
Servicelogs	Klartext wird vor der Validierung und Protokollierung entfernt
`SlotSetEvent`	Nur als maskierter "*****"-Marker gespeichert

Das maskierte SlotSetEvent zeichnet nur auf, dass der Slot bereitgestellt wurde. Es wird nicht in state.slots geschrieben, sodass Flussbedingungen, LLM-Eingabeaufforderungen und Formknoten keinen Platzhalterwert sehen.

Den Wert aus einer benutzerdefinierten Aktion lesen:

Aufruf	Vertraulicher Slot, Runde 1	Vertraulicher Slot, Runde 2+	Regulärer Slot
`a_get_slot_value(name)`	`default`	`default`	echter Wert
`get_slot_value(name)`	`default`	`default`	echter Wert
`a_get_slot_value(name, include_confidential=True)`	Klartext	`default`	echter Wert
`get_slot_value(name, include_confidential=True)`	Klartext	`default`	echter Wert

Verwenden Sie include_confidential=True nur in der Aktion, die das Geheimnis benötigt. Ohne diese Option geben vertrauliche Slots den konfigurierten Standardwert zurück (typischerweise None); die Kennzeichnung hat keine Auswirkungen auf reguläre Slots. Für Methodensignaturen und Anwendungsdetails siehe die SDK-Dokumentation.

Sicherheitshinweis: Sobald eine benutzerdefinierte Aktion den Klartext liest, ist der Aktionscode dafür verantwortlich. Nicht protokollieren, nicht in einem regulären Slot speichern, nicht in Bot-Antworten einfügen oder in LLM-Eingabeaufforderungen übergeben.

Verwendung von Extraktionsfeldern in Knoten

Formularknoten

Formularknoten sind speziell dafür ausgelegt, mehrere Felder mithilfe von LLM-gesteuerten Gesprächen zu extrahieren. Um Extraktionsfelder in einem Formularknoten zu verwenden:

Erstellen oder bearbeiten Sie einen Formularknoten
Fügen Sie dem Knoten Extraktionsfelder hinzu
Konfigurieren Sie den Prozessnamen und die Prozessbeschreibung
Das LLM wird Benutzer konversationell nach fehlenden Informationen fragen

Prozessname

Der Prozessname ist ein kurzer, beschreibender Bezeichner für das, was das Formular sammelt. Er wird intern als Funktionsname für den LLM-Toolaufruf verwendet.

Anforderungen:

Sollte prägnant sein (1-4 Wörter)
Verwenden Sie Unterstriche anstelle von Leerzeichen
Beschreibt die Aktion oder das Ziel

Beispiele:

Gute Prozessnamen	Anwendungsfall
`termin_buchen`	Sammeln von Termindetails
`kontaktinformationen_sammeln`	Sammeln von Name, E-Mail, Telefon
`konto_registrieren`	Benutzerregistrierungsformular
`einstellungen_aktualisieren`	Ändern von Benutzereinstellungen
`rückerstattung_anfordern`	Bearbeitung von Rückerstattungsanfragen
`meeting_planen`	Buchung von Meetings

Vermeiden:

Generische Namen wie form_1 oder daten_sammeln
Übermäßig lange Namen wie alle_informationen_vom_benutzer_sammeln
Sonderzeichen oder Leerzeichen

Prozessbeschreibung

Die Prozessbeschreibung sagt dem LLM, welche Informationen gesammelt werden sollen und warum. Dies ist entscheidend, damit das LLM den Kontext versteht und geeignete Fragen stellt.

Best Practices:

Seien Sie spezifisch, was Sie sammeln
Erwähnen Sie den Zweck oder Kontext
Geben Sie alle wichtigen Einschränkungen an
Schreiben Sie in natürlicher Sprache

Beispiele:

Prozessname	Gute Prozessbeschreibung
`termin_buchen`	"Sammeln Sie das bevorzugte Datum, die Uhrzeit und den Grund für den Besuch des Benutzers, um eine Beratung mit unserem Team zu planen."
`kontaktinformationen_sammeln`	"Sammeln Sie den vollständigen Namen, die E-Mail-Adresse und die Telefonnummer des Kunden für die Kontoerstellung und zukünftige Kommunikation."
`konto_registrieren`	"Sammeln Sie die notwendigen Informationen, um ein neues Benutzerkonto zu erstellen, einschließlich Benutzername, E-Mail, Passwort und Geburtsdatum."
`einstellungen_aktualisieren`	"Aktualisieren Sie die Benachrichtigungseinstellungen des Benutzers, einschließlich E-Mail-Häufigkeit, SMS-Benachrichtigungen und Inhaltsinteressen."
`rückerstattung_anfordern`	"Sammeln Sie Informationen über den Kauf, der erstattet werden muss, einschließlich Bestellnummer, Artikeldetails und Rücksendegrund."

Der Bot wird automatisch:

Identifizieren, welche Felder bereits ausgefüllt sind
Konversationell nach fehlenden Informationen fragen
Die extrahierten Werte gegen den Datentyp und die Validierungsskripte validieren
Die Prozessbeschreibung verwenden, um den Gesprächsfluss zu leiten

Templating in Antworten

Referenzieren Sie Extraktionsfeldwerte in jedem Textausgang mit doppelten geschweiften Klammern:

Hallo {{user_name}}, Ihr Termin ist für {{appointment_date}} geplant.

Wenn das Feld nicht gesetzt ist, wird es als leerer String gerendert. Sie können dies verwenden in:

Antwortknoten

Verzweigungsknoten

Verwenden Sie Extraktionsfelder in bedingter Logik, um den Gesprächsfluss zu steuern:

# Überprüfen, ob der Benutzer eine bestimmte Option ausgewählt hat
tracker_api.get_slot("product_category") == "Elektronik"

Branch_condition

Benutzerdefinierte Skripte

Greifen Sie in benutzerdefinierten Python-Skripten mit der Tracker-API auf Extraktionsfelder zu:

# Einen Slot-Wert abrufen
email = tracker_api.get_slot("user_email")

# Einen Slot-Wert setzen
tracker_api.set_slot("confirmation_sent", True)

# Überprüfen, ob der Slot existiert
if tracker_api.get_slot("phone_number"):
    # Etwas mit der Telefonnummer tun
    pass

Slots nach dem Setzen lesen

Wenn Sie einen Slot-Wert in Ihrem Skript setzen und ihn sofort zurücklesen müssen, verwenden Sie die asynchronen Versionen der Methoden, um sicherzustellen, dass Sie den aktualisierten Wert erhalten:

# ❌ Falsch: Kann alten Wert oder None zurückgeben
tracker_api.set_slot("status", "active")
status = tracker_api.get_slot("status")  # Könnte veraltet sein!

# ✅ Richtig: Gibt immer den aktuellen Wert zurück
tracker_api.set_slot("status", "active")
status = await tracker_api.a_get_slot("status")  # Frische Daten!

Warum das wichtig ist: Wenn Sie einen Slot setzen, wird das Update asynchron im Hintergrund verarbeitet. Die Methode a_get_slot() (beachten Sie das Präfix a_) wartet, bis das Update abgeschlossen ist, bevor der Wert zurückgegeben wird.

Schnellreferenz:

Was Sie brauchen	Zu verwendende Methode
Einen Slot lesen (keine kürzlichen Schreibvorgänge)	`tracker_api.get_slot("name")`
Einen Slot lesen (nach dem Setzen)	`await tracker_api.a_get_slot("name")`
Alle Slots lesen (nach Schreibvorgängen)	`await tracker_api.a_slots`
Einen Slot setzen	`tracker_api.set_slot("name", value)`

Beispiel: Setzen und Verwenden eines berechneten Wertes

async def run(tracker_api, ...):
    # Einen Wert berechnen
    total_price = quantity * unit_price
    
    # Setzen
    tracker_api.set_slot("total_price", total_price)
    
    # Verwenden Sie die asynchrone Methode, um ihn zurückzulesen
    saved_total = await tracker_api.a_get_slot("total_price")
    
    # Jetzt können Sie ihn zuverlässig verwenden
    if saved_total > 1000:
        tracker_api.set_slot("high_value_order", True)

Tipp: Wenn Sie nur Slots lesen und keine setzen, funktioniert die reguläre Methode get_slot() einwandfrei. Verwenden Sie die asynchrone Methode a_get_slot(), wann immer Sie Änderungen an Slots in Ihrem Skript vorgenommen haben.

Best Practices

1. Verwenden Sie beschreibende Namen

Wählen Sie klare, selbstdokumentierende Namen für Ihre Felder:

Gut:

user_email
appointment_date
product_id

Vermeiden:

field1
data
temp

2. Schreiben Sie detaillierte Beschreibungen

Die Beschreibung ist das, was das LLM verwendet, um zu verstehen, was extrahiert werden soll. Seien Sie explizit:

Gut:

Die bevorzugte Kontakt-E-Mail-Adresse des Benutzers. Muss ein gültiges E-Mail-Format mit @-Symbol und Domain sein. Beispiel: user@example.com

Vermeiden:

E-Mail

3. Geben Sie Beispiele an

Geben Sie dem LLM konkrete Beispiele, um die Extraktionsgenauigkeit zu verbessern:

Für Daten:

2024-01-15
2023-12-31
2024-06-20

Für Produktcodes:

PROD-001
ITEM-12345
SKU-ABC-999

4. Verwenden Sie Validierungsskripte sparsam

Fügen Sie Validierungsskripte nur hinzu, wenn es notwendig ist. Sie erhöhen die Komplexität und können die Extraktion verlangsamen. Verwenden Sie sie für:

Geschäftskritische Validierungen
Externe API-Überprüfungen
Komplexe Regeln, die nicht in der Beschreibung ausgedrückt werden können

5. Wählen Sie den richtigen Datentyp

Wählen Sie den am besten geeigneten Datentyp für Ihre Daten:

Verwenden Sie int oder float für Zahlen, auf denen Sie Berechnungen durchführen
Verwenden Sie date oder datetime für zeitliche Daten, die Sie vergleichen oder sortieren
Verwenden Sie bool für Ja/Nein-Entscheidungen
Verwenden Sie str für alles andere

6. Nutzen Sie Enums für begrenzte Auswahlmöglichkeiten

Wenn Benutzer aus einer festen Menge von Optionen wählen müssen, verwenden Sie den Enum-Modus:

Klein
Mittel
Groß
Extra Groß

Dies stellt sicher, dass das LLM nur gültige Optionen extrahiert und Tippfehler oder Variationen verhindert.

7. Halten Sie Prozessbeschreibungen klar

In Formularknoten schreiben Sie klare Prozessbeschreibungen, die erklären, was Sie sammeln:

Gut:

Sammeln Sie die Kontaktinformationen des Benutzers, einschließlich vollständigem Namen, E-Mail-Adresse und Telefonnummer für die Kontoerstellung und zukünftige Kommunikation.

Vermeiden:

Informationen abrufen

Tipp: Siehe den Abschnitt Formularknoten oben für detaillierte Beispiele von Prozessnamen und -beschreibungen für verschiedene Anwendungsfälle wie Termine, Registrierungen und Präferenzen.