Créer un Flow
Décrire un travail durable avec ses étapes, ses décisions et son résultat.
Partir du résultat attendu
Un Flow organise le travail nécessaire pour produire un résultat. Préparer une soumission reçoit un client et un besoin, construit une proposition, demande une revue et conserve la version approuvée. Le Flow ne se réduit pas à une suite de messages AI.
Dans le Studio, nommez le Flow, déclarez ses entrées et ajoutez les étapes. Reliez-les selon leurs dépendances. Les outils d’auteur et l’AI utilisent les mêmes définitions; le moteur Surface conserve l’exécution, les attentes et les décisions.
| Élément | Valeurs attendues | Description |
|---|---|---|
| Entrées | Fields ou paramètres typés | Informations nécessaires au lancement |
| Étapes | Travail humain, AI ou opération admise | Unités d’exécution et de suivi |
| Dépendances | Clés d’étapes existantes, sans cycle | Ordre et parallélisme possibles |
| Résultat | Surface ou livrable déclaré | Ce que le Flow doit produire |
| Approbation | Décision et responsable autorisé | Point de contrôle humain |
| Reprise | Politique d’erreur et d’attente | Continuité après interruption |
Exemple : préparer une soumission
Entrées : client et besoin
1. Qualifier → relever les informations manquantes
2. Préparer → rédiger à partir des tarifs et de la procédure
3. Revoir → demander la décision du responsable
4. Finaliser → conserver la soumission approuvée
Résultat : fiche Soumission reliée au ClientLancer depuis une Action
L’Action Préparer une proposition recueille le besoin et le client. La confirmation démarre le Flow et ouvre son suivi. Le client déjà ouvert peut fournir le contexte initial; les entrées requises restent vérifiées avant lancement.
Avant de confirmer, examinez le Flow proposé sous forme de cartes et de graphe. Les éléments à créer à la confirmation sont distingués des étapes prévues par le modèle : un parcours possible n’est pas encore un travail lancé. Vérifiez les dépendances et les choix proposés, puis revenez aux entrées si vous souhaitez les modifier. Si le graphe ne peut pas être affiché, rouvrez la revue plutôt que confirmer sans cette vue d’ensemble.
Si le lancement est confirmé mais que le suivi ne peut pas être ouvert, réessayez d’ouvrir le suivi. Ne relancez pas l’Action pour résoudre ce problème de lecture.
Suivre une exécution
Les intégrations AI et clientes utilisent surface_flow_instance_read pour une exécution exacte,
surface_flow_execution_discover pour l’ouvrir depuis son Work et
surface_flow_signal_references pour les choix de signal autorisés. Ces mêmes interfaces couvrent
attentes typées, délais, signaux, échecs et annulation. Examinez avec
surface_flow_transition_prepare, puis confirmez cette intention exacte avec
surface_flow_transition_apply; une lecture ou une découverte n’est pas une confirmation et
n’accorde aucun droit d’exécution.
Une étape Work sélectionnée doit appartenir à son origine déclarée : la Query d’étapes authored ou une occurrence réelle dans le scope de son Flow. Recherche et pagination changent seulement l’affichage; elles n’accordent ni ne retirent le droit de sélectionner une étape. La reprise relit cette sélection exacte nativement avant de rouvrir ses capacités, sans traiter une ligne visible ou un descendant comme une preuve.
Dans Actions requises, retrouvez les demandes d’approbation ou de réponse qui vous concernent. Le nombre indique les éléments affichés, pas un total présumé d’une liste encore en cours de chargement. Utilisez Afficher la suite pour continuer ou Actualiser après un échec de lecture. Ouvrir une demande retrouve son suivi et sa revue : cela ne confirme pas la décision à votre place.
Ouvrez le Flow depuis son travail pour retrouver son état courant, ses étapes et son historique. Vous n’avez pas à retrouver un identifiant technique d’exécution. Les étapes et l’historique indiquent séparément le nombre d’éléments chargés et proposent leur propre continuation; une page partielle n’est pas l’exécution complète.
Les dates de l’historique indiquent quand les changements ont été enregistrés. Elles ne prétendent pas mesurer la durée du travail d’un service externe. Les entrées et sorties restent auprès de leurs sources et résultats autorisés, sans être recopiées dans les messages de progression.
Utilisez les actions proposées pour l’exécution courante. L’échec d’une étape n’autorise pas automatiquement une nouvelle tentative métier. Choisissez explicitement une décision d’approbation ou des branches, puis examinez et confirmez l’intervention proposée. Si la réponse de confirmation est perdue, reprenez cette même confirmation au lieu de créer une autre exécution. La progression live ne confirme pas qu’une intervention a été enregistrée.
Les cartes de conversation ouvrent le même suivi, dans l’application qui a produit la carte. Une carte de confirmation reprend la revue de l’intervention; une carte de résultat retrouve l’état enregistré sans répéter l’action. Le suivi ne remplace pas l’éditeur de vos contenus et n’ouvre pas le document technique de l’exécution.
Quand vous posez une question sur ce Flow, Surface transmet ses instructions de fonctionnement et les versions consultées. Après une évolution de l’application, les instructions actuelles et celles retenues par l’exécution restent distinctes : ouvrir un autre Workspace ne remplace pas la cible de votre question. Si l’état du Flow ou vos accès ont changé, actualisez son suivi avant de poursuivre; Surface ne lui substitue pas un autre guide.
Pour une étape différée, le suivi indique sa date de reprise enregistrée. Une demande d’arrêt reste distincte d’une annulation confirmée tant que l’arrêt de certains travaux reste à confirmer. Les détails d’échec distinguent une approbation refusée, une attente expirée et un résultat externe incertain; aucun de ces états ne donne à lui seul un droit de réessayer. Le formulaire de signal demande seulement les valeurs déclarées et votre décision, pas un identifiant technique d’événement. Surface conserve cette identité avec votre confirmation afin qu’une réponse perdue ne provoque pas l’envoi d’un second signal.
Lorsqu’un signal demande une fiche ou un Result, choisissez-le dans la liste définie par l’application. Recherche et pages conservent le périmètre de cette sélection. Surface revérifie la version choisie avant de l’utiliser; un Result conserve aussi la provenance de sa vraie Task et de son action. Si la source ou votre accès a changé, actualisez le choix plutôt que saisir un identifiant ou le remplacer par une autre fiche.
Quand une attente demande une référence, choisissez-la parmi les contenus autorisés proposés par Surface. La recherche et les pages suivantes restent liées à cette attente. Une sélection n’envoie pas le signal : vos autres valeurs restent dans le formulaire jusqu’à votre revue et confirmation.
Utiliser le contexte opérationnel de la Task sélectionnée
Lorsque vous interrogez l’AI sur une Task de Flow, conservez cette Task comme cible exacte. Si son Model déclare plusieurs Actions opérationnelles, choisissez celle qui convient avant de charger ses instructions. La découverte présente les choix disponibles ; elle n’exécute pas la Task, ne lit pas ses preuves et n’approuve pas son résultat.
Surface sépare les références capturées d’origine du Flow des instructions et des permissions de l’application courante. Un contexte d’origine manquant est signalé explicitement, jamais remplacé par le contexte d’une autre Task ou un autre guide. Le guide Travailler avec l’AI précise les lectures MCP de découverte et d’instructions.
Définition et exécution
La définition du Flow est réutilisable. Chaque lancement possède ses entrées, ses étapes et son résultat. Changer la définition ne réécrit pas silencieusement une exécution en cours. Les règles de version, migration et reprise conservent la traçabilité du travail.
Continuez avec les étapes, les attentes et les résultats.
Exemples appliqués : Préparer une soumission
Le Flow déclare les entrées Client et Besoin, une étape exécutable et un budget borné.
Configuration
Fragment à placer dans flowBlueprints[].composition. Propriétés et valeurs admises.
{
"contract": "FlowComposition@1",
"rootWorkNodeKey": "prepare-quote",
"stateSurfaceDefinitionPath": "workspace/work/surface/preparation",
"subflowLinkTypePath": null,
"entryStepKey": "prepare",
"inputs": [
{
"key": "client",
"type": "surface-reference",
"provenance": "caller",
"minimum": 1,
"maximum": 1
},
{
"key": "need",
"type": "text",
"provenance": "caller",
"minimum": 1,
"maximum": 1
}
],
"contexts": [],
"outputs": [],
"steps": [
{
"key": "prepare",
"kind": "task",
"workNodeKey": "prepare",
"actionKey": "prepare",
"inputs": {},
"outputs": [
{
"key": "proposal",
"type": "result-reference",
"provenance": "canonical",
"minimum": 1,
"maximum": 1,
"result": "reference"
}
],
"reservedCostUnits": 1,
"maximumAttempts": 1
}
],
"budgets": {
"maximumDepth": 2,
"maximumOccurrences": 20,
"maximumConcurrency": 2,
"maximumIterations": 3,
"maximumDurationMilliseconds": 86400000,
"maximumCostUnits": 100,
"maximumStateBytes": 32000
}
}Variante et raccordement
Fragment à placer dans flowBlueprints[].composition.inputs. Propriétés et valeurs admises.
[
{
"key": "client",
"type": "surface-reference",
"provenance": "caller",
"minimum": 1,
"maximum": 1
},
{
"key": "need",
"type": "text",
"provenance": "caller",
"minimum": 1,
"maximum": 1
}
]Exemple de disposition UI
La disposition illustrative ci-dessous situe cette configuration dans l’app Clients/Soumissions. Chaque fragment s’insère à l’emplacement indiqué; ses références aux Fields, Queries et Actions correspondent aux déclarations du Model.
- Qualifier le besoin
- Préparer la proposition
- Attendre la décision
- Conserver le résultat
La proposition et ses sources restent accessibles pendant l’attente.