Types d'actions

Un modèle d'action est ce qu'une tâche demande à quelqu'un (ou au système) de faire. Une tâche peut porter une ou plusieurs actions ; elles s'affichent côte à côte dans le panneau de détail de la tâche et se complètent indépendamment. Le choix du bon actionType est la décision d'authoring la plus structurante dans un Process Flow — il détermine ce que voit l'assigné, les données que la plateforme enregistre, et quelles portes et intégrations en aval se déclenchent. Quand une tâche ne porte qu'une seule action, le tableau kanban affiche directement la puce du type de cette action (icône + couleur) sur la carte de tâche — les tâches à action unique se lisent comme « la tâche est l'action » d'un seul coup d'œil.

Cette page approfondit le tableau récapitulatif de la vue d'ensemble des Process Flows — une section par type, avec un exemple prêt à copier-coller issu d'un pack réel dans les exemples du SDK, et une note en une ligne sur ce que voit concrètement l'assigné dans agentic.

Anatomie d'une action

Toutes les actions partagent la même enveloppe, quel que soit le type :

import { defineAction } from '@scrydon/sdk-authoring/process-flows'

defineAction({
  name: 'Approve rollout plan',                  // required, 1–200 chars
  description: 'Sign off on the customer rollout schedule.',
  actionType: 'approval',                        // required, see below
  isRequired: true,                              // required — drives gate completion
  executionMode: 'manual',                       // optional — see below
  dueOffsetDays: 5,                              // optional — relative due date
  metadata: { persona: 'champion' },             // optional — per-type config bag
  // workflowId / workflowSlug only used by actionType: 'workflow' — mutually exclusive
})

Les champs qui varient selon le type se trouvent tous dans metadata. Chaque section ci-dessous indique les clés de métadonnées que le runtime lit pour ce type spécifique.

executionMode

Un seul champ facultatif contrôle le moment où une action s'exécute :

Choisissez manual lorsqu'un humain est le principal. Choisissez automatic lorsque la plateforme doit piloter l'étape dès qu'elle le peut. Choisissez on_entry uniquement lorsque l'étape doit s'exécuter avant que l'étape soit interactable.

checklist

L'action la plus légère. L'assigné voit un seul bouton intitulé « Marquer comme terminé » et clique dessus quand c'est fait. Aucun artefact, aucune métadonnée capturée au-delà de l'événement de complétion lui-même.

Utiliser pour : confirmations, attestations, acquittements « J'ai fait X » où la piste d'audit a simplement besoin de l'acteur et du horodatage.

Champs de schéma utilisés : name, description, isRequired, executionMode, metadata.persona.

Exemple (du pack de détection multi-sources NATO — un opérateur confirme une alerte capteur) :

defineAction({
  name: 'Confirm UAV detection',
  description: 'Sensor operator confirms UAV radar reading and flags the track for fusion.',
  actionType: 'checklist',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'operator' },
})

Ce que voit l'assigné : une carte intitulée « Confirm UAV detection » avec un seul bouton principal. La complétion écrit une entrée de journal d'activité action_completed taguée avec l'identifiant de l'acteur.

document

Un artefact textuel long-forme que l'assigné doit produire. La plateforme ouvre un éditeur markdown à l'intérieur de la tâche ; la page résultante est stockée dans la base de connaissances de l'espace de travail de l'instance et indexée pour la récupération par les étapes IA en aval.

Utiliser pour : plans, résumés, comptes-rendus, ordres du jour, procès-verbaux — tout ce où le contenu est le livrable, pas un fichier.

