Process Flows

Un Process Flow est un workflow structuré et reproductible avec des étapes, des tâches et des personas — lancements de projets, audits, onboarding, revues de due-diligence. Vous le créez une fois comme Process Flow avec ce SDK et le distribuez dans un .scrydon-extension.tar.gz ; la plateforme l'instancie à chaque exécution comme un Process Flow.

Installation

bun add -d @scrydon/sdk-authoring zod

import {
  defineProcessFlow,
  defineStage,
  defineTask,
  defineAction,
  definePersona,
  defineVoiceTrigger,
} from '@scrydon/sdk-authoring/process-flows'

Anatomie d'un modèle

Un exemple complet

import {
  defineProcessFlow,
  defineStage,
  defineTask,
  defineAction,
  definePersona,
} from '@scrydon/sdk-authoring/process-flows'

export default defineProcessFlow({
  manifestVersion: 1,
  package: {
    id: 'acme.kickoff',
    name: 'Acme Customer Kickoff',
    version: '1.0.0',
  },
  template: {
    slug: 'acme-kickoff',
    name: 'Customer Kickoff',
    description: 'Standard onboarding flow for new enterprise customers',
    version: '1.0.0',
    defaultView: 'tracker',
    executionConfig: {
      stageFlow: 'sequential',
      taskFlow: 'parallel',
      allowRuntimeTaskCreation: true,
    },
    metadata: {
      icon: 'rocket',
      color: '#2563eb',
      tags: ['onboarding', 'sales'],
    },
    personas: [
      definePersona({ slug: 'csm', displayName: 'Customer Success Manager', cardinality: 'one' }),
      definePersona({ slug: 'champion', displayName: 'Customer Champion', cardinality: 'one' }),
      definePersona({ slug: 'system', displayName: 'System', cardinality: 'system' }),
    ],
    stages: [
      defineStage({
        slug: 'discovery',
        name: 'Discovery',
        transitionMode: 'manual',
        estimatedDuration: { value: 5, unit: 'days' },
      }),
      defineStage({
        slug: 'rollout',
        name: 'Rollout',
        transitionMode: 'approval',
      }),
    ],
    taskTemplates: [
      defineTask({
        slug: 'collect-stakeholders',
        stageSlug: 'discovery',
        name: 'Collect stakeholders',
        defaultAssignedRoleSlug: 'csm',
        actions: [
          defineAction({
            name: 'Stakeholder list',
            actionType: 'document',
            isRequired: true,
            metadata: { persona: 'csm' },
          }),
        ],
      }),
      defineTask({
        slug: 'kickoff-call',
        stageSlug: 'discovery',
        name: 'Kickoff call',
        dependsOnTaskSlugs: ['collect-stakeholders'],
        actions: [
          defineAction({
            name: 'Record kickoff call',
            actionType: 'voice_trigger',
            isRequired: true,
            metadata: { triggerPath: '/kickoff/' },
          }),
          defineAction({
            name: 'Capture summary to KB',
            actionType: 'workflow',
            isRequired: false,
            workflowId: 'system.summarize-meeting',
            metadata: { promoteToCorpus: 'summary' },
          }),
        ],
      }),
      defineTask({
        slug: 'rollout-plan',
        stageSlug: 'rollout',
        name: 'Approve rollout plan',
        dependsOnTaskSlugs: ['kickoff-call'],
        actions: [
          defineAction({
            name: 'Approve plan',
            actionType: 'approval',
            isRequired: true,
            metadata: { persona: 'champion' },
          }),
        ],
      }),
    ],
    voiceTriggers: [],
  },
})

Types d'actions

Voir Types d'actions pour une analyse approfondie par type avec des exemples prêts à copier-coller, des notes sur l'UX à l'exécution, et les champs de métadonnées que chaque type lit.

Ancrer une étape IA dans les documents de l’espace de travail (metadata.retrieval)

