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
Einen Daten-Connector zu einem Instruction-Schritt hinzufügen
Geben Sie in einem Instruction-Schritt @ ein, um das Werkzeugmenü zu öffnen.
Wählen Sie Daten-Connector aufrufen.
Wählen Sie den spezifischen Connector, 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 sofort in nachfolgenden Schritten auf die Antwort zugreifen. Dies steht Fin allgemein als Kontext zur Verfügung, aber wir parsen auch die Antwortfelder in Daten-Connectoren, um Ihnen zu ermöglichen, explizit auf Elemente im Antwortkörper für höchste Zuverlässigkeit zu verweisen.
Hinweis: Response-Mapping 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. Bestellung abrufen > Status, Bestellung 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.
Wenn Sie beispielsweise den (@ use Get_Subscription_info) im ersten Schritt aufrufen, behält Fin den Abonnement-Kontext des Kunden für alle nachfolgenden Schritte und Unterverfahren bei.
Best Practices
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 „Test response“) Beispielantwort 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, damit sie das kleinstmögliche relevante Daten-Subset enthalten, das 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 bezieht sich „Kontext“ auf den gesamten Procedure-Durchlauf. 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 einzigen 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 sind während der Einrichtung des Daten-Connectors vorkonfiguriert, sodass Fin die Eingaben, die es zum Aufrufen des Daten-Connectors benötigt, selbst ableiten kann, ohne dass Sie Fin explizit auffordern müssen, diese Daten zu sammeln.
Beispielsweise, 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 automatisch die erforderlichen Eingaben basierend auf der Connector-Konfiguration 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, anstatt es als von Fin gesammelte Eingabe zu verwenden, 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 einen Gesundheitsindikator direkt auf der Prozeduren-Übersichtsseite, sodass Sie Connector-Probleme auf einen Blick erkennen können, ohne jede Procedure zu öffnen. Der Stempel zeigt den am schlechtesten performenden Connector dieser Procedure an, berechnet über die letzten 14 Tage (maximal 1.000 Ausführungen pro Connector).
Procedures ohne Daten-Connectoren zeigen keinen Indikator; Connectoren mit null Ausführungen gelten als gesund.
Gesundheitsstatus
Status | Kriterien | Auswirkung |
🟢 Gesund | Alle Connectoren haben eine Erfolgsrate von >95 % und eine durchschnittliche Antwortgröße unter 50 KB. | Funktioniert optimal. |
🟡 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. |
Details anzeigen
Ein Klick auf den Gesundheitsstempel öffnet eine Seitenleiste mit einer Aufschlüsselung pro Connector: Status, Erfolgsrate, durchschnittliche Antwortgröße, P90-Latenz und häufigste Fehler. Connector-Namen verlinken direkt zur Einstellungsseite für schnelles Debugging.
Tipp: Wenn ein Connector aufgrund der Antwortgröße als Verschlechtert oder Ungesund angezeigt wird, siehe die oben genannte Best Practice Optimieren Sie Ihre API-Antworten, damit sie das kleinstmögliche relevante Daten-Subset enthalten, das Fin benötigt. Das Filtern von Feldern oder die Verwendung von Codeblöcken, um die Antwort vor der Ansicht durch Fin zu kürzen, ist die schnellste Lösung.
Umgang mit Arrays
Wenn ein Daten-Connector eine Liste zurückgibt, stellt Fin nur das Wurzel-Array als Attribut bereit. Kindelemente innerhalb des Arrays werden im Attribut-Auswahlmenü nicht als separate Attribute angezeigt.
Beispielsweise sehen Sie, wenn ein Connector ein items-Array zurückgibt:
Bestellungen abrufen > items
Aber Sie sehen nicht:
Bestellungen abrufen > items > titleBestellungen abrufen > items > price
Fin kann trotzdem 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 Wireless Mouse ($24.99) und einen Laptopstä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 werden Array-Daten mit Python-Ausdrücken abgerufen, bei denen Sie Elemente explizit nach Index referenzieren oder über die Liste iterieren.
Diese Bedingung prüft, ob die Bestellung mindestens vier Artikel enthält und ob 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.