Livrer et gérer les intégrations personnalisées

Portées des intégrations personnalisées

Les identités d'intégration réservent trois portées. Les importations d'organisation constituent actuellement le chemin pris en charge pour les intégrations personnalisées :

Livraison via une source de extension

Ce qui se passe lors de l'installation

Lorsqu'une extension contenant une entrée extension est installé, la plateforme exécute le même pipeline de archive qu'auparavant :

00_organization/extension-archives/{extensionId}/{version}/archive.tar.gz

Gérer les intégrations personnalisées installées

Paramètres > Plateforme > Extensions > Installées liste chaque extension explicitement installée par votre organisation — via Ajouter une extension ou une installation depuis le catalogue de extensions — ainsi que le vendeur natif Scrydon (livré avec chaque organisation, ne peut pas être supprimé) et vos serveurs MCP enregistrés, une ligne chacun. Les vendeurs du catalogue que personne n'a ajoutés ne sont pas des lignes ; ils se trouvent dans le flux d'ajout d'extension. Une ligne se lit comme une phrase : la marque et le nom du vendeur, son éditeur (Scrydon, un vendeur, ou votre organisation), une ligne en mots de ce qu'elle apporte, une seule ligne d'état, et sa version — une mise à jour disponible s'affiche dans la colonne version sous la forme 1.3.1 → 1.4.2, sans jamais chasser un état qui demande une action. L'activation se fait dans le panneau, où sa portée organisationnelle est écrite en toutes lettres. Les lignes qui demandent une action passent en tête, et le bouton Filtrer restreint par contenu (modèles IA, outils d'agents, contenu, serveurs MCP), état et éditeur.

États

Le panneau de l'extension

Cliquez sur une ligne pour ouvrir le panneau latéral de l'extension. Tout s'y trouve, par onglets :