La direction inverse : une action workflow qui exécute un agent — un agent intégré @system/* ou un workflow de extension/canvas (inline ou frère) — peut être ancrée dans un ou plusieurs documents téléversés plus tôt dans le flow, de sorte que l’agent raisonne sur des entrées réelles plutôt que sur le nom de la tâche seul. Déclarez-le avec metadata.retrieval sur l'action :

defineAction({
  name: "AI Qualification Assessment",
  actionType: "workflow",
  isRequired: false,
  executionMode: "automatic",          // run when the stage is entered
  workflowId: "@system/agent-project-qualifier",
  metadata: {
    aiAgent: "project-qualifier",
    // Where the agent result lands, by target ACTION TYPE (see below):
    // an assessment on this workflow step itself, and an advisory banner
    // on the flow's human approval action.
    outputSurface: [
      {
        kind: "workflow",
        contentType: "project_qualification_assessment",
        pageTitle: "AI Qualification Assessment",
      },
      {
        kind: "approval",
        targetTaskSlug: "go-no-go-decision",
        advisorySource: "ai-qualification",
      },
    ],
    retrieval: {
      // The document(s) the agent must judge. `fromTask` is the slug of an
      // earlier task: its completed document action's page, its file_upload
      // action's ingested documents, and/or its workflow (agent) action's
      // assessment page are resolved as stable, source-level entries.
      inputs: [{ fromTask: "upload-source", mode: "full" }],
      // Maximum optionnel par source. Le budget exact du bloc rendu partagé
      // peut attribuer moins après comptage des titres, états et marqueurs.
      // Valeur omise → full : 24 000 ; summary : 4 000.
      inputDocMaxChars: 60_000,
    },
  },
})

Le panneau Invite & Contexte affiche une ligne pour chaque source connue et stable, y compris les documents homonymes. Il distingue les sources représentées, omises faute de capacité, illisibles et livrées par extrait après échec du résumé ; seules les sources dont du contenu a été livré contribuent aux références de sortie. La préparation est limitée à 500 sources inventoriées, 1 Mo par corps chargé, 8 Mo pour l'ensemble des entrées déclarées, 24 appels de résumé avec une concurrence de 6 et 60 secondes. Si l'inventaire autorisé ne peut pas être achevé dans sa limite de sources ou de temps, la préparation s'arrête avec une erreur générique avant l'exécution du modèle agent. Une fois l'inventaire achevé, l'expiration du délai de résumé utilise le repli local et clairement marqué décrit ci-dessus.

Aujourd'hui workflow (évaluation sur l'étape) et approval (conseil sur une action d'approbation cible) sont les surfaces de sortie implémentées. La spécification retrieval elle-même est générique et fonctionne pour toute étape workflow portant un agent nécessitant un ancrage — les agents intégrés @system/* reçoivent automatiquement le contexte assemblé comme message utilisateur, tandis que les workflows de extension/canvas doivent en plus référencer <start.processFlowContext> dans un bloc pour le recevoir (voir Recevoir le contexte du process flow — sans cette référence, le contexte assemblé est perdu).

Une base de connaissances pour chaque exécution (knowledge.scope)

Par défaut, chaque exécution d'un process flow obtient sa propre base de connaissances. Définissez knowledge.scope: "template" et chaque exécution de ce flow dans un environnement d'espace de travail écrit alors dans une seule base de connaissances partagée :

template: {
  // …
  knowledge: { scope: "template" },
}

• La base partagée est créée lors de la première exécution du flow dans un environnement et apparaît dans la liste des bases de connaissances de l'espace de travail, avec le badge Process flow.
• Chaque exécution possède un dossier, instances/<date>-<nom de l'exécution>-<id>/, qui contient ses téléversements, documents, transcriptions et résumé de clôture. Les étapes IA lisent le dossier de leur propre exécution ainsi que tout ce qui se trouve en dehors de instances/ — le matériel de référence téléversé à la racine de la base par les membres est donc disponible pour toutes les exécutions.
• Les exécutions précédentes déjà terminées servent d'ancrage aux exécutions suivantes via leurs propres dossiers.
• Supprimer une exécution ne supprime que son dossier ; supprimer la base depuis la page de connaissances est autorisé et l'exécution suivante en provisionne une nouvelle.
• Les exécutions démarrées avant que le flow ne déclare template conservent leur propre base.

scope: "instance" (la valeur par défaut) conserve le comportement actuel.

Reprendre les exécutions précédentes (knowledge.priorCycles)

Une nouvelle exécution peut s'appuyer sur ce que les exécutions précédentes du même flow ont décidé. Par défaut, elle reprend les cinq exécutions terminées les plus récentes du même environnement d'espace de travail :

• ses étapes IA reçoivent les extraits pertinents de ces exécutions, et
• les conversations partagées de ses étapes reçoivent le résumé de clôture de chaque exécution et peuvent rechercher dans leurs pages ; une question comme « qu'avons-nous décidé la dernière fois ? » reçoit une réponse fondée sur ces exécutions, qui les cite.

Définissez le nombre par flow :

template: {
  // …
  knowledge: {
    scope: "template",
    priorCycles: { maxCycles: 3 },
  },
}

• maxCycles est un entier de 0 à 10 ; 0 désactive la reprise.
• Omettez priorCycles pour suivre la valeur par défaut de la plateforme (actuellement 5).
• La valeur est figée dans chaque exécution à son démarrage : publier une nouvelle version de l'extension ne modifie pas une exécution en cours.
• Une étape IA peut toujours la remplacer avec metadata.priorCycles.maxCycles, ou s'en exclure avec excludeContext: ["priorCycles"].
• Fonctionne avec les deux valeurs de scope. Les exécutions en cours, les exécutions annulées et les pages classifiées au-dessus de l'habilitation du lecteur ne sont jamais reprises.

Validation du DAG de tâches

Les tâches peuvent déclarer :

• dependsOnTaskSlugs — d'autres tâches qui doivent d'abord se terminer
• unlockAfterTaskSlug + unlockDelay — une porte douce qui s'ouvre N jours/semaines après la fin d'un prédécesseur

Le CLI inspect exécute la détection de cycle DFS (BLANC/GRIS/NOIR) et échoue fermement sur tout cycle. Codes d'erreur stables :

Construire, inspecter, téléverser

bunx @scrydon/sdk-authoring extension validate src/extension.ts

bunx @scrydon/sdk-authoring extension build src/extension.ts --outDir dist
# → dist/<package.id>-<package.version>.scrydon-extension.tar.gz

bunx @scrydon/sdk-authoring extension inspect dist/acme-kickoff-1.0.0.scrydon-extension.tar.gz

curl -X POST "$AGENTIC_URL/api/extensions/import?organizationId=$ORG_ID&workspaceEnvironmentId=$ENV_ID" \
  -H "Cookie: $SESSION_COOKIE" \
  -F "file=@dist/acme-kickoff-1.0.0.scrydon-extension.tar.gz"

Structure de l'extension

<extension>.scrydon-extension.tar.gz
├── extension.json                          # top-level extension manifest (ExtensionArchiveManifestSchema)
├── ontology/
│   └── manifest.json                  # OntologyManifestSchema — may be empty for flow-only extensions
├── workflow-<slug>/                   # optional — zero or more workflow subdirs
│   └── manifest.json                  # WorkflowManifestSchema
└── process-flow/
    ├── manifest.json                  # ProcessFlowManifestSchema
    ├── assets/                        # optional — JSON / image assets referenced by the flow
    │   ├── icon.svg
    │   └── preview.png
    └── meta/                          # optional — non-functional metadata (e.g. sbom.cdx.json)

Chaque sous-répertoire fait l'aller-retour comme un artefact autonome valide. Extensions d'assets autorisées : .json, .svg, .png, .jpg, .jpeg, .gif, .md. Les liens symboliques, liens durs, chemins absolus et traversées de chemin (..) sont rejetés par l'inspecteur.

Quand une extension contient des workflows, l'importateur les exécute dans leur propre phase avant l'installation du process-flow — de cette façon, chaque workflowSlug sur un modèle d'action se résout en un workflowId matérialisé avant que le process flow atterrisse dans la base de données. Voir Workflows pour le contrat de rebind de slug.

Limites de sécurité

L'inspecteur runtime lit l'archive en mode streaming (analyseur tar.list uniquement — n'extrait jamais sur disque) et applique des limites strictes :

La route /import retourne 413 pour les violations de taille et 400 pour les violations de structure ou de graphe.

Pourquoi pas de code exécutable

Les process flows sont déclaratifs. La logique personnalisée est référencée — par workflowId (un workflow déjà présent dans le tenant) ou par workflowSlug (un workflow distribué avec le modèle dans le même Extension) — pas bundlée. Même quand un Extension distribue des workflows dans des sous-répertoires workflow-<slug>/, la représentation sur disque est du JSON pur ; le catalogue de blocs runtime réside dans la plateforme. Cela rend la surface déterministe, reproductible et téléversable par des auteurs non-ingénieurs.

Où aller ensuite