Nodes, tools et événements
Une contribution est une interface publique maintenue. Ne créez pas de symétrie artificielle entre nodes, tools et APIs : chaque surface optimise un mode d’utilisation différent.
Nodes de processus
Un node est conçu pour être composé dans un graphe : paramètres et outputs typés, bindings explicites, routes et garanties visibles par l’auteur du processus.
Ajoutez un node lorsqu’un cas d’usage métier durable justifie cette surface. La simple existence d’un endpoint fournisseur ou d’une opération CRUD n’est pas une justification suffisante.
Agent tools
Un Tool est conçu pour être sélectionné et invoqué par un Agent. Son intention, ses arguments et son résultat doivent être adaptés à cette interaction plutôt que copiés depuis un node.
Le catalogue de tools est volontairement curaté : une opération peut exister comme node ou API sans qu’un Tool équivalent soit souhaitable.
Événements
Un événement d’extension expose à Ormuz une occurrence significative du système partenaire. Son identifiant et ses inputs typés doivent rester stables et décrire ce qui s’est produit, pas le traitement interne effectué pour l’ingérer.
- préférez un événement métier précis à un webhook générique difficile à exploiter ;
- exposez les objets plateforme uniquement lorsque leur résolution est fiable et légitime ;
- conservez un objet externe lorsque le fait appartient au système partenaire ;
- ne faites pas d’un événement entrant une mutation cachée d’un objet plateforme.
Actions de parcours utilisateur
Une action de parcours utilisateur est une contribution navigateur destinée au participant : composant embedded, interaction provider ou redirection avec reprise. Elle doit être namespacée par l’extension et respecter le lifecycle strict de l’action courante.
Cette surface n’est pas un node supplémentaire : le node définit l’opération de processus, tandis que l’action fournit l’expérience participant-facing associée lorsque cette opération attend une interaction.
Process templates
Un process template est un artefact marketplace distinct qui fournit un processus prêt à personnaliser et déclare les extensions dont il dépend. Il n’est pas un champ workflows sous spec.contributes dans le manifeste d’extension.
Associez un template à une extension via ses requirements.extensions et, lorsque l’installation doit sélectionner une configuration, via ses requirements.configuration_slots. Le template reste versionné et installable comme un artefact propre : l’extension fournit les capacités, le template montre une composition réutilisable.
Choisir la bonne contribution
| Besoin | Surface adaptée |
|---|---|
| L’auteur d’un processus doit composer explicitement une opération avec d’autres étapes. | Node |
| Un Agent doit disposer d’une capacité bornée et sélectionnable. | Tool |
| Le système externe annonce qu’un fait s’est produit. | Événement |
| Le participant doit interagir avec une UI ou une redirection fournie par l’extension. | Action de parcours utilisateur |
| Une composition réutilisable doit être distribuée comme processus prêt à personnaliser. | Process template, artefact marketplace distinct de l’extension. |
| Le besoin est simplement de lire ou écrire via un contrat machine public. | API, sans créer automatiquement un node ou un Tool. |