Livrer et gérer les extensions personnalisées

Portées des extensions personnalisées

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

Livraison via une source d'extension

Ce qui se passe lors de l'installation

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

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

Gérer les extensions 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 d'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 de l'extension. Tout s'y trouve, par onglets :

• Configuration — tant qu'il reste quelque chose à faire, vos étapes organisationnelles sous forme de liste de contrôle (« Compte Microsoft connecté — OAuth · 12 produits ») avec une jauge de progression, et les sections de connexion (instructions console, URL de redirection OAuth, accès à l'échelle de l'organisation) présentées à plat en dessous. Une fois que plus rien n'est dû, la liste de contrôle disparaît et l'onglet devient la vue d'ensemble de la connexion — l'état qu'elle aurait signalé figure déjà sur la ligne de l'extension dans la liste. Une extension qui n'a besoin d'aucun compte conserve une seule ligne qui l'indique.

• 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 est le terme de l'espace de travail et n'apparaît jamais ici. Chaque produit a sa ligne, quel que soit leur nombre ; l'en-tête de section annonce l'ampleur (« 142 outils dans 18 produits ») avant le début de la liste.

• Connexions — intitulé Connexions · N, une ligne par connexion avec cinq colonnes : Connexion, Environnement, Qui peut l'utiliser, Utilisée par et Statut (Prête une fois son identifiant fourni et son adresse admise). La ligne grise sous le nom d'une connexion indique comment elle s'authentifie (le compte au nom duquel elle agit, ou le type d'identifiant qu'elle détient), quels produits elle dessert lorsque ce ne sont pas tous (Outlook uniquement, 2 produits sur 5), et quand elle a été utilisée pour la dernière fois. À l'ajout ou à la modification d'une connexion, Produits desservis par cette connexion vaut Tous les produits ou Uniquement la sélection. Restreindre la liste affiche d'abord les sources de données rattachées aux produits retirés : elles s'arrêtent et demandent une autre connexion, et leurs tables et lignes sont conservées. Enregistrer et tester et Tester la connexion affichent leurs vérifications au-dessus du tableau, et non dans une boîte de dialogue, afin que vous puissiez passer directement à Qui peut l'utiliser de la nouvelle connexion.

  La colonne Qui peut l'utiliser de chaque connexion indique qui peut s'en servir — Tout le monde (tout le monde dans l'organisation), les équipes par leur nom (un nombre au-delà de deux), combien de personnes, ou Administrateurs uniquement. Sélectionnez-la pour ajouter une personne ou une équipe, en Retirer une (un seul clic), ou Autoriser tout le monde dans l'organisation : ils peuvent alors choisir la connexion dans Analytics en ajoutant une source de données. Chaque équipe indique combien de personnes elle compte (équipe · 6). Quand quelqu'un demande l'accès depuis Analytics, la notification ouvre ces connexions en proposant cette personne sous Qui peut l'utiliser de chaque connexion qui dessert l'environnement demandé — le panneau s'ouvre seul lorsqu'une seule convient — et Partager lui en donne l'usage. Rien n'est partagé avant que vous choisissiez Partager. Utiliser une connexion n'affiche jamais son identifiant. Les administrateurs de l'organisation peuvent toujours utiliser toutes les connexions, et eux seuls accordent ou retirent l'accès, et créent, modifient, testent, font tourner l'identifiant, changent les produits ou suppriment une connexion. Une nouvelle connexion n'est d'abord utilisable que par les administrateurs ; les connexions antérieures à l'accès par connexion restent utilisables par tout le monde dans votre organisation jusqu'à ce que vous retiriez cet accès. Espaces de travail… dans le menu de la ligne de la connexion définit quels espaces de travail peuvent l'utiliser ; l'accès des espaces de travail s'applique à tous les produits de la connexion. Chaque changement est inscrit au journal d'audit au nom de la personne qui l'a fait.

• Accès — les espaces de travail autorisés à utiliser le vendeur. Les espaces de travail autorisés sont listés par pages de 50, avec le total au-dessus de la liste ; Start fresh révoque toutes les autorisations, pas seulement celles de la page affichée.

• Utilisation — les workflows et bases de connaissances qui la référencent. Pour une extension de sources de données, les sources de données ajoutées depuis elle, chacune avec l'espace de travail et l'environnement qui l'exécutent et la date de son ajout ; une instance supplémentaire est désignée par sa source et le nom sous lequel elle a été ajoutée.

• Version & sécurité — présent pour chaque extension, et à lire de haut en bas. D'abord la Provenance : qui l'a publiée, si son code s'exécute dans le processus de la plateforme ou dans une microVM isolée (un bouclier de confiance signale le code tiers ; une extension publiée par Scrydon n'en porte aucun), et Peut joindre — les destinations que déclarent ses outils, et si la politique de sortie de votre organisation traite cette déclaration comme une autorisation. Ensuite les Mises à jour : la version installée et celle disponible, ce qui a changé, la politique de mise à jour, et les workflows qui l'utilisent. Une extension livrée avec la plateforme n'a pas de version distincte à vérifier ni de politique à définir ; cette moitié se lit donc en une seule ligne et la moitié provenance constitue l'onglet.

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).

