đŹđ§ English version
Guide comparatif des ProcessTypes
Prérequis : Vue d'ensemble et YAML et Builders
Vue d'ensemble
Orkeon propose 6 stratégies d'orchestration via le value object ProcessType (Domain layer). Chaque stratégie définit comment les agents se coordonnent pour exécuter les tùches d'une Crew. Le choix du ProcessType est le levier architectural le plus impactant sur le comportement d'un systÚme multi-agents.
// Orkeon.Domain.SharedKernel.ValueObjects.ProcessType (sealed record)
ProcessType.Sequential // Pipeline linéaire
ProcessType.Hierarchical // Manager + workers
ProcessType.Parallel // Vagues de dépendances, concurrence dans une vague
ProcessType.Consensual // Chaque agent exécute chaque tùche, puis un vote
ProcessType.Graph // Graphe d'états avec circuit breaker
ProcessType.Autonomous // Auto-organisation sous budget
En YAML, le mode est process: (insensible à la casse, sequential en son absence) ; une valeur inconnue fait échouer le chargement en nommant les six valeurs valides (YamlCrewMapper.ParseProcessType). Avec le Fluent Builder, CrewBuilder offre .Sequential(), .Hierarchical(manager), .Parallel() et .Consensual() ; Graph et Autonomous passent par .Process(ProcessType.Graph) / .Process(ProcessType.Autonomous).
Architecture d'implémentation
ICrewOrchestrationService.KickoffAsync (SequentialCrewOrchestrator)
â planification (si activĂ©e, tenue dans la portĂ©e de plan du run), puis un switch sur crew.ProcessType
âŒ
IProcessStrategyFactory.CreateStrategy(ProcessType) (ProcessStrategyFactory, Infrastructure)
â
âââ SequentialProcessStrategy â ExecuteSequentialAsync
âââ HierarchicalProcessStrategy â ExecuteHierarchicalAsync(id du manager)
âââ ParallelProcessStrategy â ExecuteParallelAsync
âââ ConsensualProcessStrategy â ExecuteSequentialAsync
âââ GraphProcessStrategy â ExecuteSequentialAsync
âââ AutonomousProcessStrategy â ExecuteAutonomousAsync(crew.Budget)
IProcessStrategy (Domain) a quatre points d'entrĂ©e â ExecuteSequentialAsync, ExecuteHierarchicalAsync, ExecuteParallelAsync, ExecuteAutonomousAsync. SequentialCrewOrchestrator choisit le point d'entrĂ©e d'aprĂšs ProcessType.Value ; Graph et Consensual rĂ©utilisent le point d'entrĂ©e sĂ©quentiel, et une stratĂ©gie lĂšve NotSupportedException sur ceux qu'elle ne sert pas. Les stratĂ©gies sont enregistrĂ©es en scoped par AddOrkeonInfrastructure() (Consensual via AddOrkeonConsensus(), qu'il appelle).
Ce que toutes les stratégies partagent :
- Ordre des tĂąches â les modes qui distribuent les tĂąches l'une aprĂšs l'autre (tous sauf Parallel) les exĂ©cutent dans l'ordre rĂ©solu par
CrewTaskSequencer: un tri topologique stable sur lesdependenciesdĂ©clarĂ©es (dĂ©taillĂ© sous Sequential). Un plan ne le change jamais, dans aucun mode. - Planification â
planning: true(YAML),.Planning(true)(C#) oucrewBuilder().planning()(.ork.ts) fait Ă©crire par un planificateur un plan pas Ă pas pour chaque tĂąche avant la premiĂšre, et chaque tĂąche lit son propre plan dans son prompt â dans les six modes. Le plan ne change ni l'ordre des tĂąches ni qui les exĂ©cute. Voir Planification plus bas. - Hooks de cycle de vie â chaque mode rend compte via
ICrewExecutionHook(OnTaskStartedAsync,OnTaskCompletedAsync,OnCrewCompletedAsync,OnCrewFailedAsync), sur toutes les sorties, annulation comprise ; c'est ce qui alimenteAUTO_SUMMARY.md, le fluxorkeon run --eventset la progression affichĂ©e par l'hĂŽte. - Issue â une tĂąche Ă©chouĂ©e fait Ă©chouer la crew et saute ses dĂ©pendantes, dans tous les modes (dĂ©taillĂ© sous Sequential) :
Success = false, uneErrorqui nomme chaque tĂąche Ă©chouĂ©e ou sautĂ©e, un hookFailed, code de sortie 2. - TĂ©lĂ©mĂ©trie des tokens â l'usage rĂ©el (prompt, complĂ©tion, hits/misses de cache quand le fournisseur les rapporte) voyage dans les mĂ©tadonnĂ©es de
CrewOutput;CrewOutput.TokensUsedrestenullquand rien n'a été mesuré.
Qui exécute une tùche qui ne nomme aucun agent
Un agent: au niveau de la tùche est une décision, pas une suggestion : Sequential, Parallel et Graph le respectent toujours. Pour une tùche sans agent, ces trois modes interrogent TaskAgentSelector, piloté par OrkeonApplicationOptions.AgentSelectionStrategy :
| Valeur | Comportement |
|---|---|
FirstFit (défaut) |
Round-robin sur les agents de la crew |
Embedding |
Correspondance sĂ©mantique entre la tĂąche et le profil de chaque agent (exige un vrai fournisseur d'embeddings â voir les limitations) : le fournisseur est BGE local (AddOrkeonLocalEmbeddings()), sinon la configuration distante Orkeon:Embeddings, sinon le premier usage Ă©choue et la tĂąche retombe en round-robin avec un avertissement |
Skill |
Correspondance lexicale (Jaccard) sur les mots-clés rÎle/objectif/backstory, sans fournisseur d'embeddings |
Une sélection qui échoue, ou qui désigne un agent absent de la crew, retombe sur le round-robin avec un avertissement. Hierarchical et Autonomous laissent choisir le LLM manager (l'agent: d'une tùche n'y est pas consulté) ; Consensual fait exécuter chaque tùche par tous les agents.
Planification (planning: true)
planning: true (YAML), .Planning(true) (C#) ou crewBuilder().planning() (.ork.ts) â le planning=True de CrewAI, coupĂ© par dĂ©faut. Avant la premiĂšre tĂąche, un planificateur Ă©crit un plan pas Ă pas pour chaque tĂąche, et chaque tĂąche lit ensuite son propre plan dans son prompt.
- Sur quel modĂšle â le fournisseur que fixe
CrewBuilder.WithPlanningLlm(C# ; il exige.Planning(): un fournisseur de planification sur une crew qui ne planifie pas est refusĂ© Ă sa construction), sinon le profil par dĂ©faut de l'hĂŽte â la sectionLlm: le planificateur y reste, quels que soient les profils que nomment les agents. Un appel par run, Ă la tempĂ©rature 0,3, comptĂ© sousoperation: planningdanscost.updatedâ le fournisseur C# comme un fournisseur que l'hĂŽte enregistre â, et annulĂ© avec le run. - Ce qu'il lit â le but de la crew, une ligne sur la façon dont le mode ordonne les tĂąches et choisit leurs agents, les variables du run (
initial_contextcompris), et chaque tĂąche par numĂ©ro, dans l'ordre oĂč le run les prend : sa description et sa sortie attendue avec les variables dedans, telles que son agent les lit ; ses dĂ©pendances, par numĂ©ro ; et son agent â rĂŽle, but, noms des outils qu'il tient pour la tĂąche â lĂ oĂč le mode exĂ©cute une tĂąche sur l'agent qu'elle nomme (Sequential, Parallel, Graph). Ailleurs, le planificateur apprend ce que fait le mode Ă la place â « confiĂ© par le manager » (Hierarchical, Autonomous), « chaque agent rĂ©pond » (Consensual), « choisi au run » (une tĂąche qui ne nomme pas d'agent) â, et les agents de la crew sont listĂ©s une fois. Jamais un identifiant : le planificateur rĂ©pond par numĂ©ro. BornĂ© (PlanningDefaults) : une description Ă 1 500 caractĂšres, une sortie attendue Ă 500, le but d'un agent Ă 300, 15 noms d'outils par agent, les variables Ă 2 000 en tout â un texte coupĂ© finit par[âŠ]. Ni backstory, ni connaissance, ni mĂ©moire. - Ce qu'il Ă©crit â
{"plans": [{"task": 1, "plan": "1. âŠ"}]}: au plus 8 Ă©tapes numĂ©rotĂ©es par tĂąche, qui nomment les outils Ă employer lĂ oĂč un outil aide. La forme de la rĂ©ponse est contrainte autant que le fournisseur le peut (json_schema, sinonjson_object, sinon le prompt seul) et lue avec tolĂ©rance â un bloc entre```ou une phrase autour de l'objet. - OĂč il va â dans le prompt utilisateur de la tĂąche, aprĂšs la tĂąche (description, sortie attendue, livrable) et avant les variables de contexte, sous Plan for this task, from the crew's planner â follow it where it helps; the task above prevails:, coupĂ© Ă 2 000 caractĂšres. Le Guardian le filtre avec le reste du prompt, et le plan de chaque tĂąche est journalisĂ© sur une ligne en
Information(--verbose 1). La tĂąche elle-mĂȘme n'est jamais modifiĂ©e : la requĂȘte de connaissance, le souvenir rangĂ© et les prompts du manager lisent la tĂąche, pas son plan. Le run tient son plan dans une portĂ©e Ă lui (CrewPlanScope), lue lĂ oĂč les exĂ©cutions de chaque mode composent leur prompt â deux runs d'une mĂȘme crew ne lisent jamais le plan l'un de l'autre. - Dans chaque mode â Sequential, Parallel et Graph (chaque essai) : l'agent de la tĂąche. Hierarchical : le travailleur que choisit le manager, et chaque rĂ©vision qu'il demande ; les prompts du manager ne changent pas. Consensual : chaque rĂ©ponse candidate â un bulletin, tĂąche Ă part, non. Autonomous : l'agent qui prend la tĂąche, et le pair Ă qui elle est confiĂ©e aprĂšs un Ă©chec, qui reprend la tĂąche elle-mĂȘme.
- Il ne change ni l'ordre ni les agents â avec ou sans plan, une crew exĂ©cute les mĂȘmes tĂąches, dans le mĂȘme ordre, sur les mĂȘmes agents.
- Quand ça se passe mal â le plan est un conseil. Une rĂ©ponse illisible est redemandĂ©e une fois, avec ce qui n'a pas pu ĂȘtre lu, puis la crew tourne sans plan, avec un avertissement â qui le dit quand la rĂ©ponse s'est arrĂȘtĂ©e au
MaxTokensdu profil. Une tĂąche que le plan oublie s'exĂ©cute sans plan, avec un avertissement qui la nomme ; un numĂ©ro donnĂ© deux fois garde son premier plan et un numĂ©ro inconnu est ignorĂ©, chacun avec un avertissement. Seul un fournisseur en panne â une clĂ© refusĂ©e, un point d'accĂšs injoignable â fait Ă©chouer le run, avant sa premiĂšre tĂąche, avec la raison du fournisseur. - Sur le fournisseur Ă©cho â celui d'un hĂŽte sans section
Llm, qui renvoie son prompt au lieu d'y rĂ©pondre (LlmProviderCapabilities.ReplaysPrompt) â la planification est sautĂ©e avec un avertissement (planning skipped â the echo provider cannot plan, avec le remĂšde,orkeon init), et la crew va au bout comme tout run sans clĂ©. - CoĂ»t â un appel par run (deux aprĂšs une rĂ©ponse illisible), donc un par entrĂ©e sous
KickoffForEachAsyncet un par message dansorkeon-host, dont le prompt croĂźt avec la crew ; et le plan de chaque tĂąche voyage avec chaque tour de la boucle de son agent, ce que la borne de 2 000 caractĂšres contient. - En streaming aussi â un run en streaming (
KickoffStreamingAsync, une API C#) est le mĂȘme run : il planifie, et chaque tĂąche lit son plan, comme avecKickoffAsync.
Classes clés : CrewPlanner et PlanningContext (Domain), ExecutionPlanParser, CrewPlanScope et AgentPromptComposer.
Matrice de comparaison rapide
| CritĂšre | Sequential | Hierarchical | Parallel | Consensual | Graph | Autonomous |
|---|---|---|---|---|---|---|
| ModĂšle d'exĂ©cution | LinĂ©aire | LinĂ©aire + revue du manager | Vagues de dĂ©pendances, concurrence dans une vague | Tous les agents par tĂąche + bulletins de pairs | LinĂ©aire, ou les nĆuds et arĂȘtes de graph: (arĂȘtes conditionnelles, boucles) |
Assignation par le manager, délégation sur échec |
| Choix de l'agent | Déclaré, sinon sélecteur | LLM manager | Déclaré, sinon sélecteur | Tous les agents | Déclaré, sinon sélecteur | LLM manager |
| Dépendances entre tùches | Ordre + saut sur échec | Ordre + saut sur échec | Vagues + saut sur échec | Ordre + saut sur échec | Ordre + saut sur échec | Ordre + saut sur échec |
| Une tĂąche Ă©chouĂ©e fait Ă©chouer la crew | â (dĂ©pendantes sautĂ©es) | â (dĂ©pendantes sautĂ©es) | â (dĂ©pendantes sautĂ©es) | â (dĂ©pendantes sautĂ©es) | â aprĂšs ses retries (dĂ©pendantes sautĂ©es) | â (dĂ©pendantes sautĂ©es ; un budget Ă©puisĂ© aussi) |
| Circuit breaker | â | â | â | â | â 3 mĂ©canismes | â |
| Budget d'exĂ©cution | â | â | â | â | â | â
5 dimensions (budget: de la crew) |
| Retry automatique | â | Jusqu'Ă 2 rĂ©-exĂ©cutions aprĂšs revue | â | Rounds de vote | â | Une dĂ©lĂ©gation Ă un pair |
retry: d'une tĂąche |
â | â | â | â | â | â |
asyncExecution: true d'une tĂąche |
â Tourne pendant les tĂąches suivantes | RefusĂ© au chargement | AcceptĂ©, sans effet propre | RefusĂ© au chargement | RefusĂ© au chargement | RefusĂ© au chargement |
Tùches de décision et conditions when |
â | RefusĂ© au chargement | â | RefusĂ© au chargement | â | RefusĂ© au chargement |
Manager (managerAgent: ; WithManagerLlm en C#) |
RefusĂ© au chargement | â Un agent (requis) ou, en C#, un LLM : il assigne et relit | RefusĂ© au chargement | â
Un agent : l'arbitre de ManagerDecision (un LLM est refusé) |
Refusé au chargement | Un LLM seulement : le profil par défaut, ou WithManagerLlm en C# (un agent est refusé) |
planning: true : chaque tĂąche lit son plan |
â | â Le travailleur, chaque rĂ©vision | â | â Chaque candidate | â Chaque essai | â Celui qui la prend, le pair |
| ComplexitĂ© | â | ââ | â | âââ | ââ | ââââ |
| CoĂ»t LLM relatif | Bas | Moyen | Bas | ĂlevĂ© | Bas Ă moyen | Moyen |
| Cas d'usage principal | Pipelines ETL | QA, boucles de revue | Fan-out + synthÚse | Plusieurs tentatives indépendantes | Tùches instables à relancer | Exploration, R&D |
Les tùches de décision et les conditions when sont décrites dans ModÚles de décision et dans l'ADR-016 : Sequential, Parallel et Graph les exécutent, les trois autres modes refusent au chargement une crew qui en utilise (une crew construite en C#, avant sa premiÚre tùche).
1. Sequential â Pipeline linĂ©aire
Principe
Les tĂąches s'exĂ©cutent une par une â sauf une tĂąche asyncExecution: true, qui tourne pendant les tĂąches qui la suivent (voir TĂąches asynchrones). Chaque tĂąche reçoit en contexte les sorties des tĂąches exĂ©cutĂ©es avant elle. L'assignation des agents suit la rĂšgle ci-dessus : l'agent: de la tĂąche s'il est dĂ©clarĂ©, sinon le sĂ©lecteur configurĂ© (round-robin par dĂ©faut).
Ordre d'exĂ©cution â avec ou sans plan, qui ne le change jamais : les tĂąches s'exĂ©cutent dans un ordre topologique stable sur leurs dependencies dĂ©clarĂ©es â une tĂąche passe aprĂšs toutes celles dont elle dĂ©pend, et partout oĂč les dĂ©pendances le permettent l'ordre dĂ©clarĂ© est conservĂ©, si bien qu'une crew qui ne dĂ©clare aucune dĂ©pendance s'exĂ©cute exactement comme Ă©crite. Cela vaut dans toutes les dispositions : la disposition multi-fichiers (tasks/*.yaml) liste les tĂąches dans l'ordre ordinal de leurs noms de fichier, et le tri place consolidate.yaml aprĂšs l'extract.yaml dont elle dĂ©pend. Une dĂ©pendance qui nomme un identifiant de tĂąche inconnu est ignorĂ©e ; un cycle ne fait jamais Ă©chouer la crew â l'ordre dĂ©clarĂ© est conservĂ© pour les tĂąches prises dedans et un avertissement les nomme. La mĂȘme rĂšgle ordonne les modes hierarchical, consensual, graph et autonomous, qui distribuent eux aussi leurs tĂąches l'une aprĂšs l'autre ; le mode parallel garde sa propre sĂ©mantique (des vagues de dĂ©pendances, et un cycle y est refusĂ©).
Gestion des Ă©checs (tous les modes) : une tĂąche dont une dĂ©pendance dĂ©clarĂ©e n'a pas rĂ©ussi â Ă©chouĂ©e, ou elle-mĂȘme sautĂ©e â est sautĂ©e, jamais exĂ©cutĂ©e sur un contexte qui dit Task failed: ⊠lĂ oĂč son entrĂ©e aurait dĂ» se trouver : elle apparaĂźt comme â skipped dans AUTO_SUMMARY.md et comme un Ă©vĂ©nement task.completed avec skipped: true, les tĂąches qui n'en dĂ©pendent pas s'exĂ©cutent quand mĂȘme, et la crew Ă©choue en nommant chaque tĂąche Ă©chouĂ©e ou sautĂ©e. La rĂšgle est la mĂȘme dans les six modes : une crew dont une tĂąche a Ă©chouĂ© rend Success = false, son hook reçoit Failed avec la mĂȘme raison, et orkeon run sort en 2. Un mode qui tolĂšre un Ă©chec â Graph et ses retries, Autonomous et sa dĂ©lĂ©gation â le fait avant que la tĂąche compte comme Ă©chouĂ©e. Une tĂąche dont la boucle d'agent a atteint son plafond d'itĂ©rations et qui a rĂ©pondu au tour sans outil qui le suit garde Success et apparaĂźt comme â completed on its iteration cap, Ă cĂŽtĂ© de â skipped, avec endedOnIterationCap: true sur son Ă©vĂ©nement task.completed. Une tĂąche qui rĂ©ussit sans Ă©crire son livrable tool_call garde aussi Success et apparaĂźt comme â completed without writing its deliverable, avec deliverableMissing: true (Le livrable tool_call) ; une tĂąche en Ă©chec ne porte jamais ce drapeau, y compris une tĂąche Hierarchical que le manager a rejetĂ©e jusqu'au bout, et une tĂąche Consensual juge le fichier sur tout le vote : un candidat qui l'a Ă©crit compte, quelle que soit la rĂ©ponse retenue. Une tĂąche qui a fait les deux apparaĂźt comme â completed on its iteration cap without writing its deliverable. Une reprise par un pair en mode Autonomous rapporte le drapeau et le chemin du livrable (AgentChannelResponse.DeliverableMissing, AgentChannelResponse.DeliverablePath) ; un canal servi par le gestionnaire de commande d'agent d'un script ne fait aucune vĂ©rification de fin de tĂąche et rĂ©pond deliverableMissing: false. Le drapeau de plafond est portĂ© dans tous les modes, une reprise par un pair en mode Autonomous comprise (AgentChannelResponse.EndedOnIterationCap, expĂ©rimental ORKEXP002) ; la seule exception est un canal servi par le gestionnaire de commande d'agent d'un script, qui n'a pas d'information sur le plafond et rĂ©pond false. delegate_work renvoie ended_on_iteration_cap pour un collĂšgue qui a fini sur son plafond. Une rĂ©ponse vide Ă la derniĂšre itĂ©ration permise suit le mĂȘme chemin, et un rĂ©sultat typĂ© porte les tokens, les tokens de cache, les itĂ©rations, les nouvelles tentatives et la date de fin. Les boucles de repli native (appels d'outils) et textuelle hĂ©ritĂ©e n'ont pas de tour sans outil : elles finissent sur le plafond sans le drapeau.
TĂąches asynchrones (asyncExecution)
Une tĂąche asyncExecution: true â l'async_execution de CrewAI ; .Async() sur CrewTaskBuilder, .asyncExecution() dans un script â est lancĂ©e sans ĂȘtre attendue : la tĂąche suivante dĂ©marre aussitĂŽt, et les deux tournent ensemble.
- Une tĂąche qui en dĂ©pend l'attend â par
dependencies:, l'Ă©quivalent ducontextde CrewAI â, puis lit sa sortie ; si elle a Ă©chouĂ©, cette tĂąche est sautĂ©e comme toute dĂ©pendante d'une tĂąche Ă©chouĂ©e. - Sa sortie entre dans le contexte une fois qu'une tĂąche l'a attendue : une tĂąche qui n'en dĂ©pend pas dĂ©marre sans elle, et toute tĂąche aprĂšs cette attente la lit, dans l'ordre dĂ©clarĂ© â ce qu'une tĂąche lit ne dĂ©pend jamais du minutage. Une tĂąche qui en a besoin la dĂ©clare.
- La crew attend toutes les tĂąches qu'elle a lancĂ©es avant de rendre son issue â rien ne survit au run â, et sa sortie reste celle de la derniĂšre tĂąche dĂ©clarĂ©e, pas de la derniĂšre Ă finir ;
CrewOutput.TaskOutputsliste les tĂąches dans l'ordre dĂ©clarĂ©. - Un Ă©chec suit la rĂšgle de tous les modes : la crew Ă©choue et les dĂ©pendantes de la tĂąche sont sautĂ©es ; les tĂąches dĂ©jĂ lancĂ©es vont Ă leur terme, rien n'est annulĂ© en cascade. Un run annulĂ© attend qu'elles s'arrĂȘtent, puis les annule.
- La tùche démarre (
TaskStartedEvent,task.started) quand elle est lancĂ©e et se termine (TaskCompletedEventouTaskFailedEvent) quand le run l'attend ; le crochet de fin âAUTO_SUMMARY.md,task.completedâ entend chaque tĂąche quand elle finit, dans l'ordre oĂč les tĂąches finissent. Un collĂšgue Ă qui elle dĂ©lĂšgue travaille dans son contexte. Il n'y a pas de plafond de concurrence : deux tĂąches asynchrones appellent leur LLM en mĂȘme temps.
process: sequential
tasks:
research:
description: "Research the market"
expectedOutput: "Market findings"
asyncExecution: true
survey:
description: "Survey the customers"
expectedOutput: "Survey results"
asyncExecution: true # tourne en mĂȘme temps que research
synthesis:
description: "Write the recommendation"
expectedOutput: "Recommendation"
dependencies: [research, survey] # attend les deux, lit les deux
process: parallel accepte asyncExecution: true sans effet propre â toutes les tĂąches d'une vague tournent dĂ©jĂ en mĂȘme temps. Hierarchical, Consensual, Graph et Autonomous ordonnent leurs tĂąches eux-mĂȘmes (le manager, le vote, le graphe, le budget) : une crew qui y Ă©crit asyncExecution: true est refusĂ©e au chargement, chaque tĂąche nommĂ©e, en YAML comme dans un script .ork.ts, et CrewBuilder.Build() refuse de mĂȘme en C#. asyncExecution: false, la valeur par dĂ©faut, se charge partout.
Mécanisme interne
TĂąche 1 â Agent A â sortieâ
â (contexte enrichi)
TĂąche 2 â Agent B â sortieâ
â
TĂąche 3 â Agent C â sortieâ â rĂ©sultat final
Classes clés : SequentialProcessStrategy, CrewTaskSequencer, TaskAgentSelector, AgentDelegationToolsProvider (les agents avec allowDelegation: true reçoivent delegate_work_to_coworker et ask_question_to_coworker)
Configuration YAML
# Racine plate â il n'y a pas de clĂ© enveloppe crew: (une clĂ© crew: est refusĂ©e au
# chargement comme inconnue), et agents:/tasks: sont des mappings indexés par id.
name: "pipeline"
goal: "Démo séquentielle"
process: sequential
tasks:
collect:
description: "Collecter les données"
expectedOutput: "Données brutes"
analyze:
description: "Analyser les données"
expectedOutput: "Rapport d'analyse"
dependencies: [collect]
recommend:
description: "Générer les recommandations"
expectedOutput: "Plan d'action"
dependencies: [analyze]
Configuration Fluent Builder
var crew = new CrewBuilder()
.Sequential()
.WithAgent(a => a.Role("Collector").Goal("Gather data"))
.WithAgent(a => a.Role("Analyst").Goal("Analyze data"))
.WithTask(t => t.Description("Collect").ExpectedOutput("Raw data"))
.WithTask(t => t.Description("Analyze").ExpectedOutput("Report"))
.Build();
Avantages
- Simplicité maximale : aucune configuration complexe, comportement prévisible
- Traçabilité : chaque étape est clairement identifiable dans les logs
- Contexte cumulatif : chaque tùche bénéficie des résultats précédents
- RĂ©sultat honnĂȘte : une Ă©tape Ă©chouĂ©e fait Ă©chouer la crew et arrĂȘte ses dĂ©pendantes (comme dans tous les modes)
Inconvénients
- Peu de parallélisme : le temps total est la somme des tùches, sauf celles marquées
asyncExecution - Point de dĂ©faillance unique : un Ă©chec bloque la suite de la chaĂźne â ses dĂ©pendantes sont sautĂ©es, seules les tĂąches indĂ©pendantes s'exĂ©cutent encore
- Pas de retry propre : une tĂąche demande des tentatives avec
retry:; rien n'est réessayé sinon - Rigide : l'ordre est fixe, pas de branchement conditionnel
Quand l'utiliser
- Pipelines ETL (extraction â transformation â chargement)
- RĂ©daction sĂ©quentielle (recherche â rĂ©daction â relecture)
- Workflows oĂč chaque Ă©tape dĂ©pend strictement de la prĂ©cĂ©dente
- Prototypage rapide et POC
Quand ne pas l'utiliser
- Beaucoup de tĂąches indĂ©pendantes qui pourraient toutes tourner en parallĂšle â Parallel exĂ©cute chaque vague de dĂ©pendances d'un coup ;
asyncExecutionconvient à quelques étapes concurrentes d'un pipeline
2. Hierarchical â Manager + Workers
Principe
Un manager (IManagerAgent, implémenté par LlmBasedManager) coordonne les workers. Pour chaque tùche, il choisit un worker via AssignTaskAsync(), le worker exécute, puis le manager revoit la sortie avec ReviewOutputAsync().
- La crew nomme son manager :
managerAgent:en YAML (crewBuilder().manager(agent)en.ork.ts,.Hierarchical(manager)/.WithManager(agent)en C#) â cet agent est retirĂ© du pool de workers. En C#,.WithManagerLlm(fournisseur)(lemanager_llmde CrewAI) donne au manager un fournisseur Ă lui : une telle crew se passe d'agent manager, et chaque agent est alors un worker. Une crew qui n'a ni l'un ni l'autre est refusĂ©e Ă sa construction, et unmanagerAgent:qui ne nomme aucun agent de la crew fait Ă©chouer le chargement, en listant ses agents. - Un manager n'a de sens qu'Ă deux autres endroits : un agent manager arbitre le vote d'une crew Consensual, un LLM manager distribue les tĂąches d'une crew Autonomous. Sequential, Parallel et Graph n'ont pas de manager, Autonomous pas d'agent manager et Consensual pas de LLM manager : une telle crew est refusĂ©e Ă son chargement ou Ă sa construction, le message nommant la clĂ© et le mode â l'agent n'aurait Ă©tĂ© qu'un worker de plus, le fournisseur jamais appelĂ©.
- Les décisions du manager passent par le LLM que la crew lui donne, résolu une fois par run : le fournisseur posé par
WithManagerLlm(C# ; comptĂ© comme un fournisseur que l'hĂŽte enregistre), sinon le fournisseur que porte l'agent manager (C# :.WithLlm(fournisseur), ou un agent Microsoft Agent Framework par.WithAgentFrameworkAgent(agent); comptĂ© de mĂȘme, nommĂ©provider:<nom>), sinon le blocllm:de l'agent manager â son profil et son modĂšle, un modĂšle non prĂ©cisĂ© Ă©tant celui du profil (llm: { profile: claude }) â sinon le profil par dĂ©faut de l'hĂŽte. Un profil que l'hĂŽte n'offre pas fait Ă©chouer le chargement de la crew, comme pour tout agent. Les appels sont comptabilisĂ©s sous le rĂŽle du manager (operation: manager). Le YAML n'a pas de clĂ©manager_llm: le blocllm:de l'agent manager en tient lieu. - Assignation : le LLM manager rĂ©pond en JSON ; une rĂ©ponse illisible retombe sur une heuristique rĂŽle/mots-clĂ©s, une erreur du LLM sur le premier worker. L'
agent:d'une tùche n'est pas consulté. - Revue : jusqu'à 3 revues par tùche, donc au plus 2 ré-exécutions (chacune avec une variable de contexte
revision_feedback). Un troisiĂšme rejet conserve la derniĂšre sortie, prĂ©fixĂ©e[NEEDS REVISION]et marquĂ©e en Ă©chec â et la tĂąche fait Ă©chouer la crew. Une revue qui Ă©choue vaut approbation. - Une tĂąche assignĂ©e Ă un agent absent de la crew ne s'exĂ©cute jamais, et fait Ă©chouer la crew. Une tĂąche dont une dĂ©pendance a Ă©chouĂ© est sautĂ©e sans consulter le manager.
Ce que la crew mĂ©morise (memory: true) : la sortie que le manager a acceptĂ©e, une fois, sous l'agent auquel la tĂąche a Ă©tĂ© assignĂ©e â jamais un essai rejetĂ©. Chaque essai s'exĂ©cute avec SimpleExecutionContext.StoreResultInMemory Ă faux (il rappelle quand mĂȘme les souvenirs de la crew : il rĂ©pond Ă la tĂąche), et la stratĂ©gie range la sortie acceptĂ©e via IMemoryCoordinator. Rien n'est rangĂ© quand le manager rejette les trois essais, ni quand le travailleur Ă©choue ; une revue qui Ă©choue vaut approbation, et cette sortie est alors rangĂ©e. Voir SystĂšme de mĂ©moire.
Mécanisme interne
ââ Manager (LLM de la crew) âââââ
â AssignTaskAsync() â
â ReviewOutputAsync() â
ââââââââââŹââââââââââââââââââââââââ
â
ââââââââââââââââŒâââââââââââââââ
⌠⌠âŒ
Worker A Worker B Worker C
(choisi)
â
âŒ
Sortie â Revue â approuvĂ©e ? â oui â tĂąche suivante
â non â rĂ©-exĂ©cution (max 2), puis [NEEDS REVISION]
Classes clés : HierarchicalProcessStrategy, IManagerAgent, LlmBasedManager, TaskAssignment (TaskId, AssignedAgent, Reason, AssignedAt)
Interface IManagerAgent (Orkeon.Application.Interfaces) :
AssignTaskAsync(task, availableAgents, context, llm, cancellationToken)âTaskAssignmentReviewOutputAsync(output, originalTask, llm, cancellationToken)âbool(approuvĂ©e ou non) ; le jeton est celui du run : Ctrl+C,RunTimeoutet/stoparrĂȘtent une revue
llm est le ManagerLlm que la stratĂ©gie a rĂ©solu pour le run (ManagerLlmResolver) : le client de chat que le manager interroge, le modĂšle qu'il demande, et son nom dans le journal (provider:<nom> ou profile:<nom>). Chacun de ses appels attend d'abord son tour dans la fenĂȘtre maxRpm de l'agent manager et dans celle de la crew.
Configuration YAML
name: "delivery-team"
goal: "Démo hiérarchique"
process: hierarchical
managerAgent: lead # la clé de l'agent manager sous agents: (il n'existe pas de clé manager_llm)
llm: # LLM par défaut de la crew, appliqué aux agents qui n'en ont pas
model: gpt-4o
agents:
lead:
role: "Tech Lead"
goal: "Coordonner la livraison"
llm: # le manager assigne et revoit sur ce LLM :
profile: claude # un des profils de l'hĂŽte (Llm:Profiles:claude),
model: claude-sonnet-5 # sur ce modÚle (non précisé, le gpt-4o de la crew s'appliquerait)
dev:
role: "Développeur senior"
goal: "Ăcrire le code de production"
qa:
role: "Ingénieur QA"
goal: "Tester et valider"
Avantages
- Allocation intelligente : le manager choisit le worker le plus adapté à chaque tùche
- ContrÎle qualité intégré : boucle de revue automatique
- Traçabilité : chaque assignation porte une justification (
TaskAssignment.Reason)
Inconvénients
- Surcoût LLM : un appel d'assignation + un à trois appels de revue par tùche, en plus des workers
- Goulot d'étranglement : tout passe par le manager (pas de parallélisme)
- Révisions fixes : 3 revues par tùche, en dur
Quand l'utiliser
- Revue de code (le manager assigne le relecteur le plus compétent)
- Projets aux spécialistes hétérogÚnes (dev, QA, design, rédaction)
- Situations oĂč la qualitĂ© prime sur la vitesse
Quand ne pas l'utiliser
- TĂąches homogĂšnes (le round-robin suffit)
- Contraintes strictes de coût LLM
- Workflows à haute fréquence (le manager est un goulot)
3. Parallel â Vagues de dĂ©pendances
Principe
Les tĂąches sont groupĂ©es en vagues de dĂ©pendances. Une vague contient toutes les tĂąches dont les dependencies dĂ©clarĂ©es sont dĂ©jĂ satisfaites ; ses tĂąches s'exĂ©cutent en concurrence (Task.WhenAll), et la vague suivante dĂ©marre quand elles sont toutes terminĂ©es, en lisant leurs sorties comme contexte. Une crew qui ne dĂ©clare aucune dĂ©pendance forme une seule vague â un fan-out Ă plat.
- Une dépendance qui nomme une tùche absente de la crew compte comme satisfaite.
- Un cycle de dépendances est refusé : l'exécution échoue en nommant les tùches prises dedans.
- Une tĂąche Ă©chouĂ©e n'arrĂȘte pas ses voisines de vague ; ses dĂ©pendantes des vagues suivantes sont sautĂ©es, et la crew Ă©choue en nommant chaque tĂąche Ă©chouĂ©e ou sautĂ©e.
- Il n'y a pas de plafond de concurrence : toutes les tĂąches d'une vague appellent leur LLM en mĂȘme temps.
- Le
asyncExecution: trued'une tĂąche est acceptĂ© et ne change rien : sa vague tourne dĂ©jĂ en mĂȘme temps.
Mécanisme interne
Vague 1 âââŹââ TĂąche A â Agent 1 âââ
âââ TĂąche B â Agent 2 ââ†(concurrentes)
âŒ
Vague 2 ââââââ TĂąche C (dĂ©pend de A, B) â lit A + B â rĂ©sultat final
Classes clés : ParallelProcessStrategy, TaskAgentSelector
Configuration YAML
name: "market-scan"
goal: "Démo parallÚle"
process: parallel
tasks:
france:
description: "Analyser le marché français"
expectedOutput: "Rapport France"
germany:
description: "Analyser le marché allemand"
expectedOutput: "Rapport Allemagne"
synthesis:
description: "Comparer les deux marchés"
expectedOutput: "SynthĂšse comparative"
dependencies: [france, germany] # deuxiĂšme vague, lit les deux rapports
Avantages
- Vitesse : temps total = somme de la tĂąche la plus longue de chaque vague
- Simplicité : aucune coordination au-delà des dépendances déclarées
- Isolation : l'échec d'une tùche n'affecte pas ses voisines de vague
Inconvénients
- Ordonnancement grossier : une tùche attend toute sa vague, pas seulement ce qu'elle a déclaré
- Pics de consommation d'API : toutes les requĂȘtes LLM d'une vague partent en mĂȘme temps (rate limiting)
- Pas de retry sauf si la tùche le demande : une tùche échouée sans
retry:fait échouer la crew, et saute ce qui en dépend
Quand l'utiliser
- Analyses multi-marchés ou multi-sources indépendantes
- Génération de contenu en lot (un article par marché, par langue)
- Un fan-out suivi d'une synthĂšse : les collecteurs tournent ensemble, la synthĂšse les lit
Quand ne pas l'utiliser
- Relance de tĂąches instables (donnez Ă la tĂąche un
retry:, dans n'importe quel mode) - API au rate limiting strict
4. Consensual â Vote et consensus
Principe
Pour chaque tĂąche, chaque agent de la crew l'exĂ©cute (en concurrence). Puis chaque agent remplit un bulletin : il classe les rĂ©ponses rĂ©ussies des autres agents, anonymisĂ©es sous des Ă©tiquettes (A, B, âŠ). L'IVotingStrategy configurĂ©e dĂ©pouille les bulletins. Si aucun consensus n'est atteint et que EnableDiscussion est actif, un nouveau round a lieu oĂč chaque agent voit les rĂ©ponses prĂ©cĂ©dentes des autres (une variable de contexte discussion_context). AprĂšs MaxVotingRounds rounds sans consensus, la FallbackStrategy tranche.
Mécanisme interne
TĂąche N âââŹââ Agent A â rĂ©ponse A âââ âââ A classe les rĂ©ponses de B, C âââ
âââ Agent B â rĂ©ponse B âââŒââ Ă©tiquettes A,B,C âŒââ B classe les rĂ©ponses de A, C âââŒââ DĂ©pouillement ââ Consensus ? ââ oui â rĂ©ponse gagnante
âââ Agent C â rĂ©ponse C âââ âââ C classe les rĂ©ponses de A, B âââ â
non
â
Round suivant (avec discussion_context)
â
Rounds Ă©puisĂ©s â FallbackStrategy
Enregistrement : AddOrkeonConsensus() (Orkeon.Infrastructure.DependencyInjection) lie ConsensualProcessOptions Ă la section Orkeon:Consensus, enregistre IVotingStrategyFactory â VotingStrategyFactory et l'IVotingStrategy construite Ă partir du ConsensusType configurĂ© (singletons, TryAdd), IBallotCollector â AgentBallotCollector (scoped), ainsi que ConsensualProcessStrategy (scoped). AddOrkeonInfrastructure() l'appelle dĂ©jĂ â ne l'appelez vous-mĂȘme que dans un hĂŽte qui n'utilise pas AddOrkeonInfrastructure() ; enregistrer votre propre IVotingStrategy ou IBallotCollector avant lui remplace celui par dĂ©faut.
Classes clés : ConsensualProcessStrategy, IBallotCollector / AgentBallotCollector, BallotRequest, BallotCandidate, Ballot, IVotingStrategy, IVotingStrategyFactory / VotingStrategyFactory, Vote, VoteResult, VotingOptions, ConsensualProcessOptions, ConsensusFallback
Comment un bulletin est formé
- Candidats : seules les exĂ©cutions rĂ©ussies. Une exĂ©cution en Ă©chec n'est jamais candidate â son agent vote quand mĂȘme, sur toutes les rĂ©ponses. Une rĂ©ponse rĂ©ussie seule est retenue sans bulletin ; quand toutes les exĂ©cutions d'un round ont Ă©chouĂ©, la tĂąche Ă©choue avec l'erreur des agents, sans round de plus.
- Anonymisés : les réponses portent les étiquettes
A,B, ⊠dans un ordre mĂ©langĂ© par tĂąche et par round (dĂ©terministe : la mĂȘme exĂ©cution donne les mĂȘmes Ă©tiquettes). Le votant ne voit ni le rĂŽle ni l'identifiant des auteurs : il vote pour la rĂ©ponse, pas pour l'agent. - Pas de vote pour soi : un agent classe les rĂ©ponses des autres agents, jamais la sienne. La part d'un choix est donc comptĂ©e parmi les bulletins qui pouvaient le dĂ©signer (
Vote.OwnChoice) : trois agents qui rendent la mĂȘme rĂ©ponse atteignentMajority,SuperMajorityetUnanimityau premier round. - Qui le remplit : l'agent votant lui-mĂȘme, via
IAgentExecutionServiceâ sa propre configuration LLM, et ses jetons comptĂ©s dans la tĂ©lĂ©mĂ©trie de la tĂąche. On lui demande un objet JSON (format de rĂ©ponsejson_object) :{"ranking": ["B", "A"], "abstain": false, "confidence": 0.8, "justification": "âŠ"}. Une rĂ©ponse qui n'est pas cet objet, un classement qui ne nomme aucune Ă©tiquette proposĂ©e, une exĂ©cution de bulletin en Ă©chec ou"abstain": trueest une abstention : elle est journalisĂ©e et ne fait jamais Ă©chouer la tĂąche. - Ce qui est comptĂ© :
Majority,SuperMajority,UnanimityetWeightedConsensuscomptent le premier choix ;BordaCountcompte le classement entier. Laconfidencedu bulletin est lue avecUseWeightedVotes. - ĂgalitĂ©s : une Ă©galitĂ© en tĂȘte n'est pas un consensus. Deux agents ne peuvent dĂ©signer que l'autre, leur vote est donc toujours Ă Ă©galitĂ© â une crew consensuelle a besoin de trois agents ou plus pour trancher par le vote.
- Le manager : le
managerAgentd'une crew (.manager(agent)en.ork.ts,CrewBuilder.WithManageren C#) ne rĂ©pond ni ne vote ; il arbitre seulement enManagerDecision. Sous un autre repli âAcceptBestScore, le dĂ©faut, ouFailâ il ne dĂ©cide rien, et le run le dit par un avertissement Ă son dĂ©but qui nomme l'agent et le repli de l'hĂŽte : posezOrkeon:Consensus:FallbackStrategy: ManagerDecision, ou retirezmanagerAgent:pour que l'agent rĂ©ponde et vote. Une crew consensuelle ne lit pas de LLM manager :WithManagerLlm(C#) est refusĂ©.
Replis, aprĂšs MaxVotingRounds rounds sans consensus :
AcceptBestScoregarde la rĂ©ponse que le dernier dĂ©pouillement a placĂ©e en tĂȘte, sans rien relancer. Quand aucun bulletin de ce round n'a dĂ©signĂ© de rĂ©ponse (tous les votants se sont abstenus), la tĂąche Ă©choue.ManagerDecision: l'agent manager de la crew classe les rĂ©ponses du dernier round, anonymisĂ©es comme les pairs les ont vues, et son premier choix est retenu ; s'il s'abstient, la tĂąche Ă©choue. Une crew sans agent manager est refusĂ©e au lancement, avant qu'aucun agent ne s'exĂ©cute, avec un message qui nomme la correction (le repli est un rĂ©glage d'hĂŽte : le validateur YAML ne le voit pas).Failfait Ă©chouer la tĂąche (« Consensus could not be reached for task ⊠»).
Le rĂ©sultat retenu est celui de la tĂąche : s'il est en Ă©chec, la crew Ă©choue et les dĂ©pendantes de la tĂąche sont sautĂ©es ; les tĂąches qui n'en dĂ©pendent pas s'exĂ©cutent quand mĂȘme.
Ce que la crew mĂ©morise : la rĂ©ponse retenue, une fois, sous l'agent qui l'a Ă©crite â jamais une candidate que le vote a Ă©cartĂ©e, jamais un bulletin. Les candidates et les bulletins s'exĂ©cutent avec SimpleExecutionContext.StoreResultInMemory Ă faux (AgentBallotCollector le met Ă faux pour tout bulletin qu'il fait voter), et la stratĂ©gie range la rĂ©ponse retenue via IMemoryCoordinator ; une tĂąche sans rĂ©ponse retenue ne range rien. Une candidate rappelle les souvenirs de la crew avant de rĂ©pondre â elle rĂ©pond Ă la tĂąche â et un bulletin non (RecallFromMemory Ă faux). Si le rangement Ă©choue, la rĂ©ponse retenue reste le rĂ©sultat de la tĂąche et l'Ă©chec est un avertissement, comme dans les autres modes. Voir SystĂšme de mĂ©moire.
CoĂ»t : un round coĂ»te N exĂ©cutions plus N bulletins â un appel LLM court par votant, dont le prompt contient les rĂ©ponses soumises au vote : son entrĂ©e croĂźt avec N Ă la longueur des rĂ©ponses (une rĂ©ponse longue est tronquĂ©e pour tenir dans une description de tĂąche). Trois agents d'accord coĂ»tent 3 exĂ©cutions + 3 bulletins par tĂąche. Une tĂąche qui n'atteint jamais le consensus coĂ»te MaxVotingRounds Ă (N + N) appels, plus un bulletin du manager en ManagerDecision ; AcceptBestScore ne relance rien. Les variables d'entrĂ©e de la crew atteignent chaque exĂ©cution et chaque bulletin ; les sorties gagnantes des tĂąches prĂ©cĂ©dentes sont transmises en contexte.
name: review-board
process: consensual
managerAgent: chair # l'arbitre sous FallbackStrategy: ManagerDecision (inactif, avec un avertissement, sous un autre repli)
Types de consensus disponibles
Le mĂ©canisme de vote est sĂ©lectionnable par configuration : Orkeon:Consensus:VotingOptions:ConsensusType (appsettings.json .NET) choisit la stratĂ©gie via IVotingStrategyFactory. DĂ©faut : Majority. Chaque type exige aussi le quorum (QuorumPercent) et une seule rĂ©ponse en tĂȘte ; une part est comptĂ©e parmi les bulletins qui pouvaient dĂ©signer la rĂ©ponse.
| Type | Stratégie résolue | RÚgle de consensus | Seuil par défaut |
|---|---|---|---|
Majority |
MajorityVotingStrategy |
Part en tĂȘte strictement supĂ©rieure Ă 50 % | 50 % |
SuperMajority |
SuperMajorityVotingStrategy |
Part en tĂȘte â„ ConsensusThreshold |
66,7 % |
Unanimity |
UnanimityVotingStrategy |
Chaque bulletin qui pouvait désigner le gagnant l'a désigné | 100 % |
WeightedConsensus |
WeightedConsensusStrategy |
Poids du rĂŽle (RoleWeights) Ă confiance, part au-dessus de ConsensusThreshold |
66,7 % |
BordaCount |
BordaCountStrategy |
Meilleur score de Borda sur les classements complets ; pas de consensus en cas d'Ă©galitĂ© en tĂȘte | N/A |
Configuration (.NET, section Orkeon:Consensus)
{
"Orkeon": {
"Consensus": {
"MaxVotingRounds": 3,
"VotingOptions": {
"ConsensusType": "SuperMajority",
"ConsensusThreshold": 75,
"UseWeightedVotes": true,
"QuorumPercent": 50,
"AllowAbstention": true
},
"EnableDiscussion": true,
"FallbackStrategy": "AcceptBestScore",
"RoleWeights": {
"Senior Analyst": 2.0,
"Junior Analyst": 1.0
}
}
}
}
| Clé | Défaut | Effet |
|---|---|---|
MaxVotingRounds |
3 | Rounds avant le repli ; un round = N exécutions + N bulletins |
VotingOptions:ConsensusType |
Majority |
Stratégie de vote |
VotingOptions:ConsensusThreshold |
66,7 | Seuil de SuperMajority / WeightedConsensus, en pourcentage (0â100) â 75 % s'Ă©crit 75 |
VotingOptions:UseWeightedVotes |
false |
Poids Ă confiance du bulletin au lieu d'une voix par bulletin |
VotingOptions:QuorumPercent |
50 | Part minimale, en pourcentage, de bulletins exprimés (hors abstentions) parmi les votants ; en dessous, pas de consensus |
VotingOptions:AllowAbstention |
true |
false : une abstention compte comme un vote contre toutes les rĂ©ponses â elle reste au dĂ©nominateur de chaque part et rompt l'unanimitĂ© ; avec BordaCount, toute abstention empĂȘche le consensus |
EnableDiscussion |
true |
Les rounds aprÚs le premier voient les réponses des autres agents |
FallbackStrategy |
AcceptBestScore |
AcceptBestScore (la tĂȘte du dernier dĂ©pouillement, rien n'est relancĂ©), Fail, ManagerDecision (l'agent manager de la crew choisit ; obligatoire) |
RoleWeights |
vide | RĂŽle â poids, lu par WeightedConsensus |
Avantages
- Plusieurs tentatives indépendantes par tùche, exécutées en concurrence
- Un vote sur les réponses : chaque agent classe les réponses anonymisées des autres ; une tentative en échec n'est jamais retenue
- Vote configurable : 5 stratégies, quorum, abstention, pondération par rÎle
- Discussion : les agents voient les réponses des autres entre les rounds
Inconvénients
- Coût LLM élevé : N exécutions + N bulletins par tùche et par round (+ un bulletin du manager en
ManagerDecision) - Les juges sont des LLM : un bulletin est l'avis d'un modÚle ; un angle mort partagé par les modÚles de tous les agents n'est pas corrigé par le vote
- Deux agents sont toujours à égalité : le vote tranche à partir de trois agents
- Complexité de configuration : beaucoup de paramÚtres
Quand l'utiliser
- TĂąches oĂč des tentatives indĂ©pendantes de plusieurs agents valent leur coĂ»t
- Crews oĂč l'Ă©chec d'un agent doit ĂȘtre absorbĂ© par les autres (une rĂ©ponse en Ă©chec n'est jamais candidate)
Quand ne pas l'utiliser
- Tùches factuelles à réponse unique
- Contraintes de budget LLM (multiplié par 2 à N agents à R rounds : réponses et bulletins)
- Workflows à haute fréquence (trop lent)
5. Graph â Graphe d'Ă©tats avec circuit breaker
Principe
La crew s'exĂ©cute Ă travers un graphe d'Ă©tats typĂ© (StateGraph<CrewGraphState>) Ă un nĆud par tĂąche (ADR-018) : sans nĆuds ni arĂȘtes, les nĆuds sont enchaĂźnĂ©s dans l'ordre d'exĂ©cution, et les tentatives d'une tĂąche sont son propre retry: (appliquĂ© sous la stratĂ©gie), pas une boucle de son nĆud. Un circuit breaker Ă 3 mĂ©canismes borne la boucle. Le bloc graph: peut dĂ©clarer ses propres nĆuds et arĂȘtes â arĂȘtes conditionnelles sur les rĂ©ponses d'une tĂąche de dĂ©cision, et boucles (voir Orchestration par graphe).
Mécanisme interne
START âââ tĂąche 1 âââ tĂąche 2 âââ ⊠âââ derniĂšre tĂąche âââ END
Classes clés :
StateGraph<TState>â DĂ©finition du graphe (nĆuds + arĂȘtes fixes et conditionnelles)GraphRunner<TState>â Moteur d'exĂ©cution avec circuit breakerGraphProcessStrategyâ ImplĂ©mentation deIProcessStrategyCircuitBreakerPolicyâ Limites (le record partagĂ© avec la FSM)CrewGraphStateâ Ătat typĂ© qui traverse le graphe
CrewGraphState â PropriĂ©tĂ©s de l'Ă©tat
| Propriété | Type | Description |
|---|---|---|
ApplicationOutputs / DomainResults |
IReadOnlyList<âŠ> |
Sorties accumulées, une par tentative |
TotalTokensUsed |
int |
Tokens consommés (propagés dans les métadonnées de CrewOutput sous totalTokens) |
PromptTokensUsed / CompletionTokensUsed |
int |
Ventilation prompt/complétion (0 quand le fournisseur ne la rapporte pas) |
CacheHitTokensUsed / CacheMissTokensUsed |
long |
Ventilation du cache de prompt (0 si non rapportée) |
AgentIndex |
int |
Curseur round-robin des tĂąches sans agent |
Circuit breaker â 3 mĂ©canismes de protection
| Mécanisme | Calculé (défaut) | Preset Strict | Preset Default | Preset Permissive |
|---|---|---|---|---|
MaxTransitions (exĂ©cutions de nĆuds) |
2 Ă visites + 1 | 50 | 100 | 1000 |
MaxStateVisits (visites d'un nĆud) |
somme de 1 + retries | 5 | 10 | 50 |
MaxTotalDuration |
celle du preset (10 min en Strict) | 10 min | 30 min | 2 h |
Chaque entrĂ©e dans un nĆud est une visite de ce nĆud, comptĂ©e par nĆud (maxVisits). Sans maxVisits / maxTransitions explicites, les deux sont calculĂ©s depuis la crew : la somme sur les tĂąches de 1 + retries visites (les tentatives du retry: de chaque tĂąche ; tĂąches Ă (1 + retries) quand elles sont pareilles) â une borne large : un nĆud n'est visitĂ© qu'une fois, ses tentatives ont lieu dans la visite â et deux fois plus une transitions ; une crew saine n'est donc jamais coupĂ©e, quelle que soit sa taille, et une vraie boucle dĂ©clenche encore le disjoncteur. Une valeur explicite (dans le bloc graph:) l'emporte ; le preset (circuitBreakerPreset, Strict par dĂ©faut) ne fournit plus que ce qui n'est pas calculĂ©, Ă commencer par la durĂ©e totale. Le quatriĂšme mĂ©canisme de la FSM, le timeout par Ă©tat, n'est pas vĂ©rifiĂ© par le runner du graphe. Un disjoncteur dĂ©clenchĂ© renvoie un CrewOutput en Ă©chec (« Graph execution stopped by circuit breaker: ⊠») avec les sorties produites jusque-lĂ .
Configuration YAML
name: "review-loop"
goal: "Démo graphe"
process: graph
graph:
nodes: # facultatif : sans nĆuds ni arĂȘtes, un nĆud par tĂąche
- { id: write, task: write }
- { id: review, task: review } # une tĂąche de dĂ©cision : des arĂȘtes en partent selon ses rĂ©ponses
- { id: publish, task: publish }
edges:
- { from: write, to: review }
- { from: review, to: write, when: { review.verdict: [revise] } }
- { from: review, to: publish } # sans `when` : le sinon
- { from: publish, to: END }
circuitBreakerPreset: "strict" # ou "default", "permissive" â fournit la durĂ©e
# Surcharges individuelles possibles (visites et transitions sont calculées sinon) :
maxTransitions: 75
maxVisits: 20
maxTotalDurationSeconds: 1800
Une boucle est une arĂȘte qui revient sur un nĆud ; maxVisits la borne. Voir l'orchestration Graph et le schĂ©ma YAML pour les rĂšgles (une arĂȘte « sinon » par dĂ©cision, ni when: ni dependencies: au niveau tĂąche Ă cĂŽtĂ© de nĆuds).
Avantages
- Retry : le
retry:propre d'une tùche s'exécute avant que la suivante démarre, comme dans tous les modes - Sûreté : un circuit breaker borne les exécutions, les visites et la durée
- Observabilité : événements
OnNodeEntered/OnNodeCompleted/OnCircuitBroken, journalisĂ©s par la stratĂ©gie ; un Ă©vĂ©nement de rungraph.node.enteredpar nĆud entrĂ© - Bornes Ă la taille de la crew : visites et transitions calculĂ©es depuis le nombre de tĂąches et les retries
Inconvénients
- Durée par défaut de 10 minutes : la
MaxTotalDurationdu preset Strict borne encore le run â relevezmaxTotalDurationSecondspour une crew longue - Routage YAML sur dĂ©cisions uniquement : une arĂȘte conditionnelle quitte une tĂąche de dĂ©cision sur ses rĂ©ponses ; une fonction de routage exige l'API C#
StateGraph<TState>
Quand l'utiliser
- Pipelines aux Ă©tapes instables qui mĂ©ritent d'ĂȘtre relancĂ©es (web scraping, API instables)
- ExĂ©cutions qui doivent ĂȘtre bornĂ©es en nombre d'exĂ©cutions et en durĂ©e
Quand ne pas l'utiliser
- Pipelines linĂ©aires simples sans Ă©tape qui mĂ©rite d'ĂȘtre relancĂ©e (Sequential)
- Tùches indépendantes (Parallel)
Voir aussi : Orchestration Graph pour tous les détails.
6. Autonomous â Auto-organisation avec budget
Principe
Pour chaque tĂąche, le LLM manager (LlmBasedManager, comme en Hierarchical â sur le fournisseur que pose CrewBuilder.WithManagerLlm en C#, sinon sur le profil par dĂ©faut de l'hĂŽte : une crew autonome n'a pas d'agent manager, et managerAgent: est refusĂ© au chargement) choisit l'agent qui la rĂ©clame. Quand l'exĂ©cution de cet agent Ă©choue et que l'agent autorise la dĂ©lĂ©gation, la tĂąche est dĂ©lĂ©guĂ©e Ă un pair via le canal A2A (IAgentChannel), sous un budget enfant dĂ©rivĂ©. Sans pair dans la crew, l'Ă©chec est maintenu. Un budget multi-dimensionnel (5 axes) borne le run. L'API est expĂ©rimentale (ORKEXP002, voir les API expĂ©rimentales).
Mécanisme interne
ââââ AgentExecutionBudget (5 dimensions) ââââ
â appels d'outils · profondeur · durĂ©e â
â tokens · agents créés â
ââââââââââââââââââââŹââââââââââââââââââââââââââ
â
pour chaque tĂąche : Manager (LLM) ââ assigne âââ Agent A ââ exĂ©cute
â
échec + allowDelegation ?
â oui
âŒ
channel.RequestAsync("delegate") âââ premier autre agent
(budget enfant)
Classes clés :
AutonomousProcessStrategyâ StratĂ©gie d'orchestrationAgentExecutionBudgetâ Budget multi-dimensionnel (Domain)IAgentChannel/InMemoryAgentChannelâ Canal A2A requĂȘte/rĂ©ponseSpawnAgentToolâ CrĂ©ation dynamique d'agents (construit par l'hĂŽte, pas injectĂ© par la stratĂ©gie)BudgetExhaustedExceptionâ LevĂ©e quand un axe est Ă©puisĂ©
Budget multi-dimensionnel â 5 axes
| Dimension | Strict | Default | Permissive | Description |
|---|---|---|---|---|
MaxToolCalls |
8 | 15 | 50 | Appels d'outils ; la stratégie en compte un par tùche distribuée |
MaxDelegationDepth |
1 | 2 | 4 | Sauts de délégation ; le compteur, commun à la crew, n'est jamais décrémenté |
MaxTokensConsumed |
8 000 | 16 000 | 64 000 | Tokens imputés au budget (exécutions déléguées) |
MaxSpawnedAgents |
1 | 3 | 10 | Agents créés via SpawnAgentTool |
MaxWallTime |
2 min | 5 min | 15 min | Durée d'exécution maximale |
Une sixiÚme limite, MaxContextTokens (sans limite par défaut), compte les tokens en ne comptant le contexte qu'une fois et se rapporte sous la dimension Tokens ; la stratégie autonome ne la fixe jamais : le budget: YAML de la crew n'a pas de clé pour elle et le budget .ork.ts d'une crew autonome refuse contextTokens (voir Autonomous).
ICrewOrchestrationService exécute ce mode sous le budget de la crew (budget: en YAML) ; une crew qui n'en fixe aucun n'a ni plafond de tokens ni temps mural, et garde les limites structurelles de 50 tùches distribuées, 4 délégations et 10 spawns.
Budgets enfants : CreateChildBudget() donne au délégué l'allocation restante du parent sur chaque axe (un niveau de délégation en moins, au moins 1 appel d'outil et 100 tokens). Chaque budget enfant est une copie indépendante : deux délégués reçoivent chacun la totalité du reste.
Communication A2A
// RequĂȘte/RĂ©ponse (timeout par dĂ©faut : 30 s)
var request = AgentChannelRequest.Create(
from: analyst.Id,
to: researcher.Id,
intent: "find_data",
payload: "Statistiques du marché 2025");
var response = await channel.RequestAsync(request, timeout: TimeSpan.FromSeconds(30));
// Broadcast (aucune réponse attendue) vers les membres enregistrés pour cette crew
await channel.BroadcastAsync(analyst.Id, crew.Id, "Résultats disponibles", ct);
Configuration YAML
name: "research-team"
goal: "Démo autonome"
process: autonomous
budget: # facultatif ; chaque clé facultative, chacune 1 ou plus
tokens: 400000 # somme courante prompt + complétion ; aucune par défaut
wallTimeSeconds: 1800 # aucune par défaut
toolCalls: 80 # tùches distribuées ; 50 par défaut
Avantages
- Assignation pilotée par LLM : le manager associe chaque tùche à un agent
- DeuxiÚme chance : une tùche échouée est confiée à un pair
- Terminaison garantie : le budget borne le run â les tĂąches distribuĂ©es toujours, tokens et durĂ©e quand la crew les fixe
- Télémétrie du budget : les métadonnées de la crew portent la consommation de chaque axe
Inconvénients
- Expérimental :
ORKEXP002, la sémantique peut encore bouger - Non déterministe : les choix du manager varient d'une exécution à l'autre
- Budget épuisé = run écourté : les tùches restantes ne sont pas exécutées, et la crew échoue en nommant la dimension épuisée et chaque tùche qu'elle n'a pas atteinte
- Aucun plafond de tokens ni de durée par défaut : une crew qui doit tenir une dépense fixe
budget:
Quand l'utiliser
- Exploration (recherche, R&D, analyse exploratoire)
- Ăquipes hĂ©tĂ©rogĂšnes oĂč l'association tĂąche-agent n'est pas connue Ă l'avance
Quand ne pas l'utiliser
- Workflows déterministes et bien définis (Sequential ou Graph)
- Scénarios réglementaires exigeant une traçabilité complÚte du chemin d'exécution
Voir aussi : Orchestration Autonomous pour tous les détails.
Arbre de décision
Vos tùches ont-elles des dépendances entre elles ?
â
âââ NON
â âââ Voulez-vous que plusieurs agents tentent chaque tĂąche ?
â âââ OUI â Consensual
â âââ NON â Parallel
â
âââ OUI
âââ La concurrence suffit-elle â les tĂąches indĂ©pendantes ensemble, chaque vague aprĂšs ses dĂ©pendances ?
âââ OUI â Parallel (il s'exĂ©cute par vagues de dĂ©pendances)
âââ NON
âââ Le run doit-il suivre des arĂȘtes de dĂ©cision, ĂȘtre bornĂ©, ou confier une tĂąche Ă©chouĂ©e Ă un pair ?
â
âââ NON
â âââ Avez-vous besoin d'un manager qui assigne et revoit ?
â âââ OUI â Hierarchical
â âââ NON â Sequential
â
âââ OUI
âââ ArĂȘtes de dĂ©cision et bornes, ou un pair ?
âââ ArĂȘtes de dĂ©cision, bornĂ© â Graph
âââ Un pair, assignĂ© par LLM â Autonomous
Combinaisons et complémentarité
Les ProcessTypes sont exclusifs à l'échelle d'une crew, mais se combinent avec les autres briques :
Sequential/Graph + outils de délégation : dans ces deux modes, un agent avec allowDelegation: true reçoit delegate_work_to_coworker et ask_question_to_coworker, ce qui donne un comportement hiérarchique local sans manager.
Graph + FSM : GraphProcessStrategy et le moteur FSM partagent CircuitBreakerPolicy et ses presets. La FSM est un moteur Domain gĂ©nĂ©rique (orkeon forge tourne dessus) ; aucune stratĂ©gie ne fait passer une tĂąche par une machine Ă Ă©tats â la boucle d'agent borne chaque tĂąche.
DSL de scripting : une crew .ork.ts dĂ©clare son mode avec crewBuilder().process("âŠ") (les mĂȘmes six valeurs). La forme dĂ©clarative (globalThis.crew = crew) passe par les stratĂ©gies ci-dessus ; la forme procĂ©durale (await crew.run()) exĂ©cute les corps des agents dans l'ordre de dĂ©claration et se contente d'Ă©tiqueter le mode â voir Scripting.
SynthÚse coûts et performances
| ProcessType | Exécutions (N tùches, M agents) | Appels LLM supplémentaires | Latence | Prévisibilité |
|---|---|---|---|---|
| Sequential | N | â | ÎŁ(durĂ©es) | âââââ |
| Hierarchical | N Ă (1 Ă 3) | N assignations + N Ă (1 Ă 3) revues | ÎŁ(durĂ©es) Ă 1,5â3 | ââââ |
| Parallel | N | â | ÎŁ(tĂąche la plus longue de chaque vague) | ââââ |
| Consensual | N Ă M Ă rounds | N Ă M Ă rounds bulletins (+ N bulletins du manager en ManagerDecision) |
ÎŁ((max(durĂ©es) + max(durĂ©es des bulletins)) Ă rounds) | âââ |
| Graph | N Ă (1 + retries) | â | ÎŁ(durĂ©es des tentatives) | ââââ |
| Autonomous | N (+ dĂ©lĂ©gations) | N assignations | BornĂ©e par la durĂ©e maximale | ââ |
Références croisées
| Sujet | Document |
|---|---|
| Architecture et concepts fondamentaux | Vue d'ensemble |
| Fonctionnalités détaillées | YAML et Builders |
Schéma YAML (process, graph) |
Schéma YAML |
| FSM (moteur Domain générique) | ./fsm.md |
| Orchestration Graph | ./graph.md |
| Orchestration Autonomous | ./autonomous.md |
| Blueprint d'un nouveau ProcessType | ../guides/blueprint.md |