37 Connectors επιχειρησιακού επιπέδου

37.1 Επισκόπηση

Τα Sophea Automations ακολουθούν διαφορετική προσέγγιση για τους connectors σε σχέση με τα γενικά εργαλεία αυτοματοποίησης. Αντί να προσφέρουν εκατοντάδες connectors για εξωτερικές εφαρμογές SaaS, εστιάζουν σε ελεγχόμενους connectors επιχειρησιακού επιπέδου, οι οποίοι περιορίζονται ανά μισθωτή, σέβονται τα όρια δικαιωμάτων και ενσωματώνονται στη διοχέτευση RAG.

37.2 Πώς περιορίζονται οι connectors ανά μισθωτή

37.2.1 Απομόνωση μισθωτών

Κάθε connector στη Sophea περιορίζεται σε έναν χώρο εργασίας (μισθωτή). Όταν ένα βήμα ροής εμφανίζει τους διαθέσιμους connectors μέσω του broker, η απόκριση περιλαμβάνει μόνο όσους ανήκουν στον χώρο εργασίας που υπέβαλε το αίτημα. Το broker endpoint:

Ανακτά το tenant ID από τη συμμετοχή στον χώρο εργασίας
Ανοίγει μια συνεδρία βάσης δεδομένων περιορισμένη στον μισθωτή
Καλεί τη fetch_connectors() με φίλτρο μισθωτή
Επιστρέφει μόνο connectors με DocumentSource.INGESTION_API (connectors που προέρχονται από API)

Αυτό σημαίνει ότι μια ροή στον Χώρο εργασίας A δεν μπορεί ποτέ να δει ή να προσπελάσει connectors του Χώρου εργασίας B.

37.2.2 Συγχρονισμός δικαιωμάτων

Τα δικαιώματα των connectors συγχρονίζονται από το Portal. Όταν ένα μέλος του χώρου εργασίας εκτελεί μια ροή, ο broker:

Επαληθεύει ότι ο χρήστης είναι ενεργό μέλος του χώρου εργασίας (_verify_runtime_member)
Δημιουργεί υπογεγραμμένα ACL principals βάσει του email και της συμμετοχής του χρήστη στον χώρο εργασίας
Διαδίδει το ACL στην υπηρεσία RAG για τις λειτουργίες αναζήτησης

Το ACL διασφαλίζει ότι τα βήματα ροής μπορούν να προσπελάσουν μόνο έγγραφα τα οποία έχει δικαίωμα να δει ο χρήστης που υπέβαλε το αίτημα. Εάν ένας χρήστης δεν έχει πρόσβαση σε ένα σύνολο εγγράφων, κανένα βήμα ροής που ενεργοποιεί δεν μπορεί να αποκτήσει πρόσβαση σε αυτό.

37.3 Θεμελίωση με RAG

37.3.1 Τι είναι η θεμελίωση με RAG;

Η θεμελίωση με RAG (Retrieval-Augmented Generation) σημαίνει ότι οι ενέργειες AI στις ροές έχουν πάντοτε πρόσβαση στη βάση γνώσης του χώρου εργασίας. Αντί να στέλνουν prompts σε ένα LLM χωρίς συναφές περιεχόμενο, οι ενέργειες της Sophea αναζητούν πρώτα στην ευρετηριασμένη βάση γνώσης και κατόπιν μεταβιβάζουν τα ανακτημένα τμήματα ως συναφές περιεχόμενο στο LLM.

37.3.2 Πώς λειτουργεί

Ένα βήμα ροής καλεί την ask_nous_knowledge με μια ερώτηση
Το broker endpoint δημιουργεί υπογεγραμμένα ACL principals για τον χρήστη που υπέβαλε το αίτημα
Ο broker καλεί τη run_batch_search() στην υπηρεσία RAG και μεταβιβάζει το υπογεγραμμένο ACL
Η υπηρεσία RAG πραγματοποιεί αναζήτηση στο διανυσματικό ευρετήριο, με φίλτρο το ACL
Τα ανακτημένα τμήματα μεταβιβάζονται ως συναφές περιεχόμενο στο LLM
Το LLM δημιουργεί μια απάντηση θεμελιωμένη στα ανακτημένα έγγραφα
Η απάντηση επιστρέφεται στο βήμα ροής μαζί με παραπομπές

37.3.3 Διαθέσιμες ενέργειες RAG

Ενέργεια	Περιγραφή
`ask_nous_knowledge`	Υποβάλλει μια ερώτηση και επιστρέφει θεμελιωμένη απάντηση με παραπομπές
`search_knowledge`	Αναζητά στη βάση γνώσης και επιστρέφει ανεπεξέργαστα τμήματα
`batch_search_knowledge`	Εκτελεί πολλαπλές αναζητήσεις σε ένα βήμα
`fetch_chunks`	Ανακτά όλα τα τμήματα ενός συγκεκριμένου εγγράφου

