Table of Contents

🇬🇧 English version

YAML, Builders et CrewFactory

Voir aussi : Bootstrap · Schéma YAML de référence · Retour à l'index

Fluent Builders

Les trois entités principales sont construites via des builders fluides définis dans la couche Domain :

  • AgentBuilder (Orkeon.Domain.Agent) : configure rĂ´le, objectif, backstory, outils, contraintes d'exĂ©cution, templates de prompt (SystemTemplate remplace la section de rĂ´le par dĂ©faut du prompt système de l'agent, ResponseTemplate y est ajoutĂ© comme format de rĂ©ponse attendu, et PromptTemplate enveloppe le prompt de la tâche Ă  chaque {{ .Prompt }} et est refusĂ© par Build() sans cette marque), politique d'accès outils, et le fournisseur sur lequel tournent les tours de l'agent quand il porte le sien (.WithLlm(fournisseur) — Agent.Llm, comptĂ© comme le travail de l'agent ; un agent Microsoft Agent Framework par .WithAgentFrameworkAgent(agent)). Build() le refuse avec un profil de l'hĂ´te (.WithLlmConfig(LlmConfig.OnProfile(nom))) et, sur un fournisseur qui fait ses propres outils — un agent MAF —, avec .WithTool ou .AllowDelegation()
  • CrewTaskBuilder (Orkeon.Domain.Task) : configure description, rĂ©sultat attendu, prioritĂ©, dĂ©pendances, schĂ©ma JSON de sortie, mode async (.Async() — honorĂ© par une crew sĂ©quentielle, refusĂ© par CrewBuilder.Build() hors Sequential et Parallel), intervention humaine
  • CrewBuilder (Orkeon.Domain.Crew) : configure nom, objectif, process type, agents, tasks, planification (.Planning(), sur le fournisseur que pose .WithPlanningLlm(fournisseur) — refusĂ© sans .Planning()), mĂ©moire, callbacks, agents dynamiques, et le manager d'une crew hiĂ©rarchique — un agent (.Hierarchical(manager), .WithManager(agent)), ou un fournisseur Ă  lui (.WithManagerLlm(fournisseur), le manager_llm de CrewAI : le manager assigne et revoit dessus, la crew se passe alors d'agent manager et chaque agent travaille). Un agent manager est aussi l'arbitre d'une crew consensuelle ; un LLM manager distribue aussi les tâches d'une crew autonome. Build() refuse l'un ou l'autre dans un process qui n'en a pas

Chaque builder délègue en interne aux méthodes factory Agent.Create(), CrewTask.Create(), Crew.Create() et lève une BuilderValidationException si les champs obligatoires sont absents.

Les réglages de modèle d'un agent : WithLlmConfig(config) les pose en bloc ; les raccourcis Thinking(enabled, effort) et MaxOutputTokens(n) s'y fondent et, sur un agent qui n'en a pas, partent d'une configuration qui ne nomme aucun modèle (LlmConfig.OnProfile()) : l'agent tourne alors sur le modèle de l'hôte, quel que soit son vendeur. Pour épingler un modèle, partez de LlmConfig.Create(modèle) ; pour tourner sur l'un des profils nommés de l'hôte, de LlmConfig.OnProfile("claude"). Un plafond de tokens (max_tokens, MaxTokens) est un entier positif ; omettez-le pour garder le plafond hérité. Le chargement YAML, LlmConfig.with dans les scripts, Agent.Create et SetLlmOverride refusent une valeur de 0 ou moins.

Configuration YAML

Orkeon prend en charge la configuration complète des crews via YAML. Le loader YamlCrewDefinitionLoader (Orkeon.Infrastructure.Configuration) convertit les fichiers YAML en objets domaine.

Schéma de configuration (abrégé)

La structure YAML suit ce schéma :