• Configuration — vos étapes organisationnelles sous forme de liste de contrôle (« Compte Microsoft connecté — OAuth · 12 produits ») avec une jauge de progression ; la mécanique de configuration (domaines de sortie approuvés, URL de redirection OAuth, instructions console, mode système) se replie derrière Détails de connexion & instructions, ouvert tant que la configuration n'est pas terminée.
• Inclus — ce que l'extension apporte : les modèles IA d'abord (avec la liste des modèles et l'éditeur de liste d'autorisation derrière chaque capacité), puis les outils d'agents groupés par produit, chacun avec son interrupteur Activé · à l'échelle de l'organisation — Non activé lorsqu'il est éteint. Activer au sens espace de travail n'apparaît jamais ici. Les vendeurs longs replient la fin en N produits de plus.
• Connexions — les connexions du vendeur par produit, leurs environnements et l'identité d'exécution par défaut de chaque connexion.
• Accès — les espaces de travail autorisés à utiliser le vendeur.
• Utilisation — les workflows et bases de connaissances qui le référencent.
• Version & sécurité — à lire de haut en bas : la carte de mise à jour (uniquement s'il y en a une, indiquant ce qui change et ce qui est conservé), la version installée (version · source · signature · révision), ce qui s'exécute, et où (par exécutable : le code de qui, comment il est isolé, ce qu'il peut joindre — un bouclier de confiance signale le code tiers, et une extension publiée par Scrydon n'en porte aucun), l'historique des versions, et la désinstallation.

Le menu ··· de l'en-tête du panneau porte Activer / Désactiver pour l'organisation et les actions de cycle de vie — Examiner la nouvelle version, Déprécier / Annuler la dépréciation, Supprimer. Le panneau est accessible par lien direct : /settings/platform/extensions?extension=<slug> l'ouvre directement (les anciens liens ?vendor= fonctionnent toujours).

L'onglet Modèles & valeurs par défaut

Paramètres > Plateforme > Extensions > Modèles & valeurs par défaut est l'inventaire des capacités IA (LLM, embeddings, reconnaissance vocale, synthèse vocale, image, vidéo, OCR, modération, recherche web) et l'endroit où se définissent les valeurs par défaut de l'organisation : une ligne par capacité, toujours toutes, avec le vendeur qui la fournit et un sélecteur Par défaut — Sélection automatique (la plateforme classe ce qui est installé ; la ligne montre son choix actuel) ou un fournisseur/modèle épinglé, enregistré ligne par ligne. Une capacité que personne ne fournit propose Ajouter un vendeur (le flux Ajouter une extension). Une note à côté de la ligne indique ce qu'il est utile de savoir : un vendeur installé dont tous les produits sont désactivés (avec un raccourci Activer), ou un vendeur en cours de retrait et à quelle date. Une ligne coiffe l'onglet — Capacités configurées · 6 sur 9 · Vidéo, Modération et Recherche web n'ont pas de vendeur.

L'ancienne page Valeurs par défaut de la plateforme est cet onglet ; son adresse (/settings/platform/defaults) redirige ici. Couper le badge de la barre latérale dans le pied de l'onglet acquitte les manques actuels pour toute l'organisation, de sorte que le badge de l'entrée Extensions reste silencieux jusqu'à l'apparition d'un nouveau manque — l'inventaire lui-même n'est jamais masqué.

Activer / Désactiver

Activer / Désactiver pour l'organisation dans le menu ··· du panneau active ou désactive tous les produits du vendeur d'un coup ; l'interrupteur d'une ligne de produit dans l'onglet Contenu du panneau ne bascule que ce produit, pour toute l'organisation. La désactivation retire les produits de l'éditeur de workflows mais ne supprime ni les fichiers stockés ni les identifiants.

Gestion des versions

Publiez une nouvelle version de extension pour mettre à jour l'intégration. La plateforme stocke chaque version par {extensionId}/{version}/, de sorte que plusieurs versions peuvent coexister ; la version active est la version active de plus haut semver (ou la version épinglée si votre organisation en a épinglé une — voir Gestion des versions de extensions).

Séquence de catalogue et d'exécution

Au démarrage de la plateforme :

1. Analyse des archives première partie — analyse manifest.json depuis /app/archives/ (image Docker)
2. Analyse des archives de plateforme — analyse les manifestes depuis le stockage de la plateforme
3. Analyse des archives d'organisation — analyse les manifestes depuis le stockage de chaque organisation
4. Remplissage du catalogue de manifestes — métadonnées uniquement, aucun code vendeur chargé
5. Publication dynamique de la disponibilité — le Runtime Plane indique si le profil vendeur exact, épinglé par digest, possède des preuves candidat et déploiement actuelles
6. Admission à la demande — le compilateur n'expose un outil Agent personnalisé que si sa source SHA-256 vérifiée et son backend exact satisfont le minimum de sécurité
7. Exécution unique — le broker de confiance revérifie tenant, environnement, connexion, source, politique et révisions de binding, puis démarre une nouvelle microVM vendor_archive

Disponibilité des outils Agent

Pour un Agent isolé, un outil non-Scrydon n'est disponible que si toutes les conditions suivantes sont vraies :

• l'archive active possède une identité SHA-256 vérifiée et correspond toujours à la révision source compilée ;
• le Runtime Plane authentifié prend en charge le contrat vendor_archive ;
• les images runner, broker et enforcer sont épinglées par digest ;
• un substrat Kata/KVM planifiable est observé ;
• des preuves signées du candidat exact et du déploiement correspondent aux images, au profil et aux digests de preuve configurés ;
• l'egress de la requête réelle, la DLP sortante et l'audit sont prêts ; et
• le stockage chiffré des grants à usage unique est prêt.

Toute condition manquante produit une erreur typée avec remédiation. La plateforme ne dégrade jamais un outil Agent installé par une organisation vers un Worker Thread.

Politiques d'organisation

Les politiques d'organisation (configurées par les admins) régissent le comportement des intégrations personnalisées :

Politique d'exécution

{
  "maxConcurrentExecutions": 10,
  "maxTimeoutSeconds": 30,
  "allowedCapabilities": ["llm", "stt", "tools"]
}

Politique de gouvernance

{
  "allowedVendorScopes": ["scrydon", "platform"],
  "blockedVendorIds": []
}

• blockedVendorIds — identifiants vendeur bloqués à l'installation (appliqué lors de l'installation d'une extension)
• allowedCapabilities — types de capacités autorisés

Format du package

Chaque intégration personnalisée est conditionnée sous forme d'archive .tar.gz avec cette structure :

{extensionId}-{version}.archive.tar.gz
├── manifest.json           (métadonnées vendeur, JSON Schemas, définitions UI)
├── dist/
│   └── index.js            (ESM compilé, minifié ; toutes les dépendances intégrées)
├── meta/                   (généré automatiquement)
│   ├── sbom.cdx.json       (SBOM CycloneDX 1.6)
│   └── metafile.json       (graphe de dépendances esbuild)
└── assets/                 (optionnel)
    └── icon.svg, icon.png  (icônes vendeur/produit)

Génération du SBOM

Chaque artefact d'intégration personnalisée inclut automatiquement une nomenclature logicielle (SBOM) CycloneDX 1.6 dans meta/sbom.cdx.json. Le SBOM est généré lors de sdk-authoring extension build sans outils ni configuration supplémentaires.

Contenu du SBOM

Le SBOM liste chaque package NPM qu'esbuild a intégré dans dist/index.js :

• Nom et version du package — exactement ce qui est dans l'archive
• Licence — identifiant de licence SPDX depuis package.json
• URL du package (purl) — identifiant lisible par machine (pkg:npm/zod@3.24.0)
• Preuve — chemins de fichiers prouvant que le package est réellement intégré (le code élimé par tree-shaking est exclu)

Comment il est généré

Lors de sdk-authoring extension build, l'outil CLI :

1. Exécute esbuild avec metafile: true pour capturer tous les fichiers d'entrée
2. Extrait les packages NPM uniques depuis les chemins node_modules/ dans le metafichier
3. Lit le package.json de chaque package pour le nom, la version, la licence et la description
4. Sérialise tout en JSON CycloneDX 1.6
5. Écrit le résultat dans meta/sbom.cdx.json aux côtés du metafichier esbuild

Aucun outil ou dépendance externe n'est requis — la génération est intégrée dans l'outil CLI.

Utilisation par les admins

Après avoir installé une intégration personnalisée, l'onglet Version & sécurité de la fiche de l'extension affiche le nombre de composants SBOM et liste tous les packages détectés automatiquement aux côtés des dépendances déclarées. Consultez Révision d'une intégration personnalisée avant activation pour le workflow de révision complet.

Conformité

Le format CycloneDX est largement pris en charge par les outils de conformité. Pour les environnements nécessitant SPDX, convertissez avec :

cyclonedx-cli convert --input-file meta/sbom.cdx.json --output-file sbom.spdx.json --output-format spdxjson

Le graphe de dépendances esbuild brut est également disponible dans meta/metafile.json pour le débogage. Vous pouvez le visualiser sur esbuild.github.io/analyze.

Révision d'une intégration personnalisée avant activation

Après l'installation d'une intégration personnalisée, les administrateurs peuvent en examiner le contenu avant de l'activer pour l'organisation. La fiche de l'extension offre une expérience de révision structurée répartie en onglets.

Inclus

Affiche tous les produits, outils, déclencheurs et capacités d'exécution que fournit l'intégration personnalisée, chacun avec son interrupteur Activé · à l'échelle de l'organisation. Les capacités d'intelligence (LLM, STT, TTS, Embedding) affichent le nombre de modèles et prennent en charge la configuration de politiques en mode liste d'autorisation. Consultez Capacités pour plus de détails.

Version & sécurité — dépendances

Les informations de dépendances se trouvent dans Version & sécurité, en deux vues complémentaires de l'arborescence de dépendances de l'intégration personnalisée :

• Dépendances déclarées — entrées rédigées manuellement depuis defineToolkit({ dependencies: [...] }) qui incluent une reason lisible par l'homme pour chaque dépendance.
• Dépendances détectées automatiquement (SBOM) — l'ensemble complet des packages NPM qu'esbuild a intégrés dans dist/index.js, extrait depuis meta/sbom.cdx.json. Chaque entrée affiche le nom du package, la version, la licence et une URL de package lisible par machine (purl).

La section affiche le nombre total de composants SBOM afin que les administrateurs puissent évaluer rapidement l'empreinte de dépendances de l'intégration personnalisée. Les politiques de dépendances de l'organisation (niveaux de risque, listes de blocage, blocage des scripts post-installation) sont évaluées à la fois par rapport aux dépendances déclarées et détectées automatiquement.

Configuration

L'onglet Configuration affiche le paramétrage d'authentification du vendeur (OAuth, Clé API, Jeton Bot, ou Aucune) et permet aux administrateurs de renseigner les informations d'identification avant d'activer les capacités du vendeur.

Disposition du stockage

Première partie (intégré dans l'image Docker) :
  /app/archives/{extensionId}/dist/index.js

Extensions à portée plateforme :
  {platformPrefix}/extension-archives/{extensionId}/{version}/archive.tar.gz

Extensions à portée organisation :
  {storageKeyPrefix}/00_organization/extension-archives/{extensionId}/{version}/archive.tar.gz

Dépannage

L'installation échoue avec « Manifeste invalide »

Exécutez le validateur CLI localement avant de publier l'extension pour voir les erreurs détaillées :

bunx @scrydon/sdk-authoring extension test --level static

Problèmes courants :

• L'identifiant vendeur contient des majuscules ou des caractères spéciaux
• L'identifiant d'outil ne commence pas par le préfixe de l'identifiant vendeur
• Champs requis manquants (id, name, version, icon, auth)
• Le schéma Zod utilise des types non pris en charge (l'extracteur convertit Zod → JSON Schema)

Le statut de l'intégration personnalisée affiche « Échec »

Vérifiez le message d'erreur dans la boîte de dialogue de détail du vendeur (et les logs du serveur). Causes fréquentes :

• dist/index.js contient une erreur de syntaxe
• L'export par défaut n'est pas un résultat de defineExtension()
• Instruction export default manquante
• L'import à l'exécution échoue (assurez-vous que toutes les dépendances sont intégrées — esbuild devrait les inclure)

L'outil n'apparaît pas dans l'éditeur de workflows

1. Vérifiez que l'extension qui porte l'intégration est installé (Paramètres > Plateforme > Extensions > Installées) et que sa version est active
2. Vérifiez que le produit est activé pour votre organisation dans Paramètres > Plateforme > Extensions
3. Vérifiez la category du bloc — elle doit être "tools", "blocks" ou "triggers" pour apparaître dans la section correcte de la palette