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 pack

Ce qui se passe lors de l'installation

Lorsqu'un pack contenant une entrée integration est installé, la plateforme exécute le même pipeline de bundle qu'auparavant :

00_organization/integration-bundles/{vendorId}/{version}/bundle.tar.gz

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

Statuts

Activer / Désactiver

Activez ou désactivez les produits d'une intégration personnalisée depuis la boîte de dialogue de détail du vendeur sous Paramètres > Plateforme > Intégrations. La désactivation la supprime de l'éditeur de workflows mais ne supprime pas les fichiers stockés.

Gestion des versions

Publiez une nouvelle version de pack pour mettre à jour l'intégration. La plateforme stocke chaque version par {vendorId}/{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 packs).

Séquence de démarrage

Au démarrage de la plateforme :

1. Analyse des bundles première partie — analyse manifest.json depuis /app/bundles/ (image Docker)
2. Analyse des bundles de plateforme — analyse les manifestes depuis le stockage de la plateforme
3. Analyse des bundles 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. Enregistrement du type SandboxActor auprès du runtime Dapr
6. Prêt à servir — les acteurs s'activent à la demande (première exécution d'outil)

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'un pack)
• 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 :

{vendorId}-{version}.bundle.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 integrations 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 le bundle
• 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 integrations 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 Dépendances dans la boîte de dialogue de détail du vendeur affiche le nombre de composants SBOM dans l'en-tête de l'onglet 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 boîte de dialogue de détail du vendeur offre une expérience de révision structurée répartie en plusieurs onglets.

Onglet Capacités

Affiche tous les produits, outils, déclencheurs et capacités d'exécution que fournit l'intégration personnalisée. Les administrateurs peuvent activer ou désactiver des blocs individuels depuis cet onglet. 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.

Onglet Dépendances

L'onglet Dépendances affiche 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 defineProduct({ 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).

L'en-tête de l'onglet 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.

Onglet Configuration

Affiche la configuration d'authentification du vendeur (OAuth, Clé API, Jeton Bot, ou Aucune) et permet aux administrateurs de configurer 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/bundles/{vendorId}/dist/index.js

Packs à portée plateforme :
  {platformPrefix}/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Packs à portée organisation :
  {storageKeyPrefix}/00_organization/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Dépannage

L'installation échoue avec « Manifeste invalide »

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

bunx @scrydon/sdk-authoring integrations 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 defineVendor()
• 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 le pack qui porte l'intégration est installé (Paramètres > Plateforme > Packs) et que sa version est active
2. Vérifiez que le produit est activé pour votre organisation dans Paramètres > Plateforme > Intégrations
3. Vérifiez la category du bloc — elle doit être "tools", "blocks" ou "triggers" pour apparaître dans la section correcte de la palette