# Schéma CrewYamlConfig — clés les plus utilisées (surface complète dans docs/architecture/yaml-schema.md :
# llm:/rag:/links:/mounts:/announce_mounts: au niveau crew, workingRoot:/filesystem:/knowledge: agent, decision:/when: tâche (voir docs/fr/architecture/decision-models.md), tools:/deliverable:/llm_override: tâche, llm thinking/responseFormat/cache)
name: string              # Identifiant de la crew ; portée de sa mémoire long terme (les crews d'un même nom la partagent)
goal: string              # Objectif (requis)
process: string           # "sequential" | "hierarchical" | "parallel" | "consensual" | "graph" | "autonomous"
verbose: bool             # default: false — chaque agent du run journalise ses tours (appels d'outils, résultats, réponses du modèle) en Information, catégorie Orkeon.Verbose
memory: bool              # default: false. true : range le résultat de chaque tâche et rappelle les plus proches avant chaque tâche (demande un embedder)
memoryProvider: string    # exige memory: true. "InMemory" | "Redis" | "Sqlite" | "ChromaDb" | "Pinecone" | "LanceDb" — le type ; la section hôte (Orkeon:Redis, …) donne la connexion ; absent : le magasin par défaut de l'hôte
planning: bool            # default: false. true : un plan pas à pas par tâche, écrit avant la première et lu par chaque tâche dans son prompt ; ne réordonne jamais les tâches
maxRpm: int               # default: aucun — au plus N requêtes au modèle par minute pour la crew, tous ses agents et son manager confondus ; une de plus attend son tour
budget: {tokens, wallTimeSeconds, toolCalls, delegationDepth, spawnedAgents}  # process: autonomous seulement ; default: aucun plafond de tokens ni de durée, 50 / 4 / 10
managerAgent: string      # La clé d'un agent. Requis si process = "hierarchical" : le manager, sur son propre bloc llm: ; facultatif si "consensual" : l'arbitre de ManagerDecision ; refusé par les autres process
mounts: [string]          # Racines virtuelles utilisées par la crew ("/output", ou "<id>|/output" pour épingler une entrée des settings)

agents:
  <agent_id>:             # Clé = identifiant unique de l'agent
    role: string          # RĂ´le de l'agent (requis)
    goal: string          # Objectif personnel de l'agent (requis)
    backstory: string     # Contexte et expertise (multi-ligne recommandé)
    tools: [string]       # Noms d'outils enregistrés dans IToolRegistry
    allowDelegation: bool # default: true — permet la délégation à d'autres agents
    maxIter: int          # default: 20 — les tours que l'agent peut prendre sur une tâche
    maxRpm: int           # default: aucun — au plus N requêtes au modèle par minute pour cet agent ; une de plus attend son tour
    maxExecutionTime: int # default: aucun — les secondes qu'une tâche peut prendre chez cet agent (alias max_execution_time ; 0 < valeur <= 4294967, environ 49,7 jours)
    verbose: bool         # default: false — logs détaillés pour cet agent (appels d'outils, résultats, réponses du modèle, en Information, catégorie Orkeon.Verbose)
    llm:
      profile: string     # Profil LLM de l'hôte (Llm:Profiles:<nom>) — absent = le fournisseur par défaut de l'hôte
      model: string       # Modèle LLM ("gpt-4", "claude-3-opus", etc.) — absent = le modèle propre du profil
      temperature: float  # Créativité (0.0-2.0) — absente = celle du profil, sinon rien n'est envoyé et le modèle applique la sienne
      maxTokens: int      # Limite de tokens en sortie

tasks:
  <task_id>:              # Clé = identifiant unique de la tâche
    description: string   # Description détaillée de la tâche (requis)
    expectedOutput: string # Format/contenu attendu en résultat (requis)
    agent: string         # Clé de l'agent assigné à la tâche (une clé inconnue fait échouer le chargement)
    dependencies: [string] # Clés des tâches prérequises (garantit l'ordre ; une clé inconnue fait échouer le chargement)
    asyncExecution: bool  # default: false — sequential : tourne pendant les tâches suivantes, une dépendante l'attend ; parallel : sans effet propre ; autres modes : true fait échouer le chargement
    humanInput: bool      # default: false — demande intervention humaine
    context: {key: value} # Données additionnelles de contexte
    tools: [string]       # Outils AJOUTÉS à ceux de l'agent pour cette tâche seulement — sans jamais les remplacer
    guardrails:           # Guardrails au niveau tâche (optionnel) — même forme qu'au niveau agent
      preset: string      # "analysis" | "strict" | "creative" — tout autre nom fait échouer le chargement
      header: string
      rules: [string]
      toolRules:
        <tool_name>: [string]

