Téléverser et gérer les intégrations personnalisées

Portées des intégrations personnalisées

Les intégrations personnalisées existent à trois portées, toutes exécutées via le même chemin d'exécution en bac à sable :

Téléversement via l'interface Paramètres

Téléversement via l'API

Utilisez une requête POST avec des données de formulaire multipart :

curl -X POST https://your-instance.example.com/api/bundle-upload \
  -F "bundle=@dist/my-vendor-1.0.0.bundle.tar.gz" \
  -b "better-auth.session_token=<your-session-token>"

Réponse

{
  "vendorId": "my-vendor",
  "version": "1.0.0",
  "toolCount": 3,
  "productCount": 1
}

Réponses d'erreur

Ce qui se passe lors du téléversement

Le pipeline de téléversement effectue ces étapes :

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

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

Statuts

Activer / Désactiver

Basculez le statut d'une intégration personnalisée depuis l'onglet Personnalisé. La désactivation d'une intégration personnalisée la supprime de l'éditeur de workflows mais ne supprime pas les fichiers stockés.

Supprimer

La suppression d'une intégration personnalisée supprime l'enregistrement en base de données. Le blob stocké peut être nettoyé séparément.

Gestion des versions

Téléversez une nouvelle version du même vendeur pour le mettre à jour. La plateforme stocke les intégrations personnalisées par {vendorId}/{version}/, de sorte que plusieurs versions peuvent coexister. La version active la plus récemment téléversée est celle utilisée à l'exécution.

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"],
  "allowOrgUploads": true,
  "requireApprovalForUploads": false,
  "blockedVendorIds": []
}

• allowOrgUploads — indique si les admins de l'organisation peuvent téléverser des intégrations personnalisées
• requireApprovalForUploads — indique si les téléversements nécessitent l'approbation d'un admin de plateforme
• blockedVendorIds — identifiants vendeur explicitement bloqués
• 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 téléversé 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 le téléversement 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

Téléversements de plateforme :
  {platformPrefix}/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Téléversements d'organisation :
  {storageKeyPrefix}/00_organization/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Dépannage

Le téléversement échoue avec « Manifeste invalide »

Exécutez le validateur CLI localement 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 le tableau des intégrations personnalisées. 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 statut de l'intégration personnalisée est Actif dans Paramètres > Plateforme > Intégrations > Personnalisé
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