Connectors

Les connecteurs sont la moitié propre aux fournisseurs de la façon dont Tale atteint d’autres systèmes, et ils font partie de la plateforme plutôt que d’un assemblage à la charge d’une organisation. Chacun est un fichier YAML dans l’arbre des sources qui déclare à qui il parle, comment il s’authentifie et chaque action qu’il sait exécuter — d’où un catalogue identique dans tous les déploiements, qu’une mise à jour suffit à faire avancer. Lis cette page pour savoir ce qu’un connecteur promet réellement à un appelant, ou quand tu hésites entre contribuer un connecteur et atteindre ton propre service depuis un agent de projet ou une automatisation.

Le versant organisation — ajouter des identifiants, choisir celui par défaut, relancer une autorisation expirée — est Identifiants d’connector, et le catalogue lui-même est Connectors.

Comment un connecteur est déclaré

Chaque connecteur est un répertoire sous configs/platform/system/connectors/, nommé d’après son slug, contenant un connector.yml et l’icône que la page de paramètres affiche. Le slug est à la fois le nom du répertoire, le name déclaré du connecteur et la première moitié du type de nœud avec lequel une automatisation pose une de ses actions — <connector>.<action>. Quatorze connecteurs fournisseurs apparaissent aujourd’hui dans Paramètres (plus quelques connecteurs d’auth plateforme absents du sélecteur).

Le fichier s’ouvre sur l’identité du connecteur et son contrat d’authentification, puis énumère les actions :

name: tavily
displayName: Tavily
description: Real-time web search and page extraction for AI research.
tags:
  - Search
allowedHosts:
  - api.tavily.com
auth:
  - method: api-key
actions:
  - name: search
    description: >-
      Search the open web via Tavily. Returns top results with title, URL,
      content snippet, and score.
    effects: read
    input:
      type: object
      required: [query]
      properties:
        query: { type: string, description: 'Natural-language search query.' }
        max_results: { type: number, description: 'Max results (1-10).' }
    output: '{ answer?: string, results: Array<{ title: string, url: string, content: string, score: number }> }'

allowedHosts est la frontière de sortie — un corps d’action qui viserait ailleurs est refusé plutôt que relayé. Un connecteur dont l’API vit chez le client plutôt que chez le fournisseur ajoute endpointMode: per-credential, et chaque identifiant porte alors l’origine à partir de laquelle ses appels sont construits ; Confluence et Shopify sont les deux cas livrés.

Ce qu’une action déclare

Une action est un contrat, et chacun de ses champs est visible pour l’appelant avant que l’appel n’ait lieu :

• Nom et description. Le nom complète le type de nœud ; la description est ce que lit un agent quand il décide si cette action est la bonne.
• Entrée. Un JSON Schema — type objet, champs obligatoires et une description par propriété. Les automatisations valident la configuration d’un nœud contre lui, et les agents la remplissent à partir du même schéma.
• Sortie. Une signature décrivant la forme qui revient, pour que l’auteur d’un workflow sache ce que l’étape suivante peut référencer.
• Effets. Soit read, soit write. Les actions en écriture passent par la politique d’approbation de l’organisation, et un appel qui n’atteint aucune décision d’approbation est refusé plutôt qu’exécuté sans contrôle.

Les actions résolvent leur identifiant au moment de l’appel : celui que l’appelant nomme, ou celui par défaut du connecteur quand il n’en nomme aucun. C’est cette couture qui permet à la même automatisation de tourner sur un autre compte en la pointant vers un autre nom d’identifiant. La sync mail et le triage de boîte s’écartent volontairement de cette règle : conversation.sync_mailbox et conversation.list_mailbox_messages parcourent chaque identifiant actif du connecteur, pour couvrir chaque boîte connectée sans qu’une automatisation ait à les nommer une à une.

Les méthodes d’authentification

Un connecteur déclare les méthodes qu’il accepte, et un identifiant est enregistré sous exactement l’une d’elles. Les quatre sont fixes, parce que chacune décrit un chemin différent par lequel un secret atteint le fournisseur.

Les secrets sont chiffrés au repos dans une seule enveloppe et ne ressortent jamais vers un appelant. Une liste affiche un aperçu masqué calculé à l’écriture de l’identifiant, si bien que lire la liste ne touche jamais au chiffré.

Enregistrer une application OAuth

Un connecteur oauth2 déclare les URL d’autorisation et de jeton du fournisseur ainsi que les portées qu’il demande, et il faut bien une application contre laquelle ces URL s’authentifient. Deux sources existent, et la plus spécifique gagne :

• Par organisation — un admin de l’organisation ouvre Paramètres > Connectors et, sous Apps OAuth, colle l’ID client et le secret de l’enregistrement d’app du fournisseur (plus l’ID d’annuaire pour une app Microsoft mono-tenant ; Tale autorise alors contre ce tenant au lieu de /common). Le secret est chiffré et ne s’affiche plus jamais. Sur un déploiement multi-organisations, c’est ce qui permet à chaque organisation d’apporter sa propre app.
• Par déploiement — des variables d’environnement nommées par connecteur CONNECTOR_OAUTH_<SLUG>_CLIENT_ID et CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET, le slug en majuscules et ses tirets changés en tirets bas. Elles restent la valeur par défaut du déploiement partout où une organisation n’a pas configuré sa propre app.

Slack est l’exception : son app reste dans l’environnement (CONNECTOR_OAUTH_SLACK_* plus CONNECTOR_SLACK_SIGNING_SECRET), parce que la vérification des événements entrants s’exécute avant qu’aucune organisation ne soit connue. Enregistre ${SITE_URL}${BASE_PATH}/api/connectors/slack/events comme Events Request URL dans l’app Slack ; l’endpoint ne répond au handshake d’enregistrement qu’une fois le secret de signature défini, et renvoie 503 jusque-là. Une livraison est vérifiée avec le secret de signature, routée vers l’organisation dont le workspace l’a envoyée, puis acquittée — rien ne la traite plus loin dans cette version : connecter Slack aujourd’hui te donne les actions sortantes, pas une conversation entrante.

Enregistre exactement ce callback comme URI de redirection autorisée côté fournisseur, construit à partir du SITE_URL du déploiement et de son éventuel préfixe BASE_PATH :

${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback

Quand SITE_URL n’est pas défini, le consentement refuse de démarrer au lieu de deviner une origine à partir de la requête.

L’import personnel OneDrive / Google Drive pour Knowledge n’est pas un connector d’organisation — mais il résout son app OAuth de la même façon, et l’app google-drive est partagée entre les deux voies : un seul client OAuth Google, avec les deux URI de redirection enregistrées, sert le connecteur et l’import de connaissances. Voir Documents et l’URI cloud-import sous Référence d’environnement.

Choisir une surface

Deux surfaces atteignent des systèmes hors de Tale, et le choix porte sur qui possède le pont et qui le fait tourner.

Enregistrer un serveur MCP externe ne fait pas partie de cette version — la seule surface MCP de Tale est l’endpoint entrant sous Paramètres > API > MCP, où ton client MCP pilote Tale. Serveurs MCP dit ce qui a remplacé le formulaire d’enregistrement ; Endpoint MCP est la référence de la surface qui existe vraiment.

Où cela s’inscrit

Un connecteur est un contrat déclaré — hôtes, authentification et une liste d’actions typées — livré avec la plateforme et alimenté par des identifiants qui appartiennent à l’organisation. Lis Connectors pour ce que contient le catalogue, Identifiants d’connector pour la gestion quotidienne de ces identifiants, et Serveurs MCP pour la seule surface MCP que cette version livre.