Un fournisseur par agent (profils)

Un hôte offre ses fournisseurs sous forme de profils nommés (Llm:Profiles:<nom> dans ses réglages, la section Llm étant celui par défaut — voir Configuration). Une crew en choisit un par son nom — au niveau crew (tous les agents), sur un agent, ou dans le llm_override d'une tâche (cette tâche seulement) ; le plus précis l'emporte, et profile: default ramène un agent ou une tâche au défaut de l'hôte. Un fichier de crew ne porte jamais ni clé ni URL.

llm:
  profile: deepseek          # niveau crew : tous les agents, sauf avis contraire
agents:
  planner:
    role: Planner
    goal: Plan the article
    llm:
      profile: claude        # cet agent tourne sur le profil « claude » de l'hôte…
      model: claude-opus-5   # …sur un autre modèle que celui du profil
  writer:
    role: Writer
    goal: Write the article  # hérite du profil « deepseek » de la crew, sur son propre modèle
tasks:
  review:
    description: Review the article
    expectedOutput: A review
    agent: writer
    llm_override:
      profile: claude        # cette tâche seule fait passer le rédacteur sur « claude »

Un profil que l'hôte ne définit pas fait échouer le chargement de la crew, et le message liste les profils offerts — exactement comme un outil inconnu. Un bloc llm: qui ne nomme pas de model tourne sur le modèle propre du profil (celui de l'hôte pour le profil par défaut), jamais sur un défaut du framework. Le manager d'une crew hiérarchique tourne sur le bloc llm: de son agent manager, comme tout agent (en C#, un fournisseur posé par WithManagerLlm l'emporte, puis celui que porte l'agent manager, WithLlm) ; le sous-système RAG tourne sur le profil que nomme Orkeon:Rag:LlmProfile ; le planificateur et le Guardian restent sur le profil par défaut (Configuration). En .ork.ts, le même choix s'écrit agentBuilder().llm(llm.profile("claude")) sur un agent et taskBuilder().withProfile("claude") sur une tâche.

