Daten-Connectoren ermöglichen es Fin, über API-Endpunkte mit externen Systemen zu interagieren. Fin kann Daten-Connectoren verwenden, um:
Informationen vom Daten-Connector lesen (z. B. welchen Plan der Nutzer hat).
Aktionen ausführen (z. B. Verwendung eines POST, um ein Abonnement in einem externen System zu kündigen).
Loslegen
Hinzufügen eines Daten-Connectors zu einem Instruction-Schritt
Geben Sie in einem Instruction-Schritt @ ein, um das Werkzeugmenü zu öffnen.
Wählen Sie Daten-Connector aufrufen.
Wählen Sie den spezifischen Connector aus, den Sie ausführen möchten (zum Beispiel Bestellungen abrufen, um die Kaufhistorie eines Kunden abzurufen).
Tipp: Erfahren Sie, wie Sie Daten-Connectoren einrichten, um Live-Informationen direkt aus Ihren internen Systemen oder Drittanbieter-APIs in Ihre Fin Procedures zu ziehen.
Zugriff auf die Antwort mit automatisch generierten Attributen
Sobald ein Connector hinzugefügt wurde, können Sie die Antwort sofort in nachfolgenden Schritten verwenden. Dies steht Fin allgemein als Kontext zur Verfügung, aber wir parsen die Antwortfelder auch in Daten-Connectoren, damit Sie explizit auf Elemente im Antwortkörper für höchste Zuverlässigkeit verweisen können.
Hinweis: Eine Antwortzuordnung ist bei der Verwendung von Daten-Connectoren in Procedures nicht erforderlich. Fin verwendet die Testantwort, die Sie im Daten-Connector konfigurieren, um die Struktur der API-Antwort mit den verfügbaren Feldnamen und deren Typen zu verstehen. Sie können dann in Ihren Verfahrensanweisungen einfache Sprache verwenden, um Fin mitzuteilen, welche Daten aus der Antwort verwendet werden sollen. Zur Laufzeit macht Fin einen Live-API-Aufruf und liest die echten Werte aus diesen Feldern.
Geben Sie @ ein und wählen Sie Ein Attribut lesen.
Sie sehen die Antwortfelder des Daten-Connectors automatisch oben im Dropdown-Menü aufgelistet (z. B. Lieferauftrag abrufen > Status, Lieferauftrag abrufen > order_id).
Wählen Sie das spezifische Attribut aus, das Sie in Ihre Anweisung oder Bedingung einfügen möchten.
Kontext wird über das gesamte Procedure geteilt
Wenn Sie Fin anweisen, einen Daten-Connector zu verwenden (@ use data connector), werden die zurückgegebenen Daten im gesamten Procedure verfügbar.
Für höhere Zuverlässigkeit können Sie auf diese Daten mit (@ read attributes) zugreifen. Fin behält Connector-Daten für die gesamte Dauer eines Procedures, einschließlich aller Schritte und Unterverfahren. Sie müssen jeden Connector nur einmal pro Procedure aufrufen, es sei denn, Sie benötigen explizit aktualisierte Daten.
Zum Beispiel, wenn Sie (@ use Get_Subscription_info) im ersten Schritt aufrufen, behält Fin den Abonnement-Kontext des Kunden für alle nachfolgenden Schritte und Unterverfahren.
Beste Praktiken
Nutzen Sie Mock-Daten-Connectoren, um Ihre Procedure zu testen und aufzubauen
Sie benötigen keine vollständig funktionierende Live-API, um mit dem Aufbau von Procedures zu beginnen. Sie können Beispielantworten verwenden, um Daten zu simulieren.
Beispielantwort: Wählen Sie im Setup des Daten-Connectors (unter dem Tab „Testantwort“) Beispielantwort aus und fügen Sie eine Mock-JSON-Nutzlast ein. So können Sie den Ablauf der Procedure sofort aufbauen und testen.
Dynamisches Mocking: Für komplexere Szenarien können Sie Tools wie Beeceptor verwenden, um dynamische API-Antworten zu simulieren.
Optimieren Sie Ihre API-Antworten so, dass sie die kleinstmögliche Teilmenge relevanter Daten enthalten, die Fin für die Procedure benötigt.
Zu viele irrelevante Daten können die Leistung beeinträchtigen. Generell gilt: Je kleiner und präziser, desto besser.
Wenn eine Datenumwandlung erforderlich ist, wird dringend empfohlen, die Daten entweder durch Auswahl einer begrenzten Anzahl von Feldern oder durch Verwendung von Daten-Connector-Codeblöcken zu transformieren. Dies transformiert die API-Antwort, bevor Fin sie im Procedure sieht.
Optimieren Sie, nicht mehr als einen Daten-Connector pro Schritt zu verwenden.
Ein Schritt soll eine einzelne Arbeitseinheit sein. Fin ist am zuverlässigsten, wenn Sie in einem einzelnen Schritt nur einen Daten-Connector aufrufen.
Daten-Connectoren einmal pro Kontext aufrufen
In Procedures bezeichnet „Kontext“ den gesamten Ablauf des Procedures. Fin verwendet Connector-Daten automatisch über alle Schritte und Unterverfahren hinweg wieder. Sie müssen dieselbe API nicht zweimal aufrufen.
❌ Es ist nicht notwendig, denselben Connector in mehreren Schritten aufzurufen:
Step 1:
… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows
Step 2
… (@use Get_Subscription_info) … and include @read refund eligibility in your response so the users knows
✅ Es ist einfacher, sauberer und schneller, den Connector nur einmal aufzurufen:
Step 1:
… (@use Get_Subscription_info) … include @read plan status in your response so the users knows
Step 2
… include @read refund eligibility in your response so the users knows
Wenn Sie Daten aus mehreren Systemen benötigen, verteilen Sie die Logik auf mehrere Schritte, anstatt mehrere Connectoren in einem Schritt aufzurufen.
Es ist nicht nötig, Fin zu bitten, Daten zu sammeln, die bereits als erforderliche Eingaben für einen Daten-Connector konfiguriert sind.
Eingaben werden während der Einrichtung des Daten-Connectors vorkonfiguriert, sodass Fin die benötigten Eingaben automatisch ableitet, ohne dass Sie Fin explizit auffordern müssen, diese Daten zu sammeln.
Zum Beispiel, wenn der Daten-Connector Get Order Details bereits das Eingabefeld E-Mail konfiguriert hat:
❌ Unnötig komplexe Anweisung:
First ask the customer for their email, then call @get_order_details with that email
✅ Klare Anweisungen:
Call @get_order_details
Fin leitet erforderliche Eingaben basierend auf der Connector-Konfiguration automatisch ab und sammelt sie, sofern die Eingabe nicht bereits direkt von Intercom bereitgestellt wird.
Hinweis: Wenn Sie Leistungs- oder Zuverlässigkeitsprobleme bei der Eingabesammlung bemerken, können Sie Fin explizit anweisen, wann diese Daten gesammelt werden sollen.
Profi-Tipp: Wenn ein Procedure genaue, unveränderte oder sichere Daten benötigt (z. B. E-Mail, Benutzer-ID oder Kontoinformationen), injizieren Sie diese Werte direkt von Intercom in den Connector. Indem Sie das Attribut direkt im Connector konfigurieren statt als von Fin gesammelte Eingabe, umgeht die Daten die Sammlung oder Verarbeitung durch Fin vollständig und bleiben unverändert.
Überwachung der Connector-Gesundheit
Procedures, die Daten-Connectoren verwenden, zeigen auf der Prozeduren-Übersichtsseite einen Connector-Probleme-Indikator, sodass Sie Connector-Probleme auf einen Blick erkennen können, ohne jede Prozedur zu öffnen. Die Anzeige spiegelt den am schlechtesten performenden Connector wider, der in den letzten 14 Tagen verwendet wurde (maximal 1.000 Ausführungen pro Connector).
Procedures ohne Daten-Connectoren zeigen keinen Indikator; Connectoren ohne Ausführungen gelten als gesund.
Hinweis: Der Connector-Probleme-Indikator auf der Prozeduren-Übersichtsseite zeigt immer die letzten 14 Tage an. Erfolgsraten im Gesundheits-Dashboard eines Daten-Connectors folgen dem dort gewählten Zeitfilter. Nach der Behebung eines Problems müssen Sie möglicherweise auf neue Daten warten oder den Zeitfilter anpassen, um zu bestätigen, dass der Connector erfolgreich ist.
Gesundheitszustände
Status | Kriterien | Auswirkung |
🟡 Verschlechtert | Ein Connector hat eine Erfolgsrate von 80–95 %, oder >95 % Erfolgsrate, aber eine durchschnittliche Antwortgröße ≥50 KB (~15K Tokens). | Erlebt Probleme oder liefert große Antworten, die das Risiko von Halluzinationen erhöhen können. |
🔴 Ungesund | Ein Connector hat eine Erfolgsrate von <80 %, oder eine durchschnittliche Antwortgröße ≥100 KB (~30K Tokens). | Kritische Probleme oder gefährlich große Antworten, die sofortige Aufmerksamkeit erfordern. |
Detaillierte Ansicht
Ein Klick auf den Connector-Probleme-Indikator öffnet ein Panel mit einer Karte pro betroffenem Connector, die dessen Status (Verschlechtert oder Ungesund), Erfolgsrate, Ausführungsanzahl und Antwortgröße zeigt. Connector-Namen verlinken direkt zur Einstellungsseite für schnelles Debugging.
Umgang mit Arrays
Wenn ein Daten-Connector eine Liste zurückgibt, stellt Fin nur das Wurzel-Array als Attribut bereit. Kind-Elemente innerhalb des Arrays werden im Attribut-Auswahlmenü nicht als separate Attribute angezeigt.
Zum Beispiel, wenn ein Connector ein items-Array zurückgibt, sehen Sie:
Bestellungen abrufen > items
Aber Sie sehen nicht:
Bestellungen abrufen > items > titleBestellungen abrufen > items > price
Fin kann dennoch mit dem Inhalt einer Liste arbeiten. Zum Beispiel, wenn Sie folgende Anweisung geben: „Wenn der Kunde fragt, was in seiner Bestellung ist, verwenden Sie Bestellung abrufen > items, um die Produkte und deren Preise aufzulisten.“
Fin liest den gesamten Inhalt der Items-Liste und antwortet mit: „Ihre Bestellung enthält eine kabellose Maus (24,99 $) und einen Laptop-Ständer (39,99 $).“
Zum Beispiel: Für die untenstehende Antwort-Nutzlast wird nur das Wurzel-Array-Element items als temporäres Attribut bereitgestellt, nicht jedoch dessen Kinder.
{
"order_id": "ORD-1001",
"status": "processing",
"created_at": "2025-01-12T14:23:00Z",
"items": [
{
"product_id": "PROD-200",
"name": "Wireless Mouse",
"quantity": 1,
"unit_price": 24.99
},
{
"product_id": "PROD-122",
"name": "Laptop Stand",
"quantity": 1,
"unit_price": 39.99
}
]
}
Hinweis: @Read Bestellungen abrufen > items und nennen Sie dem Kunden die drei wichtigsten Artikel in seiner Bestellung.
Verwendung von Arrays in Code-Bedingungen
Array-Attribute sind unter dem Objekt inputs["data_connector"] verfügbar, gruppiert nach dem Namen des Daten-Connectors. Arrays sind nullbasiert, das heißt, das erste Element hat den Index 0. Prüfen Sie immer die Array-Länge bevor Sie auf einen bestimmten Index zugreifen.
Sie können Werte innerhalb eines Arrays weiterhin mit einer Code-Bedingung abfragen.
In Code-Bedingungen wird auf Array-Daten mit Python-Ausdrücken zugegriffen, wobei Sie Elemente explizit nach Index referenzieren oder über die Liste iterieren.
Diese Bedingung prüft, ob die Bestellung mindestens vier Artikel enthält und die Menge des vierten Artikels größer als drei ist.
Validieren Sie immer die Array-Länge, bevor Sie auf einen Index zugreifen, um Laufzeitfehler bei der Bedingungsbewertung zu vermeiden.
Hinweis: Die verfügbaren Aktionen hängen davon ab, wie Ihr Daten-Connector konfiguriert ist.
Daten-Connectoren unterstützen:
Erstellen: Verwenden Sie POST-Anfragen, um neue Datensätze in einem externen System zu erstellen.
Lesen: Verwenden Sie GET-Anfragen, um vorhandene Daten abzurufen.
Aktualisieren: Verwenden Sie PUT- oder PATCH-Anfragen, um vorhandene Datensätze zu ändern.
Löschen: Verwenden Sie DELETE-Anfragen, um Datensätze zu entfernen.