Champs de schéma utilisés : name, description, isRequired, executionMode, metadata.persona, metadata.promoteToCorpus (facultatif — l'un de summary / minutes / decisions / action-items ; à la complétion de l'étape, le document est également publié dans le dossier instances/<instance>/canonical/ de la KB de l'instance sous ce slug, où les étapes de promotion KB en aval vont le chercher).

Exemple (du modèle AI Boardroom — le secrétaire rédige l'ordre du jour) :

defineAction({
  name: 'Create meeting agenda',
  actionType: 'document',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'secretary' },
})

Ce que voit l'assigné : une carte intitulée « Create meeting agenda » avec un bouton « Ouvrir l'éditeur ». La complétion est implicite — l'action est considérée terminée une fois la page sauvegardée avec du contenu non vide.

Où le document aboutit : pendant l'édition, le contenu réside dans l'action elle-même. Quand l'action est marquée terminée, la plateforme le convertit en Markdown et l'écrit comme une vraie page dans la base de connaissances de l'instance du process flow, sous instances/<instance>/documents/<stage>/ avec le nom de l'action comme titre de page. Compléter l'action à nouveau après des modifications met à jour la même page sur place. À partir de là, elle est interrogeable via la KB de l'instance et peut ancrer les étapes actionType: "workflow" ultérieures via metadata.retrieval. Les process flows créés avant l'existence des bases de connaissances d'instance en reçoivent une provisionnée automatiquement la première fois qu'un document, une transcription ou une page canonique y est écrit.

approval

Une porte de validation. Le persona assigné voit une paire de boutons Approuver / Rejeter. Approuver marque l'action comme terminée et débloque les tâches en aval ; rejeter signale la tâche et affiche un champ de motif.

Utiliser pour : validations de porte d'étape, décisions go/no-go, revues de gouvernance où une personne ayant l'autorité nommée doit attester du résultat.

Champs de schéma utilisés : name, description, isRequired, executionMode, metadata.persona, metadata.promoteToOrgKb (booléen — déclenche la condensation des apprentissages workspace-KB → org-KB ; valide uniquement sur approval).

Exemple (du modèle AI Boardroom — validation exécutive du résumé rédigé par l'IA) :

defineAction({
  name: 'Approve meeting summary',
  actionType: 'approval',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'executive' },
})

Ce que voit l'assigné : une carte avec les boutons Approuver et Rejeter. L'approbation écrit une entrée d'activité approval_granted ; le rejet écrit approval_rejected avec un motif optionnel et laisse la tâche ouverte.

workflow

Exécute un workflow Scrydon — soit un agent IA agentique, une séquence de blocs d'intégration, ou une porte human-in-the-loop. Le workflow s'exécute dans le moteur de workflow de la plateforme ; l'action se termine quand le workflow retourne.

Utiliser pour : étapes d'agent IA, intégrations automatisées, portes HITL nécessitant plus qu'un oui/non — tout ce qui nécessite une logique exécutable dans le cadre du flow.

Champs de schéma utilisés : name, description, isRequired, executionMode (souvent automatic), workflowId ou workflowSlug (mutuellement exclusifs), metadata.aiAgent, metadata.retrieval, metadata.outputSurface.

Il existe deux façons de référencer le workflow, et choisir entre elles est la décision d'authoring clé pour ce type :

Par workflowId — référencer un workflow existant

Utilisez ceci quand le workflow existe déjà dans le tenant. Deux cas courants : un agent @system/* fourni par la plateforme, ou un workflow que l'espace de travail a construit indépendamment.

Exemple (de l'étape de détection NATO — appel du détecteur multi-sources fourni par le système) :

defineAction({
  name: 'Run UAV radar detection',
  actionType: 'workflow',
  isRequired: true,
  executionMode: 'automatic',
  workflowId: '@system/agent-multi-source-detector',
  metadata: { persona: 'ai-platform', aiAgent: 'multi-source-detector' },
})

Le runtime traite les identifiants @system/* de manière spéciale — ils se résolvent toujours, quel que soit l'espace de travail dans lequel l'instance s'exécute.

Par workflowSlug — distribuer le workflow dans le même pack

Utilisez ceci quand le workflow est propre au process et que vous voulez qu'ils soient distribués comme une unité atomique. Créez le workflow aux côtés du process flow dans le même .scrydon-pack.tar.gz ; l'importateur matérialise d'abord le workflow, puis rebind chaque workflowSlug à l'identifiant matérialisé avant que le process flow atterrisse.

Exemple (du pack SAP Activate Brabant — une porte HITL distribuée avec le modèle) :

defineAction({
  name: 'Realize → Deploy Gate (HITL)',
  actionType: 'workflow',
  isRequired: true,
  executionMode: 'manual',
  workflowSlug: 'hitl-realize-gate',  // resolved at install time
})

workflowId et workflowSlug sont mutuellement exclusifs — le raffinement Zod rejette une action qui définit les deux. Voir Workflows pour le contrat de rebind de slug.

Ce que voit l'assigné : si executionMode est automatic ou on_entry, généralement rien — l'étape s'exécute en arrière-plan et affiche son résultat inline une fois terminée. Si manual, un bouton « Exécuter » apparaît ; cliquer dessus démarre le workflow et diffuse la progression dans la carte.

Où atterrit la sortie IA

Quand une action workflow exécute un agent @system/ et déclare un outputSurface, son résultat est sauvegardé à trois endroits :

1. L'action elle-même — verdict structuré (verdict, confidence, rationale, titres des apprentissages cités) plus une copie Markdown rendue.
2. La base de connaissances de l'instance — une page sous instances/<instance>/assessments/<stage>/, écrite automatiquement à la complétion. Cette page est la source de vérité : le bouton Voir la sortie sur l'action l'ouvre inline. Le niveau de confidentialité de la page est plafonné au niveau le plus élevé des sources qui l'ont informée, de sorte que les lecteurs en dessous de ce niveau voient un refus au lieu du contenu.
3. Une action d'approbation sœur (uniquement lorsque le flow déclare la surface de sortie approval) — une bannière consultative sur la porte de décision humaine.

Réexécuter l'action met à jour la même page sur place. Le panneau Détails d'exécution sur l'action affiche l'enveloppe d'exécution (identifiant du workflow, identifiant d'exécution, statut, horodatages) et les charges utiles stockées brutes pour le débogage.

entity_link

L'intention est d'attacher une tâche à une instance d'objet typé provenant de l'ontologie — de sorte que l'action devienne « remplir cet objet » plutôt que « produire un artefact libre ». Le type d'objet serait déclaré via task.ontologyContract.writes (ou le ontologyContract de l'action), et le runtime scaffolderait un éditeur pour les propriétés de ce type.

Champs de schéma utilisés : name, description, isRequired, executionMode, ontologyContract (déclaré au niveau de l'action ou de la tâche).

file_upload

L'assigné téléverse un ou plusieurs fichiers. Les octets transitent dans la base de connaissances de l'espace de travail de l'instance, sont hachés et stockés via @scrydon/storage, et sont immédiatement indexés — les rendant disponibles pour les étapes actionType: "workflow" en aval via metadata.retrieval.inputs[].fromTask.

Utiliser pour : importer des documents source (appels d'offres, contrats, packs de conseil d'administration, preuves d'audit) sur lesquels les étapes IA en aval doivent raisonner.

Champs de schéma utilisés : name, description, isRequired, executionMode, metadata.persona, et les contraintes de zone de dépôt optionnelles metadata.acceptedExtensions, metadata.acceptedMimeTypes, metadata.maxSizeMb.

Contraindre ce qui peut être téléversé. Une étape file_upload accepte toujours plusieurs fichiers ; vous ne pouvez pas désactiver la multiplicité. Ce que vous pouvez déclarer, c'est quels fichiers et quelle taille :

Les trois sont optionnels. Ne déclarez rien et l'étape revient aux valeurs par défaut de la plateforme : extensions .pdf .docx .xlsx .csv .pptx .txt .md, taille maximale 50 Mo. Déclarer acceptedExtensions ou acceptedMimeTypes remplace l'ensemble d'extensions par défaut, vous pouvez donc filtrer uniquement par MIME si vous préférez.

Ces limites sont appliquées à la fois dans le sélecteur (le filtre accept de la zone de dépôt et la vérification de taille) et côté serveur lors du téléversement — une requête qui contourne l'interface est toujours rejetée avec un 400. Les instances en cours existantes conservent les valeurs par défaut ; les contraintes prennent effet pour les flows instanciés après leur déclaration dans le modèle.

Exemple (du modèle AI Boardroom — le secrétaire téléverse le pack du conseil d'administration) :

defineAction({
  name: 'Upload board documents',
  actionType: 'file_upload',
  isRequired: true,
  executionMode: 'manual',
  metadata: {
    persona: 'secretary',
    // Optional — omit for the platform defaults (.pdf/.docx/.xlsx/.csv/.pptx/.txt/.md, 50 MB).
    acceptedExtensions: ['.pdf', '.docx', '.pptx'],
    acceptedMimeTypes: ['application/pdf'],
    maxSizeMb: 25,
  },
})

Ce que voit l'assigné : une carte avec zone de dépôt qui accepte plusieurs fichiers — sélectionnez-en plusieurs à la fois ou continuez à ajouter des fichiers au fil du temps (chaque téléversement s'ajoute à la liste des pièces jointes de l'étape ; les fichiers existants ne sont jamais remplacés). Le sélecteur ne propose que les types acceptés et rejette les fichiers dépassant la limite de taille. La complétion est explicite : dès qu'au moins un fichier est joint, l'assigné marque l'étape comme terminée (le bouton Marquer l'étape comme terminée sur la carte, ou la case à cocher de l'action dans la liste de contrôle de la tâche). Chaque fichier devient une page KB que les tâches en aval peuvent référencer par le slug de cette tâche.

distribution

Envoie un message aux détenteurs d'un ou plusieurs personas et suit l'acquittement. Utilisé pour diffuser un résultat, demander un acquittement avant un exercice sur table, ou boucler avec des parties prenantes qui ne pilotent pas activement le flow.

La livraison aujourd'hui passe par email via le mailer de la plateforme — aucune configuration d'intégration n'est requise. channel: "slack" et channel: "teams" sont acceptés dans le manifeste comme intention déclarée, mais la livraison pour ces canaux sera activée dans une version future ; en attendant, le panneau affiche le canal déclaré et désactive l'envoi pour les canaux non-email.

Utiliser pour : notifications, briefings, résumés poussés vers des canaux externes.

Champs de schéma utilisés : name, description, isRequired, executionMode, plus un bloc metadata plus riche :

Exemple (du pack de revue trimestrielle ISO — distribution du résumé prêt pour l'audit sur Slack avec une liste de destinataires) :

defineAction({
  name: 'Distribute report summary',
  actionType: 'distribution',
  isRequired: true,
  metadata: {
    persona: 'compliance-lead',
    channel: 'slack', // Declared intent — Slack delivery not yet active; email delivers today.
    recipientPersonas: ['compliance-lead', 'ciso', 'dpo', 'eng-owner'],
    completion: 'all-acknowledged',
  },
})

Ce que voit l'assigné : un panneau ciblé montrant le canal déclaré, le mode de complétion et la liste de destinataires résolue (les utilisateurs assignés à chaque persona destinataire par nom). Pour l'email, un formulaire de composition (sujet pré-rempli avec le nom de l'action, message modifiable) envoie à chaque destinataire un lien personnel suivi ; une fois envoyé, le panneau affiche le statut d'acquittement par destinataire et une ligne de progression « N sur M acquittés » pour les modes all-acknowledged / quorum. Les destinataires acquittent en ouvrant le lien suivi, qui les redirige également vers l'artefact lié.

voice_trigger

Capture de l'audio contre un chemin défini sur le modèle. L'enregistrement est automatiquement transcrit (STT passe par la capacité STT). Quand l'action se termine, la transcription est écrite comme une page dans la KB de l'instance du process flow sous instances/<instance>/transcripts/<stage>/, et l'audio brut est mis en file d'attente pour ingestion sous instances/<instance>/audio/<stage>/ — les deux prêts à ancrer les étapes en aval.

Utiliser pour : enregistrements de réunions, dictée, enrichissement vocal d'un flow qui est majoritairement silencieux le reste du temps.

Champs de schéma utilisés : name, description, isRequired, executionMode, metadata.persona, metadata.triggerPath (correspond à un path sur une entrée template.voiceTriggers[] de niveau supérieur).

Exemple (du modèle AI Boardroom — enregistrement de la réunion elle-même, couplé à un déclencheur vocal de niveau supérieur qui configure le STT et l'enrichissement en aval) :

// On the task action:
defineAction({
  name: 'Record meeting',
  actionType: 'voice_trigger',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'secretary', triggerPath: 'board-meeting' },
})

// On the top-level template:
defineVoiceTrigger({
  path: 'board-meeting',
  sttProvider: 'openai',
  language: 'en',
  enrichments: [
    { workflowId: '@system/agent-meeting-summarizer' },
  ],
})

Ce que voit l'assigné : une carte avec un bouton d'enregistrement. Enregistrement dans le navigateur ; à l'arrêt, l'audio se téléverse et le résultat STT se diffuse. Les workflows d'enrichissement sur le déclencheur vocal se déclenchent automatiquement une fois la transcription disponible.

Choisir le bon type

Un bref arbre de décision pour les auteurs incertains :

Si l'étape consiste à « remplir un objet typé », il n'existe pas encore de type d'action dédié — modélisez-la comme une action workflow qui appelle un agent ou un bloc d'intégration pour créer l'instance via l'API d'ontologie.

Pièges de validation courants

La commande pack validate exécute le schéma Zod et rejette les manifestes qui violent ces règles. Les plus fréquents :

Où aller ensuite