Le tools: d'une tâche s'ajoute aux outils de son agent pour cette tâche seulement : un rédacteur qui détient file_read et exécute une tâche déclarant tools: [file_write] peut lire et écrire pendant cette tâche, et seulement lire pendant les autres. Il n'y a pas de bloc circuitBreaker: — une crew qui en écrit un est refusée au chargement. Ce qui borne une tâche à l'exécution, c'est la boucle de l'agent (maxIter, un arrêt après 3 erreurs d'outil identiques consécutives, et les reprises de validation de sortie) ; un run Graph est borné par graph: (ci-dessous).

Les guardrails peuvent être déclarés sur un agent (toutes ses tâches) et/ou sur une tâche (cette tâche seulement). Quand les deux existent, les deux s'appliquent — les règles de l'agent d'abord, puis celles de la tâche — injectées dans le prompt système de l'agent exécutant. Un preset autre que analysis, strict ou creative fait échouer le chargement, en nommant l'agent ou la tâche. Voir Schéma YAML — Configuration Guardrails.

Quand process: "graph" est utilisé, un bloc graph: supplémentaire décrit les nœuds et les arêtes du graphe d'état et le borne :

graph:
  start: string                 # facultatif : le premier nœud par défaut
  nodes: [{ id, task }]         # facultatif : absent = un nœud implicite par tâche
  edges: [{ from, to, when? }]  # `to: END` termine le run ; plusieurs depuis un nœud, dans l'ordre ; sans `when` = le sinon
  circuitBreakerPreset: string  # "strict" | "permissive" | "default" — défaut : strict
  maxTransitions: int           # Défaut : calculé, 2 × visites + 1
  maxVisits: int                # Visites d'un nœud — défaut : calculé, somme sur les tâches de 1 + leurs retries
  maxTotalDurationSeconds: int  # Durée totale en secondes (surcharge le preset)

Voir Orchestration Graph pour le détail complet.

Modèles YAML

Les modèles YAML incluent :

  • CrewYamlConfig (dĂ©finition complète d'une crew)
  • AgentYamlConfig (rĂ´le, objectif, backstory, outils, limites)
  • TaskYamlConfig (description, rĂ©sultat attendu, dĂ©pendances, outils, livrable, guardrails)
  • LlmYamlConfig (profil, modèle, tempĂ©rature, max tokens)
  • GraphYamlConfig (circuitBreakerPreset, surcharges — voir Orchestration Graph ; une tâche Ă©chouĂ©e est relancĂ©e par son propre retry:, voir Retry d'une tâche)

Il n'existe pas d'objet « configuration prédéfinie » au niveau du framework : un hôte compose ses réglages via AddOrkeonInfrastructure / AddOrkeonApplication et son appsettings.json.

Modes de chargement

Le loader YamlCrewDefinitionLoader prend en charge les modes ci-dessous. Il lit à travers le système de fichiers virtuel (IFileSystemService) : chaque chemin qu'il reçoit est donc un chemin virtuel sous un montage déclaré — /crews/... ci-dessous suppose un montage tel que ./crews:/crews:ro (ADR-008) ; un chemin disque ne trouve aucun montage.

Mode fichier unique : contient agents et tasks dans un seul fichier

// loader : ICrewDefinitionLoader (implémentation YamlCrewDefinitionLoader) résolu via DI
var config = await loader.LoadFromFileAsync("/crews/research_crew.yaml", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);

Mode multi-fichier : séparation agents.yaml, tasks.yaml, et crew.yaml dans un répertoire

var config = await loader.LoadFromDirectoryAsync("/crews/research/", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);
// Charge automatiquement : crew.yaml, agents.yaml, tasks.yaml

Mode répertoire par entité : les réglages de la crew dans config.yaml (ou crew.yaml), un agent par fichier sous agents/, une task par fichier sous tasks/. Le nom du fichier (sans extension) est l'identifiant de l'entité — c'est-à-dire la clé de dictionnaire utilisée dans les formats plats. LoadFromDirectoryAsync sélectionne ce mode automatiquement dès qu'un sous-répertoire agents/ ou tasks/ est présent.

crews/research/
├── config.yaml          # réglages de la crew (name, goal, process, llm, …) — ou crew.yaml
├── agents/
│   ├── researcher.yaml  # → agent "researcher"
│   └── writer.yaml      # → agent "writer"
└── tasks/
    ├── collect.yaml     # → task "collect"
    └── report.yaml      # → task "report"
// Même appel : la disposition est détectée automatiquement.
var config = await loader.LoadFromDirectoryAsync("/crews/research/", ct);
var crew = await crewFactory.CreateFromConfigAsync(config, ct);

Notes :

  • config.yaml est prĂ©fĂ©rĂ© Ă  crew.yaml quand les deux sont prĂ©sents ; un fichier de rĂ©glages absent lève FileNotFoundException (paritĂ© avec le mode plat).
  • Un dossier agents//tasks/ vide ou absent ne produit simplement aucun agent ni aucune task — l'erreur de validation « au moins un agent/une task » remonte alors via loader.Validate(config).
  • MĂ©langer les deux dispositions (par exemple agents.yaml et un rĂ©pertoire agents/) lève InvalidOperationException au lieu d'appliquer une prĂ©cĂ©dence silencieuse.
  • Les fichiers d'entitĂ© peuvent finir par .yaml ou .yml ; le mĂŞme nom sous les deux extensions lève InvalidOperationException (Keep one.).
  • Le fichier de rĂ©glages du dossier ne porte que les rĂ©glages de la crew : une clĂ© agents: ou tasks: y est refusĂ©e comme toute clĂ© qu'aucun modèle ne lit, avec son fichier, sa ligne et la clĂ© la plus proche. Les agents et les tasks sont les fichiers des deux dossiers.
  • Limite : les ancres YAML ne peuvent pas traverser les fichiers — chaque fichier est prĂ©traitĂ© indĂ©pendamment (c'Ă©tait dĂ©jĂ  le cas entre les trois fichiers plats).

Côté CLI, orkeon run <dossier> accepte directement ces répertoires — voir Trois façons d'exécuter Orkeon.

CrewFactory — Du YAML aux objets domaine

Le pipeline de création transforme la configuration YAML en objets domaine opérationnels via CrewFactory (Orkeon.Infrastructure.Configuration), qui implémente ICrewFactory (Orkeon.Application.Interfaces).

Pipeline de création

  1. YAML → CrewYamlConfig : Désérialisation YAML en modèles de configuration
  2. CrewYamlConfig → CrewConfiguration : Mapping des modèles YAML vers les DTOs application avec validation basique (les erreurs lèvent InvalidOperationException, les avertissements sont journalisés)
  3. Collections RAG : les collections déclarées par un bloc rag: sont ingérées (de façon incrémentale) — quand le sous-système RAG est enregistré ; sans lui, un Warning et aucune ingestion
  4. Résolution des outils : Noms d'outils (strings) résolus via IToolRegistry.GetToolByNameAsync(name) en instances IBaseTool
  5. Création des agents : Instances Agent construites avec AgentBuilder, les outils résolus et leur bloc llm: — chaque profil qu'un agent ou une tâche nomme doit être offert par l'hôte, sinon le chargement échoue en les listant
  6. Création des tasks : Instances CrewTask construites avec CrewTaskBuilder et dépendances validées
  7. Validation des dépendances : Détection des cycles (circular dependency detection) et validation de l'ordre
  8. Création de la Crew : Instance Crew construite avec CrewBuilder, process strategy appliquée
  9. Persistance : Agents, Tasks, Crew rangés dans les repositories — toujours, pour que ICrewOrchestrationService.KickoffAsync(crew.Id, …) les trouve
  10. Liens : l'identité de la crew et son bloc links: sont remis à l'ACL de l'EventHub (un bloc links: déclaré sans AddOrkeonEventHubAcl() journalise un Warning : rien ne l'applique)

Points d'entrée

CrewFactory expose trois méthodes publiques :

/// <summary>
/// Crée une Crew à partir d'une CrewConfiguration déjà désérialisée.
/// Utilisé après LoadFromFile/LoadFromDirectory.
/// </summary>
public async Task<Crew> CreateFromConfigAsync(
    CrewConfiguration config,
    CancellationToken ct = default)
{
    // Valide la config, résout les outils, crée agents/tasks/crew
}

/// <summary>
/// Crée une Crew directement à partir d'un fichier YAML.
/// Mode fichier unique (agents + tasks dans le mĂŞme fichier).
/// </summary>
public async Task<Crew> CreateFromFileAsync(
    string yamlFilePath,
    CancellationToken ct = default)
{
    // Désérialise YAML → CrewYamlConfig → appelle CreateFromConfigAsync
}

/// <summary>
/// Crée une Crew à partir d'un répertoire YAML.
/// Disposition par entité (config.yaml + agents/ + tasks/) ou plate crew.yaml + agents.yaml + tasks.yaml
/// </summary>
public async Task<Crew> CreateFromDirectoryAsync(
    string directoryPath,
    CancellationToken ct = default)
{
    // Charge la disposition du répertoire → appelle CreateFromConfigAsync
}

Résolution des outils

Les noms d'outils spécifiés dans agents[].tools[] sont résolus à la construction via IToolRegistry.GetToolByNameAsync(toolName). Le sort d'un outil manquant dépend de CrewFactoryOptions.StrictTools (clé Orkeon:CrewFactory:StrictTools) : les runners (orkeon run) le mettent à true par défaut et CrewFactory lève alors une exception listant les outils manquants ; le défaut bibliothèque est false — l'outil est sauté avec un log Warning et la crew se charge sans lui.

Exemple d'erreur (mode strict) :

Crew configuration references unknown tool(s): web_scraper, custom_analyzer. Available tools: file_read, file_write, http_api, ...