Voir aussi : Guide ProcessTypes · Retour à l'index
Blueprint — Ajout d'un type d'orchestration dans Orkeon
Ce document est une check-list reproductible pour ajouter un septième ProcessType au framework et le documenter. Il suit le chemin qu'ont pris les six modes existants — le mode Graph (un moteur Domain + un bloc YAML) et le mode Autonomous (un point d'entrée IProcessStrategy dédié) sont les deux précédents de référence — et couvre les 8 étapes, du value object Domain jusqu'à la documentation.
Un enregistrement oublié échoue bruyamment plutôt qu'en silence : ProcessType.From, le parser YAML et l'adaptateur de scripting refusent un nom inconnu, et ProcessStrategyFactory comme SequentialCrewOrchestrator lèvent NotSupportedException pour un mode qu'ils n'aiguillent pas.
Prérequis
Avant de commencer, décidez :
- Nom du mode : la valeur de
ProcessType(PascalCase, par ex.Swarm) et son écriture YAML/scripting (swarm: le YAML est comparé sans tenir compte de la casse, leprocess()du builder de scripting n'accepte que le nom en minuscules) - Point d'entrée : réutiliser
IProcessStrategy.ExecuteSequentialAsync(crew, inputVariables, ct)(Graph, Consensual) ou ajouter une méthode dédiée (Autonomous, qui a besoin d'unAgentExecutionBudget) - Configuration : aucune, une section d'options .NET (Consensual :
Orkeon:Consensus), ou un bloc YAML de niveau crew (Graph :graph:) - Moteur : si le mode a besoin d'un moteur Domain réutilisable (
StateGraph<TState>,StateMachine<TState, TEvent>) ou vit entièrement dans sa stratégie - Stabilité : si la surface publique est livrée sous un diagnostic
[Experimental](Autonomous :ORKEXP002, voir les API expérimentales)
Étape 1 — Domain : déclarer le mode
Fichier : src/core/Orkeon.Domain/SharedKernel/ValueObjects/ProcessType.cs
/// <summary>Les agents essaiment sur le pool de tâches sous un budget partagé.</summary>
public static readonly ProcessType Swarm = new("Swarm");
private static readonly Dictionary<string, ProcessType> s_all = new(StringComparer.OrdinalIgnoreCase)
{ /* … les six entrées existantes …, */ [nameof(Swarm)] = Swarm };
ProcessType.All, From et TryFrom lisent s_all : une fois l'entrée ajoutée, le YAML (YamlCrewMapper.ParseProcessType) et l'adaptateur de scripting (JsCrewConfigurationAdapter) acceptent la nouvelle valeur sans autre changement, et leurs messages d'erreur la listent.
Prédicats par mode. Décidez la réponse du mode à chacun, car ils retombent sur une valeur par défaut pour un mode qu'ils ne listent pas : ProcessType.AcceptsManagerAgent (Hierarchical et Consensual) et AcceptsManagerLlm (Hierarchical et Autonomous), qui encadrent le manager qu'une crew peut déclarer ; CrewPlanner.HonoursTaskAgent, HowTheCrewRuns et AgentTheModeChooses (src/core/Orkeon.Domain/Crew/CrewPlanner.cs), dont la branche _ décrit une exécution séquentielle ; DecisionTaskRules.Check (src/core/Orkeon.Domain/Task/DecisionTaskRules.cs), qui ne gère les tâches de décision et les conditions when que pour Sequential, Parallel et Graph ; et le budget, que Crew.cs et CrewDefinitionValidator n'acceptent que pour Autonomous.
Point d'entrée. Quand le mode a besoin de son propre point d'entrée, ajoutez-le à IProcessStrategy (src/core/Orkeon.Domain/Crew/IProcessStrategy.cs), comme l'a été ExecuteAutonomousAsync ; chaque stratégie existante l'implémente alors en levant NotSupportedException("Use <Mode>ProcessStrategy …").
API publique. Les projets core suivent leur surface publique : ajoutez chaque nouveau membre public au PublicAPI.Unshipped.txt du projet (src/core/Orkeon.Domain/, src/core/Orkeon.Infrastructure/, src/core/Orkeon.Application/), sinon le build échoue (RS0016/RS0017 sont des erreurs).
DTO Application. Rien à ajouter : CrewDto.ProcessType est une chaîne, et les handlers (GetCrewHandler, CreateCrewHandler) y copient le ProcessType.Value du value object Domain ; le nouveau nom atteint donc le DTO dès l'étape 1 faite.
Fluent Builder (optionnel). CrewBuilder.Process(ProcessType.Swarm) fonctionne tel quel ; un raccourci comme .Swarm() n'existe que pour les modes historiques (Sequential(), Hierarchical(...), Parallel(), Consensual()).
Étape 2 — Domain : configuration et moteur (si nécessaire)
DTO de configuration
Fichier : src/core/Orkeon.Domain/Configuration/<Mode>Config.cs — un sealed record immuable avec des valeurs par défaut, nullable là où une valeur surcharge un preset (GraphConfig sert de modèle : CircuitBreakerPreset = "strict", limites nullables).
Faites-le voyager jusqu'à l'exécution :
| Où | Quoi ajouter | Précédent Graph |
|---|---|---|
Configuration/CrewConfiguration.cs |
public <Mode>Config? <Mode>Config { get; init; } sur CrewConfiguration (et sur TaskConfiguration, même fichier, pour un bloc de niveau tâche) |
CrewConfiguration.GraphConfig |
Crew/CrewCreateOptions.cs |
La même propriété | CrewCreateOptions.GraphConfig |
Crew/Crew.cs |
Une propriété en lecture seule alimentée depuis les options dans Crew.Create |
Crew.GraphConfig |
Crew/CrewBuilder.cs |
With<Mode>Config(...) qui alimente les options |
WithGraphConfig(...) |
La stratégie doit lire la config sur l'argument crew au moment de l'exécution, jamais la stocker sur l'instance de stratégie (scoped, partagée) — des crews concurrentes écraseraient mutuellement leurs réglages.
Moteur
Un moteur réutilisable va dans la couche Domain, sans aucune dépendance externe (Orkeon.Domain.Graph pour StateGraph<TState>, Orkeon.Domain.Common.StateMachine pour la FSM). Ce que fournissent les moteurs existants, et qu'un nouveau devrait fournir aussi :
- une garantie de terminaison — circuit breaker (
CircuitBreakerPolicy, presetsStrict/Default/Permissive) ou budget (AgentExecutionBudget, mêmes trois presets) ; - des événements d'observabilité (
OnNodeCompleted/OnTransition,OnCircuitBroken) et un instantané d'état ; - l'annulation coopérative (
CancellationTokensur chaque membre asynchrone) ; - la sûreté des threads là où le moteur est partagé (
lock,Interlocked) ; [assembly: InternalsVisibleTo]uniquement pour les types que les tests doivent atteindre.
Étape 3 — Infrastructure : la stratégie
Fichier : src/core/Orkeon.Infrastructure/Crew/Strategies/<Mode>ProcessStrategy.cs
public sealed partial class SwarmProcessStrategy : IProcessStrategy
{
public SwarmProcessStrategy(
CrewStrategyDependencies dependencies, // tâches, agents, service d'exécution, scope mémoire (+ événements de domaine facultatifs)
ILogger<SwarmProcessStrategy> logger,
ICrewExecutionHook? hook = null, // optionnel : l'observateur du run
TaskAgentSelector? agentSelector = null) // optionnel : qui exécute une tâche sans agent:
{ /* … */ }
public Task<CrewOutput> ExecuteSequentialAsync(Crew crew,
IReadOnlyDictionary<string, string>? inputVariables = null, CancellationToken cancellationToken = default)
{ /* le mode */ }
// Les points d'entrée que le mode ne sert pas :
public Task<CrewOutput> ExecuteHierarchicalAsync(/* … */)
=> throw new NotSupportedException("Use HierarchicalProcessStrategy for hierarchical orchestration.");
// … ExecuteParallelAsync, ExecuteAutonomousAsync de même
}
Réutilisez les briques partagées de Crew/Strategies/ et Crew/ — plusieurs sont internal, raison pour laquelle les stratégies vivent dans Orkeon.Infrastructure :
| Brique | Usage |
|---|---|
CrewStrategyDependencies |
Les quatre collaborateurs que prend chaque stratégie (repositories de tâches/agents, IAgentExecutionService, IMemoryScope), plus un cinquième facultatif, DomainEvents (IDomainEventDispatcher?) |
CrewTaskSequencer.ResolveAsync |
Ordre des tâches : celui du plan, sinon le tri topologique stable sur dependencies |
TaskAgentSelector |
Choix de l'agent : agent: déclaré, sinon OrkeonApplicationOptions.AgentSelectionStrategy |
CrewHookDispatcher |
Appels à ICrewExecutionHook — envoyez l'événement terminal (CrewCompletedAsync / CrewFailedAsync) sur chaque sortie, initialisation et annulation comprises |
TokenUsageTally |
Télémétrie de tokens dans les métadonnées de CrewOutput (jamais un zéro fabriqué) |
AgentDelegationToolsProvider |
Outils de délégation pour les agents avec allowDelegation: true (Sequential, Graph) |
LlmUsageScope.Begin(...) |
Comptabiliser les appels LLM que le mode fait lui-même (un manager, un juge) sous la bonne opération |
Rendez compte honnêtement du résultat : CrewOutput.CreateFailure(...) quand le contrat propre du mode a échoué (le runner sort alors avec un code non nul), avec les sorties et l'usage de tokens produits jusque-là.
Étape 4 — Infrastructure : enregistrement et aiguillage
Trois endroits, tous dans Orkeon.Infrastructure :
| Fichier | Changement |
|---|---|
DependencyInjection/InfrastructureExtensions.cs |
services.AddScoped<SwarmProcessStrategy>(); dans AddOrkeonRepositoriesAndStrategies — ou une extension publique AddOrkeon<Mode>() (binding d'options, stratégies de vote…) appelée depuis AddOrkeonFeatureModules, comme AddOrkeonConsensus() |
Crew/Strategies/ProcessStrategyFactory.cs |
"Swarm" => _serviceProvider.GetRequiredService<SwarmProcessStrategy>(), |
Orchestration/SequentialCrewOrchestrator.cs |
Un cas dans ExecuteDomainStrategyAsync qui appelle le point d'entrée choisi ("Swarm" => await processStrategy.ExecuteSequentialAsync(crew, stringVariables, cancellationToken)…) |
Une section d'options suit la convention Orkeon:* (services.AddOptions<SwarmOptions>().BindConfiguration("Orkeon:Swarm")) et est listée dans la configuration.
Étape 5 — YAML : le bloc de configuration
process: swarm ne demande rien de plus (étape 1). Un bloc de niveau crew suit le chemin de graph: ; un bloc de niveau tâche suit celui du deliverable: de tâche — mappé dans MapTasks, puis appliqué à la tâche par CrewFactory : un bloc lu et jamais appliqué est un bug, et une crew qui écrit une clé qu'aucun modèle ne porte est refusée au chargement (CrewYamlKeyCheck), donc le modèle de cette étape doit exister avant d'écrire le bloc.
Modèles — src/core/Orkeon.Infrastructure/Configuration/Yaml/YamlConfigModels.cs. Les modèles ne portent aucun attribut [YamlMember] : les clés se résolvent par convention (camelCase, avec un repli snake_case). Ajoutez une classe publique et la propriété sur les modèles qui en ont besoin :
public class SwarmYamlConfig
{
public int? MaxAgents { get; set; } // maxAgents: ou max_agents:
}
// Sur CrewYamlConfig (crew mono-fichier) ET CrewSettingsYamlConfig (crew.yaml multi-fichiers) :
public SwarmYamlConfig? SwarmConfig { get; set; } // clé : swarmConfig
// Sur TaskYamlConfig pour un bloc de niveau tâche.
Mapping — Configuration/Yaml/YamlCrewMapper.cs : une méthode privée Map<Mode>Config(...) qui renvoie le DTO Domain (ou null), une propriété sur CrewMappingSettings, et l'affectation dans BuildConfiguration (niveau crew) ou MapTasks (niveau tâche).
Loader — Configuration/YamlCrewDefinitionLoader.cs remplit CrewMappingSettings dans les deux chemins : depuis CrewSettingsYamlConfig (multi-fichiers) et depuis CrewYamlConfig (mono-fichier). En oublier un fait fonctionner le bloc dans une seule disposition.
Factory — Configuration/CrewFactory.cs : if (config.SwarmConfig is not null) builder.WithSwarmConfig(config.SwarmConfig);, à côté de WithGraphConfig.
Validation — les règles de chargement (une valeur hors bornes, une combinaison que le mode refuse) vont dans Configuration/Yaml/CrewDefinitionValidator.cs, pour qu'un fichier erroné échoue au chargement et non en cours de run.
Étape 6 — DSL de scripting
| Fichier | Changement |
|---|---|
src/scripting/Orkeon.Scripting/Builders/JsCrewBuilder.cs |
Ajouter le nom à AllowedProcesses (le builder refuse tout autre nom) |
src/scripting/Orkeon.Scripting/Typings/crew.d.ts |
L'ajouter à l'union Process |
src/scripting/Orkeon.Scripting/Adapters/JsCrewConfigurationAdapter.cs |
Rien pour le nom (ProcessType.TryFrom) ; mapper la config du mode quand le DSL l'expose, ou la lister dans CollectIgnoredFeatures |
src/scripting/Orkeon.Scripting.Cli/Commands/UseCases/UseCasesCommand.cs |
Le texte d'aide de --process de orkeon usecases list |
La forme procédurale d'un script (await crew.run()) ignore le process ; seule la forme déclarative (globalThis.crew = crew) exécute la stratégie — voir Scripting.
Étape 7 — Tests
xUnit avec les assertions natives et des doubles écrits à la main (Mock* / Fake* / Stub* dans un dossier Doubles/ — pas de bibliothèque de mocking).
| Test | Où | Précédent |
|---|---|---|
Le value object (nombre d'éléments de All — figé à 6 aujourd'hui —, From, TryFrom, insensibilité à la casse) |
tests/core/Orkeon.Domain.Tests/ValueObjects/ProcessTypeTests.cs |
— |
| Le moteur, s'il y en a un | tests/core/Orkeon.Domain.Tests/<Zone>/ |
Graph/StateGraphTests.cs, Common/StateMachine/* |
| La stratégie : chemin nominal, crew vide, échecs, annulation, événement terminal du hook sur chaque sortie, métadonnées de tokens, points d'entrée non supportés | tests/core/Orkeon.Infrastructure.Tests/Strategies/<Mode>ProcessStrategy/ |
GraphProcessStrategy/GraphProcessStrategyTests.cs |
| L'aiguillage de la factory | Strategies/ProcessStrategyFactory/ProcessStrategyFactoryTests.cs |
— |
| L'aiguillage de l'orchestrateur vers le bon point d'entrée | Orchestration/CovAutonomous_SequentialCrewOrchestratorTests.cs |
KickoffAsync_Graph_DispatchesViaSequential |
YAML : parsing de process: et le bloc de config dans les deux dispositions |
Configuration/YamlCrewDefinition/YamlCrewDefinitionTests.cs (itère sur ProcessType.All), Configuration/CircuitBreakerPolicyFactoryGraphTests.cs |
— |
| Scripting | tests/scripting/Orkeon.Scripting.Tests/ (le builder accepte le nom, l'adaptateur le mappe) |
— |
dotnet test tests/core/Orkeon.Domain.Tests/Orkeon.Domain.Tests.csproj --filter "FullyQualifiedName~ProcessType"
dotnet test tests/core/Orkeon.Infrastructure.Tests/Orkeon.Infrastructure.Tests.csproj --filter "FullyQualifiedName~Swarm"
Le runner de tests est Microsoft.Testing.Platform : un --filter qui ne correspond à aucun test d'un projet est une erreur, filtrez donc chaque projet sur des noms qu'il contient.
Étape 8 — Exemple et documentation
Exemple
Dossier : examples/<NN-catégorie>/<NNN-nom>/ avec un config.yaml (ou un main.ork.ts) et un README.md (objectif, diagramme, YAML annoté, comment l'exécuter). Partez de 102-graph-orchestration. La racine YAML est plate — pas d'enveloppe crew: — et agents: / tasks: sont des mappings indexés par id :
name: "swarm-demo"
goal: "…"
process: swarm
swarmConfig: # refusé au chargement tant que SwarmYamlConfig ne le porte pas
maxAgents: 5
agents:
scout: # mapping indexé par id d'agent — jamais une séquence
role: "…"
goal: "…"
tasks:
explore: # l'id EST la clé (TaskYamlConfig n'a pas de champ id:)
description: "…"
expectedOutput: "…"
Un nouvel exemple numéroté change le nombre d'exemples que la documentation annonce et que scripts/check-doc-claims.py vérifie ; listez-le dans examples/INDEX.md.
Documentation
| Page | Changement |
|---|---|
docs/orchestration/<mode>.md (nouvelle) |
Vue d'ensemble, architecture (classes par couche), flux d'exécution, configuration et résolution, garanties de terminaison, observabilité, usage YAML et C#, exemple, tests — les pages Graph et Autonomous servent de modèles |
docs/orchestration/process-types.md |
La liste des valeurs, le diagramme d'architecture, la colonne de la matrice, une section dédiée, l'arbre de décision, le tableau des coûts |
docs/architecture/yaml-schema.md |
Les valeurs de process: et le nouveau bloc |
docs/reference/configuration.md |
Une nouvelle section d'options, le cas échéant |
docs/INDEX.md, docs/toc.yml |
La nouvelle page |
CHANGELOG.md, CLAUDE.md |
La fonctionnalité, et chaque mention de « 6 modes » |
Chaque page a son miroir français sous docs/fr/ (même chemin), mis à jour dans le même changement — une vérification de CI contrôle la parité. Les placeholders en prose vont dans des code spans (<Mode>), jamais nus. Puis exécutez :
python3 scripts/check-doc-claims.py
Check-list finale
| Critère | Attendu | Vérifié |
|---|---|---|
| Déclaré | Entrée ProcessType, nombre d'éléments de All |
[ ] |
| Prédicats par mode | AcceptsManagerAgent, AcceptsManagerLlm, helpers de CrewPlanner, DecisionTaskRules.Check, règle du budget tranchés pour le nouveau mode |
[ ] |
| Aiguillé | Stratégie enregistrée, cas ProcessStrategyFactory, cas SequentialCrewOrchestrator |
[ ] |
| Se termine | Circuit breaker, budget ou boucle bornée — et annulation respectée | [ ] |
| Observable | Événement terminal du hook sur chaque sortie, métadonnées de tokens, logs structurés | [ ] |
| Résultat honnête | CreateFailure quand le contrat du mode échoue |
[ ] |
| Configurable | Config par crew lue sur la crew, les deux dispositions YAML, validation au chargement | [ ] |
| Scriptable | AllowedProcesses, crew.d.ts, orkeon usecases |
[ ] |
| Testé | Domain, stratégie, factory, orchestrateur, YAML, mapping, scripting | [ ] |
| Documenté | Page du mode + miroir FR, process-types, yaml-schema, INDEX/toc, CHANGELOG, check-doc-claims.py au vert |
[ ] |
| Exemple | config.yaml fonctionnel avec README, listé dans examples/INDEX.md |
[ ] |