37.3.4 Επιβολή ACL στο RAG

Η υπηρεσία RAG επιβάλλει το ACL σε επίπεδο ερωτήματος. Όταν λαμβάνεται ένα αίτημα αναζήτησης:

Επαληθεύεται η κεφαλίδα X-Sophea-Principals (υπογραφή HMAC)
Αποκωδικοποιείται το υπογεγραμμένο ACL: {tid, uid, pr, exp}
Εάν το tenant ID ή το user ID δεν συμφωνεί με το αίτημα, η αναζήτηση επιστρέφει 401
Η διανυσματική αναζήτηση φιλτράρει τα αποτελέσματα ώστε να περιλαμβάνουν μόνο έγγραφα που αντιστοιχούν στο ACL
Εάν το ACL έχει λήξει ή λείπει, η συμπεριφορά εξαρτάται από το REQUIRE_SIGNED_PRINCIPALS:
- off (προεπιλογή): επιστροφή στο acl_principals του σώματος
- warn: καταγραφή προειδοποίησης και επιστροφή στο acl_principals του σώματος
- enforce: επιστροφή 401

37.4 Τύποι connector

37.4.1 Sophea piece (εγγενές)

Το Sophea piece παρέχει 21 ενέργειες και 4 triggers που είναι εγγενή στην πλατφόρμα:

Γνώση: ask_nous_knowledge, search_knowledge, batch_search_knowledge, fetch_chunks
AI: ask_workspace_model, run_nous_agent
Κύκλος ζωής agent: start_agent_run, get_agent_run_status, cancel_agent_run, get_agent_run_artifacts
Εγκρίσεις: request_human_approval, create_approval_task, llm_approval
Χώρος εργασίας: list_connectors, list_workspace_users, list_workspace_teams, fetch_saved_searches, notify_workspace, send_workspace_email
Έγγραφα: upload_document, get_document_status
Triggers: agent_run_completed, document_indexed, connector_sync_completed, connector_sync_failed

37.4.2 Λίστα επιτρεπόμενων στοιχείων λειτουργίας shell

Στη λειτουργία shell είναι διαθέσιμα μόνο ελεγμένα pieces (18 συνολικά):

@activepieces/piece-sophea (όλες οι ενέργειες και τα triggers της Sophea)
@activepieces/piece-manual-trigger (χειροκίνητο trigger)
@activepieces/piece-schedule (triggers βάσει χρόνου)
@activepieces/piece-webhook (webhook trigger υπογεγραμμένο με HMAC)
@activepieces/piece-tables (πίνακες δεδομένων)
@activepieces/piece-forms (φόρμες και ανθρώπινη εισαγωγή)
@activepieces/piece-file-helper (λειτουργίες αρχείων)
@activepieces/piece-csv (λειτουργίες CSV)
@activepieces/piece-data-mapper (μετασχηματισμός δεδομένων)
@activepieces/piece-data-summarizer (σύνοψη δεδομένων)
@activepieces/piece-date-helper (βοηθητικές λειτουργίες ημερομηνίας)
@activepieces/piece-delay (βήμα καθυστέρησης)
@activepieces/piece-math-helper (μαθηματικές λειτουργίες)
@activepieces/piece-pdf (λειτουργίες PDF)
@activepieces/piece-qrcode (δημιουργία κωδικών QR)
@activepieces/piece-store (αποθήκευση ζευγών κλειδιού-τιμής)
@activepieces/piece-text-helper (βοηθητικές λειτουργίες κειμένου)
@activepieces/piece-xml (λειτουργίες XML)

37.4.3 Εξωτερικοί connectors

Εξωτερικοί connectors, όπως Slack, Google Drive και Confluence, είναι διαθέσιμοι εκτός λειτουργίας shell. Η διαχείρισή τους γίνεται μέσω του τυπικού πλαισίου connectors και σέβονται την απομόνωση μισθωτών σε επίπεδο σύνδεσης. Κάθε σύνδεση περιορίζεται σε έναν χώρο εργασίας.

37.5 Μοντέλο ασφαλείας

Επίπεδο	Μηχανισμός
Μεταφορά	HTTP υπογεγραμμένο με HMAC μεταξύ Automations API και backend του Nous
Μισθωτής	Το workspace ID επαληθεύεται σε κάθε κλήση προς τον broker
Χρήστης	Επαλήθευση μέλους κατά την εκτέλεση (ενεργή συμμετοχή στον χώρο εργασίας)
Δεδομένα	Υπογεγραμμένα ACL principals διαδίδονται στην υπηρεσία RAG
Εκτέλεση	Εκτέλεση pieces σε sandbox με ελεγμένη λίστα επιτρεπόμενων στοιχείων
Webhooks	Επαλήθευση υπογραφής HMAC σε εισερχόμενα webhooks