Déprécier propose Appliquer les remplacements maintenant lorsqu'une autre extension activée fournit la même capacité. Pour un modèle de langage, chaque sélecteur de modèle des workflows de votre organisation qui désigne l'un des modèles de l'extension dépréciée — dans les workflows standard comme dans les workflows d'automatisation — est redirigé vers le modèle de remplacement choisi, et la valeur par défaut de la capacité suit. Seul un champ où vous choisissez un modèle de langage dans la liste est réécrit : un modèle saisi en texte (la vérification d'hallucination de Guardrails, la sortie analysée du bloc Web) garde sa valeur, tout comme un champ qui choisit un modèle d'image ou d'embedding ; vérifiez-les à la main. Les bases de connaissances conservent leur modèle d'embedding : le changer impose une réindexation, à faire depuis la base de connaissances. Les workflows de chaque produit sont réécrits en une seule étape : un échec laisse ceux de ce produit inchangés. Les valeurs par défaut ne changent qu'une fois tous les produits réussis, et la boîte de dialogue vous invite à relancer les autres.

L'onglet Connexions

Connexions, à côté d'Installées, liste toutes les connexions de votre organisation, toutes extensions confondues — extension, nom, environnement, qui peut l'utiliser, dernière utilisation et qui l'a activée — une page à la fois. Qui peut l'utiliser ouvre le même panneau que la fiche de l'extension, si bien que l'accès se modifie aussi ici ; ouvrez la fiche de l'extension pour modifier la connexion elle-même.

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 le modèle vers lequel elle se résout actuellement, marqué automatique (la plateforme classe ce qui est installé) ou épinglé. Le nom du modèle ne répète jamais le vendeur affiché à côté. Modifier ouvre le sélecteur sur place : Sélection automatique, ou un fournisseur/modèle précis, enregistré ligne par ligne. Une capacité dont le vendeur est présent mais qui ne résout aucun modèle affiche Aucun modèle résolu plutôt qu'un tiret. 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.

Chaque organisation démarre avec les embeddings locaux Scrydon activés. Ils exécutent le modèle all-MiniLM-L6-v2 à 384 dimensions dans API Platform, sans identifiants de fournisseur ni appel sortant à un modèle. La sélection automatique l'utilise lorsqu'aucun autre fournisseur d'embeddings activé n'est disponible. Vous pouvez l'épingler explicitement ou désactiver sa connexion dans les paramètres de l'extension Scrydon.

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é.

Désactiver la recherche web

La ligne Recherche web porte un interrupteur Désactiver la recherche web. C'est la seule capacité qu'une organisation peut couper entièrement, pour les déploiements où l'accès au web public relève de la conformité plutôt que de la configuration. L'interrupteur s'enregistre dès qu'on le bascule — il n'y a pas de bouton Enregistrer, car le refus est une politique d'organisation distincte et non une partie de la sélection de fournisseur de la ligne — et il s'affiche même si aucun vendeur de recherche web n'est installé, afin qu'une organisation puisse fixer et prouver un « off » explicite avant d'avoir acheté quoi que ce soit.

Tant qu'il est actif, la ligne indique off et n'affiche aucun sélecteur de fournisseur, et la plateforme refuse la recherche web aux deux points d'entrée :

• la capacité de recherche web (action.search.web) — utilisée par le chat, le bloc Search, le SDK des notebooks et les appels d'outils des agents — refuse ;
• un outil vendeur appartenant à une boîte à outils qui sert la recherche web (par exemple l'outil search de Google) refuse aussi, même lorsqu'un agent le nomme directement.

Le refus est volontairement le même que celui que voit un appelant quand rien n'est installé (CAPABILITY_NOT_CONFIGURED), pour que les fonctionnalités se dégradent au lieu de tomber en erreur. Les journaux et les enregistrements d'audit portent policyCode: CAPABILITY_DISABLED_BY_ORG_POLICY, afin qu'une décision de conformité ne soit jamais confondue avec une configuration cassée. Désactiver l'interrupteur ramène la ligne à Sélection automatique ; cela ne restaure pas un fournisseur épinglé auparavant.

Tout admin ou propriétaire de l'organisation peut le définir ; la tentative d'un membre est refusée. Il prend effet immédiatement sur la plateforme — il n'est pas mis en cache derrière une fenêtre de rafraîchissement.

Cortex cesse de proposer son outil de recherche web au modèle tant que la recherche web est désactivée, au tour de chat principal comme pour les sous-agents de recherche, de sorte que l'assistant répond à partir de la conversation, des bases de connaissances et des autres outils au lieu de planifier une recherche qu'il ne peut pas exécuter. Cortex revérifie dans la minute qui suit un changement ; pendant cet intervalle, la plateforme refuse toujours l'appel et l'assistant est informé que la recherche web est désactivée pour l'organisation.

La décision et son effet sont tous deux enregistrés dans le journal d'audit comme événements de gouvernance :

Une vérification de disponibilité (par exemple Cortex demandant s'il doit proposer l'outil) n'est pas un refus et n'écrit aucun événement.

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 Inclus 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 d'extension pour mettre à jour l'extension. 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 d'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 extensions 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 extension personnalisée est conditionnée sous forme d'archive .tar.gz avec cette structure :

{extensionId}-{version}.archive.tar.gz
├── manifest.json           (vendor metadata, JSON Schemas, UI definitions)
├── dist/
│   └── index.js            (compiled, minified ESM; all dependencies inlined)
├── meta/                   (automatically generated)
│   ├── sbom.cdx.json       (CycloneDX 1.6 SBOM)
│   └── metafile.json       (esbuild dependency graph)
└── assets/                 (optional)
    └── icon.svg, icon.png  (vendor/product icons)

Génération du SBOM

Chaque artefact d'extension 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 extension personnalisée, l'onglet Version & sécurité du panneau 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 extension 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 extension personnalisée avant activation

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

Inclus

Affiche tous les produits, outils, déclencheurs et capacités d'exécution que fournit l'extension 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'extension 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'extension 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

Affiche la configuration 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

First-party (baked into Docker image):
  /app/archives/{extensionId}/dist/index.js

Platform uploads:
  {platformPrefix}/extension-archives/{extensionId}/{version}/archive.tar.gz

Org uploads:
  {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'extension personnalisée affiche « Échec »

Vérifiez le message d'erreur dans le panneau de l'extension (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 archivées — esbuild devrait les intégrer)

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

1. Vérifiez que l'extension qui porte l'extension est installée (la ligne de l'extension dans 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

Le build échoue avec block_tools_not_manifest_safe

Un bloc de workflow installé ne dispose que de sa définition de manifeste compatible JSON ; le build refuse donc un bloc que la plateforme exécuterait mal (contrôle statique S19) :

• tools.config.tool ou tools.config.params est une fonction. Une fonction ne peut pas être écrite dans manifest.json ; la plateforme ne l'a donc jamais exécutée. Routez avec tools.toolSelector, envoyez un champ sous un autre nom d'entrée avec canonicalParamId, et déclarez des schémas input d'outil typés — la plateforme convertit elle-même le texte des champs en nombres, booléens, listes et objets.
• tools.access liste plusieurs outils et il n'y a pas de tools.toolSelector. Chaque exécution appellerait le premier outil, quelle que soit l'opération choisie. Associez chaque option du champ d'opération à son outil.

Voir « Des champs aux entrées de l'outil » dans la référence du SDK.