Référence YAML — Schéma complet
Ce document est la source unique de vérité pour le schéma YAML d'Orkeon. Les documents spécialisés (FSM, Graph, Autonomous) renvoient ici pour le schéma.
Schéma de configuration complet
La structure YAML suit ce schéma. Nommage des clés : le loader (YamlDotNetSerializer)
reconnaît les clés en camelCase (la forme canonique, celle qu'écrit YamlCrewExporter — voir
Export) et se rabat sur le snake_case pour la même propriété — expectedOutput et expected_output,
llm_override et llmOverride sont équivalents partout. Toute clé est lue ou refusée au
chargement : une clé qu'aucun modèle ne porte (ou une clé retirée) fait échouer le chargement avec
son fichier, sa ligne et son chemin, et la clé la plus proche (Did you mean 'expectedOutput'?) ;
CrewYamlKeyCheck s'exécute avant la désérialisation. Seuls les noms que vous choisissez restent libres :
les identifiants sous agents: et tasks:, les noms d'outils sous toolRules:, les noms de collections sous rag.collections:, les clés et
valeurs de context:, les noms de questions sous decision.questions: et decision.fallback:, les noms d'options sous le
choice: d'une question, et les clés de when:.
Une clé de fusion (<<:) est refusée, de même qu'une ancre sur une clé inconnue : partagez le texte
sous anchors:. Les mêmes modèles servent le format mono-fichier
et les formats multi-fichiers (crew.yaml + agents.yaml + tasks.yaml, ou config.yaml +
agents/ + tasks/) décrits dans YAML et Builders ;
un mapping anchors: de premier niveau (chaînes multi-lignes nommées) est développé avant le
parsing (YamlAnchorPreprocessor).
# Schéma complet CrewYamlConfig
name: string # Identifiant de la crew (requis) ; portée de sa mémoire long terme
goal: string # Objectif (requis)
process: string # "sequential" (défaut) | "hierarchical" | "parallel" | "consensual" | "graph" | "autonomous" — insensible à la casse ; une valeur inconnue fait échouer le chargement
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 : la crew range le résultat de chaque tâche et rappelle les plus proches avant chaque tâche (embedder requis au kickoff) ; false : rien n'est rangé ni rappelé
memoryProvider: string # Exige memory: true (refusé sinon). "InMemory" | "Redis" | "Sqlite" | "ChromaDb" | "Pinecone" | "LanceDb" — insensible à la casse (alias "in-memory", "chroma", "lance") ; un type inconnu fait échouer le chargement, en listant les types connus. Le TYPE seul : la connexion vient de la section hôte (Orkeon:Redis, Orkeon:Sqlite, …). Absent : le magasin par défaut de l'hôte (Memory:Provider)
planning: bool # default: false. true : avant la première tâche, un planificateur (le profil par défaut de l'hôte) écrit un plan pas à pas par tâche, que la tâche lit dans son prompt, dans chaque mode ; il ne change ni l'ordre ni les agents
maxRpm: int # default: aucun — au plus N requêtes au modèle par minute pour toute la crew, tous ses agents et son manager confondus (vagues parallèles comprises) ; une de plus attend son tour. Le max_rpm de CrewAI (max_rpm: est accepté). 0 ou moins fait échouer le chargement
budget: {tokens, wallTimeSeconds, toolCalls, delegationDepth, spawnedAgents} # process: autonomous seulement — voir Budget autonome plus bas ; default: aucun plafond de tokens ni de durée, 50 / 4 / 10
managerAgent: string # La clé d'un des agents de la crew (tout autre nom fait échouer le chargement, en les listant). Hiérarchique : le manager — requis (omis, le chargement échoue) ; il assigne et revoit sur son propre bloc llm:, profil et modèle. Consensual : l'arbitre du repli ManagerDecision (inactif, avec un avertissement au début du run, sous un autre repli). Tout autre process : refusé au chargement
graph: {…} # Mode Graph : nœuds, arêtes et réglages du circuit breaker (voir la section dédiée)
llm: # LLM par défaut de la crew, fusionné CHAMP PAR CHAMP sous le llm: propre de chaque agent (même forme que agents.<id>.llm)
profile: string # Profil LLM de l'hôte (Llm:Profiles:<nom>) pour tous les agents — inconnu → le chargement échoue en listant les profils de l'hôte
model: string
max_tokens: int # Positif ; omis = le plafond hérité, 0 ou moins fait échouer le chargement en nommant la crew
temperature: float
links: # ACL EventHub (optionnel) — à qui cette crew peut parler sur le hub
- to: string # Le name: de la crew cible, tel quel — ou "client:<nom>" pour un pair externe (p. ex. un front-end de bureau)
direction: string # "outbound" (défaut) | "inbound" | "bidirectional" (alias "both") — une valeur illisible écarte l'entrée avec un warning
allowed_topics: [string] # Omis ou vide = tous les topics
mounts: # Les racines virtuelles que la crew utilise (optionnel) — sélectionne et valide, ne restreint jamais
- /output # une racine qu'une entrée des settings (ou un --mount) doit fournir ; refusée en une ligne si rien ne le fait
- 01J9Z3K4M5N6P7Q8R9S0T1V2W3|/data # une racine épinglée à UNE entrée des settings par son identifiant, quand plusieurs la déclarent
announce_mounts: bool # default: true — chaque agent qui a un outil de fichiers liste ses chemins virtuels dans son prompt système (alias announceMounts) ; la clé propre d'un agent l'emporte
rag: # Configuration RAG au niveau crew (optionnel)
provider: string # Supprimée : le chargement la refuse et renvoie à Orkeon:Rag:Provider — le magasin est celui de l'hôte
collections:
<nom_collection>:
sources: [string] # Fichiers, globs, répertoires ou URL — relatifs au dossier de la crew sauf s'ils sont absolus — ingérés à la création de la crew
chunking: # Omis → les défauts du pipeline d'ingestion
strategy: string # default: "recursive"
max_tokens: int # default: 512 — tokens par chunk (×4 caractères)
overlap: int # default: 64 — recouvrement de tokens entre chunks
defaults:
profile: string # Le profil de récupération de chaque attachement de connaissance qui n'en nomme pas (voir Configuration Knowledge & RAG)
agents:
<agent_id>: # Clé = identifiant unique de l'agent
role: string # Rôle de l'agent (par défaut : la clé de l'agent)
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 (un nom inconnu fait échouer le chargement sous Orkeon:CrewFactory:StrictTools, le défaut des runners)
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 (en C# et en .ork.ts aussi). 0 ou moins fait échouer le chargement
maxRpm: int # default: aucun — au plus N requêtes au modèle par minute pour cet agent ; une de plus attend son tour. Le RateLimiting:AgentRequestsPerMinute de l'hôte le borne aussi, le plus strict l'emporte. 0 ou moins fait échouer le chargement
maxExecutionTime: int # default: aucun — les secondes qu'une tâche peut prendre chez cet agent (alias max_execution_time) ; 0 ou moins, ou plus de 4294967 (environ 49,7 jours), fait échouer le chargement, tout comme une limite sur le manager hiérarchique
permissionMode: string # default: aucun (Orkeon:Security:PermissionGate:DefaultMode) — default, acceptEdits, bypassPermissions, plan ou dontAsk (C# AgentBuilder.PermissionMode) : le mode que la permission gate lit pour les appels d'outil de cet agent, une fois Orkeon:Security:PermissionGate:Enabled à true ; toute autre valeur fait échouer le chargement
working_root: string # default: aucun — un chemin virtuel (alias workingRoot, C# AgentBuilder.WorkingRoot) sous un mount qui confine les outils fichier et shell_command de cet agent ; refusé au démarrage du run, en nommant la racine, si aucun mount ne la contient
filesystem: # default: aucun — les seuls chemins virtuels que les outils de cet agent peuvent toucher (C# AgentBuilder.FileSystem) ; chaque entrée réduit son mount, ne l'élargit jamais. Une liste : un chemin ou une map seuls font échouer le chargement en nommant l'agent ; sans valeur, ~ ou null, rien n'est déclaré
- string # un chemin : les droits du mount à cet endroit
- path: string # ou un chemin avec
access: string # "ro" | "rw" | "rwnd" — refusé au démarrage du run, en nommant l'agent et l'entrée, au-delà des droits du mount ou hors de tout mount ; une liste vide, une clé ou un accès inconnus font échouer le chargement
announce_mounts: bool # default: l'announce_mounts de la crew — liste les chemins virtuels et la racine de travail de cet agent dans son prompt système (alias announceMounts, C# AgentBuilder.AnnounceMounts)
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: # Omis (et pas de llm: de crew) → la section Llm des settings du runner
profile: string # Profil LLM de l'hôte (Llm:Profiles:<nom>) : le fournisseur de cet agent ; "default" = la section Llm
model: string # Identifiant du modèle LLM — omis → le modèle propre du profil
temperature: float # Envoyée quelle que soit sa valeur — omise = celle du profil, sinon rien n'est envoyé et le modèle applique la sienne
maxTokens: int # Plafond de tokens en sortie, positif — omis = le maximum documenté du modèle ; 0 ou moins fait échouer le chargement
topP: float # Nucleus sampling, envoyé quelle que soit sa valeur — omis = celui du profil, sinon rien n'est envoyé (Mistral écrit 1)
thinking: # Contrôle du raisonnement (gaté par capacité selon le provider)
enabled: bool
effort: string # "low" | "medium" | "high" | "xhigh" | "max", casse exacte — toute autre valeur fait échouer le chargement (un provider envoie le niveau le plus proche que son champ connaît)
budget_tokens: int # Honoré par Qwen et OpenRouter ; les autres providers émettent un warning
responseFormat: string # "text" (= défaut du provider) | "json_object" | "json_schema" — toute autre valeur est transmise telle quelle avec un warning
responseSchema: # Avec responseFormat: json_schema (un schéma seul implique json_schema)
name: string # default: "response"
schema: string # Le JSON Schema sous forme de chaîne JSON, p. ex. '{"type":"object"}'
strict: bool # default: true
cache: # Prompt caching explicite (Anthropic) ; désactivé tant qu'aucun breakpoint n'est demandé
system: bool # default: false
tools: bool # default: false
ttl: string # "5m" | "1h" ; omis = défaut du fournisseur. Sans system ni tools, il ne met rien en cache et fait échouer le chargement
guardrails: # Règles opérationnelles injectées dans le system prompt de l'agent (optionnel)
preset: string # "analysis" | "strict" | "creative" — tout autre nom fait échouer le chargement
header: string # En-tête de section — utilisé seulement sans preset (chaque preset apporte le sien)
rules: [string] # Règles globales numérotées
toolRules: # Règles rendues seulement quand l'agent possède l'outil ; un nom d'outil ignore la casse, et un outil écrit sous deux clés fait échouer le chargement
<tool_name>: [string]
knowledge: # Collections de connaissance (RAG) attachées à l'agent (optionnel) ; une clé inconnue d'une entrée est refusée, une valeur mal formée reste un warning
- string # Forme courte : nom de collection avec options par défaut
- collection: string # Forme longue (clé requise)
top_k: int # default: 5 — chunks retenus par requête
min_score: float # Score de pertinence minimal dans [0, 1]
profile: string # Le profil de récupération de cet attachement — sinon rag.defaults.profile, sinon Orkeon:Rag:Profile (voir Configuration Knowledge & RAG)
max_context_tokens: int # default: 2000 — plafond de tokens de contexte injectés
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é qui ne désigne aucun agent fait échouer le chargement, en listant les agents de la crew)
dependencies: [string] # Clés des tâches prérequises (garantit l'ordre ; une clé inconnue fait échouer le chargement, en listant les tâches de la crew ; un cycle aussi)
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
retry: # défaut : aucun — la tâche tourne une fois. Une tentative en échec rejoue la tâche ENTIÈRE (voir « Retry d'une tâche »)
attempts: int # obligatoire, 1 ou plus — exécutions au total, la première comprise
backoffMs: int # défaut : 0 — attente de base avant une nouvelle tentative, en millisecondes
backoff: string # "fixed" (défaut) | "exponential" (double à chaque retry, plafonné à 5 minutes)
humanInput: bool # default: false — demande intervention humaine ; avec le checkpoint la question est durable : le run peut s'arrêter dessus (sortie 75) et reprendre avec --input
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) — résolus comme ceux d'un agent : un nom inconnu fait échouer le chargement sous StrictTools
deliverable: # Contrat de fichier de sortie (ignoré sans path)
path: string # Chemin virtuel, p. ex. "/output/report.md"
source: string # "tool_call" (défaut — l'agent écrit le chemin lui-même et a besoin d'un outil qui écrit ce format ; le prompt nomme celui qu'il détient, celui du format d'abord ; le chargement avertit si aucun agent ne le peut) | "final_message" (le framework écrit la réponse finale) | "structured_output" (JSON écrit par le framework, contraint par le schéma en json_schema là où le fournisseur le déclare, en grammaire GBNF là où Llm:Grammar est allumé, et toujours vérifié au parsing) | "none" — toute autre valeur fait échouer le chargement
format: string # "markdown" (défaut) | "json" | "text"
sanitize: bool # default: true — retire les tokens de template en fin de texte (final_message)
schema_path: string # Chemin virtuel d'un fichier JSON Schema (structured_output exige lui ou schema_inline)
schema_inline: string # Le JSON Schema sous forme de chaîne JSON — alternative à schema_path
llm_override: # Surcharge LLM au niveau tâche (cascade crew → agent → tâche)
profile: string # Cette tâche tourne sur un autre profil LLM de l'hôte que celui de son agent
response_format: string # Mêmes valeurs que llm.responseFormat
response_schema: {name, schema, strict} # schema est une chaîne JSON
temperature: float
max_tokens: int # Positif ; omis = le plafond hérité, 0 ou moins fait échouer le chargement en nommant la tâche
top_p: float
thinking: {enabled, effort, budget_tokens}
cache: {system, tools, ttl} # Même forme que le cache: de l'agent — remplace le bloc de l'agent en entier ; un bloc sans point d'arrêt coupe le cache de l'agent pour cette tâche
guardrails: # Guardrails au niveau tâche, même forme que le bloc agent (optionnel)
preset: string # "analysis" | "strict" | "creative" — tout autre nom fait échouer le chargement
header: string
rules: [string]
toolRules:
<tool_name>: [string]
decision: # Fait de la tâche une tâche de décision : pas d'agent, répondue par le modèle de décision — voir Tâches de décision et conditions plus bas. Avec agent : refusé au chargement
questions: # Obligatoire, au moins une ; la clé est le nom de la question
<question>:
choice: {<option>: string} # Une option parmi 255 au plus, chacune avec sa description
score: [string] # Une échelle ordonnée de 10 niveaux au plus
noul: string # Une question oui/non : l'énoncé
instructions: string # Optionnel, pour choice et score
minConfidence: float # défaut : 0.5, dans [0, 1] — en dessous, une condition d'option ne sélectionne rien
state: [string] # Clés des tâches dont le modèle juge la sortie ; défaut : les sorties des dépendances qui ont tourné
longContext: bool # défaut : false — demande le contexte long du modèle
fallback: {<question>: string} # Réponses utilisées sans requête quand le circuit de décision est coupé
when: # Ne lance la tâche que si une tâche de décision a répondu comme écrit (une seule tâche de décision par when:)
<task>.<question>: [string] | ">= 0.7" # Une liste d'options (choice), ou un seuil : une probabilité (oui/non) ou une position de niveau (score)
<task>.<question>.<option>: ">= 0.25" # La probabilité d'une option d'un choice
<task>: otherwise # Seule : vaut quand aucune condition sœur sur cette tâche ne vaut
La validation a lieu
au chargement (CrewDefinitionValidator) : une crew exige un name, un goal, au moins un agent
(chacun avec un goal) et au moins une tâche (chacune avec une description et un
expectedOutput) ; des dependencies circulaires, un item de mounts: listé deux fois ou deux
identifiants qui sélectionnent la même racine font échouer le chargement. Une clé
circuitBreaker: aussi, à la racine comme sur une tâche : le bloc a été supprimé (voir « Supprimé :
circuitBreaker » plus bas), et le chargement nomme le bloc graph au lieu de l'ignorer. Le
asyncExecution: true d'une tâche aussi, hors process: sequential et process: parallel : les quatre
autres modes ordonnent leurs tâches eux-mêmes, et le chargement nomme chaque tâche qui le demande au lieu
d'ignorer le drapeau (voir Tâches asynchrones).
Un maxRpm de 0 ou moins — sur la crew ou sur un agent — et un maxIter de 0 ou moins font échouer le
chargement aussi, en nommant la crew ou l'agent : omettre maxRpm:, c'est n'avoir aucune limite, omettre
maxIter:, c'est le défaut (20). Un max_tokens de 0 ou moins — sur le llm de la crew, le llm d'un agent ou le
llm_override d'une tâche — fait échouer le chargement aussi, en nommant la crew, l'agent ou la tâche : omettre
la clé, c'est garder le plafond hérité. Les plafonds propres
de l'hôte sur les appels au modèle — qui bornent le maxRpm d'un agent, le plus strict l'emportant — sont
les réglages de RateLimiting.
Le maxExecutionTime (ou max_execution_time) d'un agent est un nombre entier de secondes : 0 ou moins, un décimal,
une valeur au-dessus du plafond (4294967 s, environ 49,7 jours) et une limite sur le managerAgent d'une crew
hiérarchique font échouer le chargement, en nommant l'agent. Une tâche qui dépasse sa limite se termine en
ExecutionTimeExceeded au plus tard à la fin de l'appel en cours ; le temps passé à attendre un humain ne compte pas.
Un retry: de tâche sans attempts, avec attempts sous 1, un backoffMs négatif, un backoff autre que fixed ou exponential, ou posé sur une tâche de décision, fait aussi échouer le chargement, en nommant la tâche et la clé (voir Retry d'une tâche).
Un message nomme un agent ou une tâche par sa clé — Agent 'researcher' must have a goal. —, une
configuration bâtie en code par son identifiant.
Tâches de décision et conditions
Une tâche qui porte un bloc decision: est une tâche de décision : elle n'a pas d'agent, ne fait
aucun appel LLM et n'écrit aucun texte. À l'exécution, elle envoie son état et toutes ses questions au
modèle de décision en une seule requête (voir
Modèles de décision), et sa sortie
est l'ensemble des réponses. Une tâche qui porte un bloc when: ne tourne que si une tâche de décision
a répondu comme écrit, et est sautée sinon.
agents:
reader: { role: Reader, goal: Read tickets }
engineer: { role: Engineer, goal: Fix defects }
finance: { role: Finance, goal: Handle refunds }
tasks:
ticket:
description: Read the support ticket
expectedOutput: A summary of the ticket
agent: reader
triage:
description: Sort the ticket
expectedOutput: The category and whether a refund is asked
dependencies: [ticket]
decision:
questions:
category:
choice:
bug: a defect in the product
feature: a request for a new capability
billing: a question about an invoice
refund_requested:
noul: the customer asks for a refund
minConfidence: 0.6
fix_bug:
description: Fix the defect or plan the feature
expectedOutput: A fix or a plan
agent: engineer
when:
triage.category: [bug, feature]
refund:
description: Handle the refund
expectedOutput: A refund decision
agent: finance
when:
triage.category: [billing]
triage.refund_requested: ">= 0.7"
manual_triage:
description: Route the ticket to a person
expectedOutput: A hand-over note
agent: reader
when:
triage: otherwise
summary:
description: Summarise what was done
expectedOutput: A short report
agent: reader
dependencies: [fix_bug, refund, manual_triage]
Le bloc decision:.
questionsest obligatoire et compte au moins une question. Une question déclare exactement un genre :choice(une table option vers description, 255 options au plus),score(une liste ordonnée de 10 niveaux au plus) ounoul(l'énoncé d'une question oui/non, le nom que Jev lui donne).instructionsest optionnel sur un choice et un score. Les noms de questions sont uniques.minConfidenceest le seuil de confiance, un nombre dans [0, 1] ; il vaut 0,5 par défaut.min_confidencese lit de la même façon, comme toute clé du fichier.stateliste les clés des tâches dont le modèle juge la sortie ; sans lui, le modèle lit les sorties des dépendances de la tâche qui ont tourné, dans l'ordre. Une tâche listée est ajoutée auxdependenciesde la tâche si elle n'y est pas.longContext(défautfalse) demande le contexte long du modèle ; il n'est jamais demandé de lui-même.fallbackassocie une question à la réponse utilisée quand le circuit de décision est coupé : une option d'un choice, un niveau d'un score,yesounod'un oui/non (mettez"no"entre guillemets, que YAML lit comme un booléen). Une question sans réponse de repli ne sélectionne aucune option. Voir le repli.- Une tâche de décision exige toujours une
descriptionet unexpectedOutputcomme toute tâche, et la crew exige toujours un agent, même si aucune tâche ne l'utilise.
Le bloc when:. Un when: nomme une seule tâche de décision ; chaque clause s'écrit <task>,
<task>.<question> ou <task>.<question>.<option>, où <task> est la clé de la tâche de décision.
Plusieurs clauses s'écrivent dans un même bloc et doivent toutes valoir. La grammaire :
| Clause | Vaut quand |
|---|---|
<task>.<question>: [a, b] |
La question est un choice, l'option choisie est dans la liste et la confiance est au moins égale à minConfidence. |
<task>.<question>: ">= 0.7" |
La question est un oui/non (sa probabilité d'un oui, dans [0, 1]) ou un score (le score pondéré du modèle sur les positions des niveaux, de 0 à n-1) et la comparaison vaut. Le seuil de confiance ne s'applique pas. |
<task>.<question>.<option>: ">= 0.25" |
La probabilité de cette option d'un choice satisfait la comparaison, même si l'option n'est pas la choisie. Le seuil de confiance ne s'applique pas. |
<task>: otherwise |
Aucune condition sœur sur cette tâche de décision ne vaut, y compris quand la confiance est sous le seuil. |
Un seuil est un opérateur (>=, >, <=, <) et un nombre, écrit comme une chaîne entre
guillemets : une probabilité dans [0, 1] sur un oui/non ou une option, une position de niveau de 0 au
nombre de niveaux moins un sur un score ("> 1.5" sur [low, medium, high] dépasse le niveau du
milieu). Plusieurs tâches dont les conditions valent pour une même décision tournent toutes (un
fan-out) ; une tâche qui dépend de plusieurs branches tourne quand au moins une d'elles a tourné. La
tâche de décision nommée par un when: est ajoutée aux dependencies de la tâche si elle n'y est pas.
Une tâche dont la condition ne vaut pas, ou dont toutes les dépendances ont été sautées par une
condition, est sautée : elle ne laisse aucune sortie, et la crew réussit quand même.
Où cela tourne. Les tâches de décision et when: sont pris en charge avec process: sequential,
parallel et graph. Les autres processus les refusent au chargement (Task 'triage' declares a decision or a condition, which the Hierarchical process does not support.) ; un équipage construit en
C# qui les atteint échoue avant sa première tâche avec le même message.
Ce qui est refusé au chargement. Une tâche est nommée par sa clé déclarée, la clé de la table YAML,
dans tous les messages, sous la forme Task '<clé>' <partie> … où la partie est decision,
decision.questions.<nom>, decision.fallback ou when. Le chargement échoue sur :
- une tâche qui a à la fois un
agent:et undecision:, une décision sans question, un choice de plus de 255 options, un score de plus de 10 niveaux, unminConfidencehors de [0, 1] ou qui n'est pas un nombre, unlongContextqui n'est pas un booléen ; - une question qui déclare plus d'un parmi
choice,scoreetnoul; - un repli qui nomme une question inconnue, ou une réponse que la question n'a pas ;
- un
when:sur une tâche qui n'est pas une tâche de décision, ou qui nomme une question ou une option inconnue, ou avec un seuil hors de sa plage (une probabilité dans [0, 1], une position de score de 0 à n-1) ou qui n'est pas écrit comme un opérateur et un nombre fini ; otherwiseécrit à côté d'autres clauses, une seconde tâcheotherwisesur une même tâche de décision, unotherwisesans condition sœur sur cette tâche de décision ;- une clause d'option avec une liste (
triage.category.bug: [bug]), qui n'accepte qu'une chaîne de seuil ; - une décision ou un
when:dans un processus autre que les trois ci-dessus.
Avec le circuit de décision coupé, l'exécution est aussi refusée avant sa première tâche quand une
tâche de décision n'a ni fallback ni tâche otherwise.
Configuration Guardrails
Les guardrails sont des règles opérationnelles rendues dans le system prompt de l'agent exécutant.
Ils peuvent être déclarés sur un agent (s'appliquent à toutes les tâches que l'agent exécute) et/ou
sur une tâche (s'appliquent uniquement à cette tâche). Quand les deux sont présents, les deux
s'appliquent — les guardrails de l'agent sont rendus d'abord, puis ceux de la tâche en section
séparée. preset (analysis / strict / creative) fournit un socle de règles de base ; les
rules/toolRules explicites sont fusionnées par-dessus, et les toolRules d'un outil donné ne sont
émises que si l'agent exécutant possède effectivement cet outil pour la tâche — ses propres outils
plus le tools: de la tâche. Un en-tête de preset prime sur un
header personnalisé. Un preset autre que ces trois — une faute de frappe — fait échouer le
chargement, en nommant l'agent ou la tâche par sa clé et les trois presets ; de même un outil écrit
sous deux clés de toolRules (file_write et File_Write) : un nom d'outil ignore la casse.
Configuration Knowledge & RAG
Deux blocs complémentaires. Le bloc crew rag: déclare les collections
(sources d'ingestion, chunking) et les défauts globaux. Le bloc agent knowledge: attache
des collections à un agent avec ses options de récupération. À l'assemblage du contexte
d'exécution, chaque collection attachée est interrogée avec l'entrée de la tâche par la moitié
retrieval du pipeline de son profil — le profile de l'attachement, sinon
rag.defaults.profile, sinon Orkeon:Rag:Profile — et les résultats sont injectés dans le
prompt utilisateur de l'agent sous forme d'extraits numérotés et cités
(IKnowledgeContextAugmenter, qui honore top_k, min_score et max_context_tokens). Les deux
moitiés exigent le sous-système RAG (AddOrkeonRag(configuration)), que tout hôte runner
enregistre (orkeon run sous toutes ses formes, orkeon-host) : à la création de la crew
(CrewFactory), les collections déclarées sont ingérées de façon incrémentale
(IRagCollectionsBootstrapper — une source inchangée n'est pas ré-embeddée ;
CrewFactoryOptions.PrepareRagCollections = false désactive l'étape, comme le fait
--validate). Sur un hôte sans le sous-système, un bloc rag: déclaré et les knowledge: de
chaque agent journalisent un warning et n'injectent rien. Le parsing du YAML lui-même ne
déclenche jamais d'ingestion. Le document store relève de l'hôte (Orkeon:Rag:Provider, voir
Pipeline RAG) ; une clé rag.provider est refusée au
chargement, avec la phrase qui renvoie à Orkeon:Rag:Provider.
Ce que veut dire une entrée de sources : un chemin qui ne commence pas par / est
relatif au dossier de la crew — /crew sous orkeon run crew.yaml ou un répertoire de crew,
donc ./data/faq.md à côté du fichier de crew est /crew/data/faq.md — et un chemin absolu est
un chemin virtuel (/kb/faq.md, un de vos montages). Un glob (*, **, ?) est développé à
travers le VFS comme le développent rag_ingest, orkeon rag ingest et rag.ingest ; un
répertoire vaut tous les fichiers qu'il contient ; une adresse http(s):// et un fichier simple
parviennent tels quels aux chargeurs. Un glob ou un répertoire qui ne donne aucun fichier, une
source relative d'une crew lue depuis une chaîne (pas de dossier auquel être relative) et un
glob hors de tout montage sont chacun un warning de chargement qui nomme la collection — la crew
se charge quand même ; un fichier absent est signalé par l'ingestion. Un fichier que deux
entrées nomment n'est ingéré qu'une fois.
Forme courte — attacher des collections avec les options par défaut :
rag:
collections:
produits:
sources: ["./data/catalogue/**/*.pdf", "./data/faq.md"]
agents:
support:
role: "Agent support client"
goal: "Répondre aux questions produits"
knowledge: [produits, procedures]
Forme longue — options de récupération par collection (mixable avec la forme courte dans la même liste) :
rag:
collections:
procedures:
sources: ["./docs/procedures/"]
chunking: { strategy: recursive, max_tokens: 512, overlap: 64 }
defaults: { profile: balanced }
agents:
expert:
role: "Expert métier"
goal: "Fournir des réponses sourcées"
knowledge:
- collection: procedures
profile: quality
top_k: 8
min_score: 0.35
max_context_tokens: 1500
Les clés acceptent snake_case (la forme utilisée ci-dessus) et camelCase. Une entrée knowledge malformée
(collection manquante, top_k non numérique, …) est ignorée ou dégradée avec un warning —
elle ne fait jamais planter le loader. L'équivalent fluent est
AgentBuilder.WithKnowledge("produits") /
WithKnowledge("produits", opts => { opts.TopK = 8; opts.Profile = "quality"; }) (cumulable).
Retry d'une tâche
tasks:
fetch:
description: Récupérer les cours
expectedOutput: Un tableau de cours
agent: trader
retry:
attempts: 3 # obligatoire — 3 exécutions au total : la première, puis au plus deux retries
backoffMs: 250 # défaut 0
backoff: exponential # fixed (défaut) | exponential : 250 ms, puis 500 ms, ... jamais plus de 5 minutes
Une tâche qui échoue est rejouée dans chaque mode d'orchestration : un seul décorateur, entre le checkpoint et le cœur d'exécution, applique la politique ; les stratégies ne réessaient donc jamais et les six modes se comportent pareil. Graph n'a pas de boucle de retry propre, et maxRetryCycles est refusé au chargement.
- Une nouvelle tentative rejoue la tâche entière, appels au modèle et appels d'outils compris, y compris les appels d'outils déjà réussis. Rien ne les déduplique : une tâche dont les outils écrivent (un fichier, un e-mail, un paiement) doit pouvoir tourner deux fois sans dommage, et c'est à l'auteur de la crew de le garantir.
- Jamais réessayés : une annulation, un refus du gardien (
GuardianBlocked), un budget épuisé. Le refus de la porte de permission est un résultat d'outil à l'intérieur d'une tentative, pas un échec de tâche. Les retries d'une sortie invalide restent à l'intérieur d'une tentative. Une tâche de décision n'exécute aucun agent et ne peut pas déclarerretry:(le chargement échoue, en nommant la tâche). - Réessayés exprès : un dépassement du temps d'exécution (
ExecutionTimeExceeded) et une chaîne de basculement de fournisseur à court de profils (FallbackExhausted) comptent tous deux comme des échecs et sont réessayés, après le backoff, car l'un comme l'autre peut être passager. Le coût est borné : au plusattemptsfois la chaîne de basculement entière par tour de la tâche. - Ce qu'une tentative en échec laisse derrière elle : ses appels d'outils (un fichier écrit, un message envoyé), ce qu'un outil a écrit en mémoire, le coût qu'elle a mesuré et les événements
tool.*etcost.updatedqu'elle a émis restent, et les callbacksOnTaskStarted/OnTaskCompletedpartent une fois par tentative. Le résultat de la tâche va dans la mémoire de la crew et son livrable (final_message,structured_output) n'est écrit que par une tentative qui a produit une réponse finale : un retry les remplace donc au lieu de les dupliquer ; un fichier que l'agent écrit lui-même avecfile_writen'est remplacé que si la tentative suivante écrit le même chemin. - Reprise : seule la tentative qui a clos la tâche est checkpointée. Un run arrêté entre deux tentatives, ou dont la dernière tentative a échoué, n'a aucun checkpoint pour cette tâche, et
orkeon run --resumela rejoue depuis la tentative 1. - Après la dernière tentative il reste le dernier échec, exactement comme si la tâche avait tourné une fois : le même résultat en échec ou la même exception.
- L'attente entre deux tentatives vient de
backoffMsetbackoff, sur leTimeProviderde l'hôte, et s'interrompt aussitôt que le run est annulé. - Ce que voit un observateur : chaque retry émet un
task.startedqui porteattempt(le démarrage de la stratégie est la tentative 1 ; voir le bus d'événements du run) ;task.completedarrive une fois, pour la tentative qui a clos la tâche. Le checkpoint d'une tâche réussie à la troisième tentative noteRetryCount: 2, et un run repris la répond depuis là sans interroger le modèle, en rejouant sonRetryCount. - Le basculement de fournisseur est une autre couche. Un basculement (là où il est configuré) passe au fournisseur suivant à l'intérieur d'un appel au modèle ;
retry:rejoue la tâche entière. Les deux se combinent : un appel qui échoue sur tous les fournisseurs de sa chaîne fait échouer la tentative,retry:rejoue alors la tâche, et cette tentative parcourt de nouveau la chaîne : une tâche fait au plusattemptsfois la longueur de la chaîne d'appels au modèle par tour. - Les budgets du graphe comptent les tentatives : sans bornes
graphexplicites, les visites valent par défaut la somme sur les tâches de1 + retries(retries=attempts - 1), soitnœuds × (1 + tentatives de retry)quand toutes les tâches réessaient pareil (ADR-018), et les transitions le double plus un.
Configuration Graph
Avec process: "graph", un bloc graph: décrit le graphe d'état que la crew exécute et le borne (ADR-018) ; sans bloc, ou avec un bloc qui ne tient que des budgets, la crew exécute un nœud par tâche, enchaînés dans l'ordre d'exécution :
process: graph
graph:
start: triage # facultatif : le premier nœud par défaut
nodes: # facultatif : absent = un nœud implicite par tâche, son id le nom de la tâche
- { id: triage, task: triage }
- { id: fix, task: fix }
- { id: escalate, task: escalate }
edges:
- { from: triage, to: fix, when: { triage.category: [bug] } }
- { from: triage, to: escalate } # sans `when` : le « sinon »
- { from: fix, to: END }
- { from: escalate, to: END }
circuitBreakerPreset: strict # "strict" (défaut) | "permissive" | "default"
maxTransitions: 50 # défaut : calculé, 2 × visites + 1
maxVisits: 5 # visites d'UN nœud — défaut : calculé, somme sur les tâches de 1 + leurs retries
maxTotalDurationSeconds: 600 # durée totale (surcharge le preset)
- Nœuds. Un nœud est
{id, task}:tasknomme une tâche de la crew,STARTetENDsont refusés comme ids. Une tâche est portée par un nœud au plus ; quandnodesest donné, une tâche qu'aucun nœud ne nomme est refusée.edgessansnodesdonne un nœud implicite par tâche. Un nœud est revisité par une arête qui y revient : à la revisite, la dernière sortie et la dernière décision l'emportent. Un nœud dont la tâche échoue arrête le run : il n'y a pas de routage sur échec (un retry est leretry:de la tâche). - Arêtes. Plusieurs
edgesdepuis un mêmefromforment une seule arête conditionnelle, évaluée dans l'ordre de déclaration : la première dont lewhentient l'emporte, et l'arête sanswhenest le « sinon ». Unfromqui porte des arêteswhenest une tâche de décision et a exactement une arête sanswhen; une tâche ordinaire a exactement une arête. Lewhengarde la grammaire de celui de la tâche, avec son préfixe<tâche>.:<tâche>.<question>: [option, ...],<tâche>.<question>: ">= 0.7",<tâche>.<question>.<option>: ">= 0.25"; la tâche est celle dufrom, et ses questions sont vérifiées au chargement.otherwisene s'écrit pas : une arête sanswhenen tient lieu. - Refusé au chargement, chaque message nommant le nœud : un
whensur unfromqui n'est pas une décision, une décision sans arête sanswhen, deux arêtes sanswhendepuis un même nœud, plusieurs arêtes sur une tâche ordinaire, un nœud orphelin, un nœud sans chemin versEND, une arête vers un nœud inconnu, ungraph:hors deprocess: graph, et unwhen:ou desdependencies:au niveau tâche dans une crew qui a des nœuds ou des arêtes (les arêtes ordonnent les tâches, un second routeur les contredirait). Les fautes de topologie viennent deGraphTopologyValidator, toutes à la fois, et l'export vérifie les mêmes règles avant d'écrire. - Budgets.
maxVisitsest leMaxStateVisitsdu Domain, compté par nœud : un nœud entré plus souvent que cela déclenche le disjoncteur. Non renseigné,maxVisitsvaut la somme sur les tâches de1 + retriesetmaxTransitionsdeux fois plus un ; une valeur explicite l'emporte. - Retiré (
[breaking]). Le blocgraphConfig:(ses budgets passent dansgraph:,maxStateVisitsdevenantmaxVisits),maxRetryCycleset toutmaxCycles: une borne sur les cycles estmaxVisits, et un retry est leretry:de la tâche. Une crew qui écrit encoregraphConfigest refusée au chargement, avec un renvoi versgraph:; une clémaxRetryCyclesoumaxCyclesest refusée au chargement comme clé qu'Orkeon ne lit pas. - Exécution. Le moteur Domain exécute toute crew du process Graph, avec ou sans bloc
graph:;JsStateGraphn'exécute que lestateGraph(...)d'un script.ork.ts. Un run repris parcourt de nouveau le graphe : les exécutions d'une tâche déjà terminée sont servies depuis le checkpoint, clé<tâche>#<n>selon leur ordre, donc un nœud entré deux fois a deux entrées. La réponse d'un nœud de décision est checkpointée de la même façon (<tâche>#<n>) et rejouée à la reprise, jamais redemandée : un modèle interrogé deux fois pourrait répondre autrement et envoyer le run repris sur une autre route. L'export réécritgraph:, si bien qu'import, export, import donnent le même graphe.
graph: est le seul réglage de circuit breaker d'une crew (CircuitBreakerPolicyFactory.ResolveGraph). Le moteur de graphe n'applique que trois limites : transitions, visites d'un même nœud, durée totale (GraphRunner) ; un timeout par état ou un mode dégradé n'a aucun effet sur un run de graphe.
Supprimé : circuitBreaker
Le bloc circuitBreaker: — à la racine de la crew comme sur une tâche — n'existe plus, et une crew
qui en écrit encore un est refusée au chargement avec un message qui nomme le bloc graph. Le
bloc de tâche configurait une machine d'états de tâche qu'aucun chemin d'exécution ne lançait, et
trois limites de garde (maxRetries, maxToolCallsPerRound, maxValidationRetries) que rien ne
lisait. Le bloc de crew n'était lu que par le mode Graph, où le bloc graph: porte le même preset et
les trois mêmes limites effectives.
Ce qui borne une tâche, c'est sa boucle d'agent : le maxIter de l'agent, l'arrêt après trois
erreurs d'outil identiques consécutives, et les reprises de validation de sortie. Un agent à deux itérations de son plafond en est prévenu une fois, tant qu'il peut agir (rien n'est envoyé quand maxIter vaut 2 ou moins) ; celui qui atteint maxIter reçoit un dernier tour sans outil qui lui demande de dire ce qu'il n'a pas pu faire, et sa tâche garde Success mais porte le drapeau endedOnIterationCap. Cela vaut pour la boucle d'agent principale ; les boucles de repli native (appels d'outils) et textuelle héritée ne font ni l'un ni l'autre : elles finissent toujours sur le plafond, sans la note et sans le drapeau. Ce qui borne un
run de graphe, c'est graph: (ci-dessus). Le moteur générique de machine d'états et
CircuitBreakerPolicy restent — le mode Graph, orkeon forge et le graphe RAG correctif s'en
servent (voir FSM).
Le livrable tool_call
Avec source: tool_call (le défaut), l'agent écrit le fichier lui-même. Le prompt nomme toujours le
chemin : Deliverable: write the final result to '<path>' using the <tool> tool. quand la boîte à
outils de l'agent, ses propres outils plus ceux de la tâche, contient un outil intégré qui écrit ce chemin,
l'outil de son format d'abord (docx_writer pour un .docx, file_write pour un fichier texte ;
les outils qui écrivent), et
Deliverable: write the final result to '<path>'. sinon : un agent ne reçoit jamais la consigne d'appeler
un outil qu'il n'a pas, ni file_write pour un fichier binaire. Avec source: final_message, le prompt dit que le framework écrit la réponse
finale telle quelle au chemin : l'agent donne le contenu complet et n'écrit pas le fichier lui-même ;
source: structured_output n'ajoute aucune ligne.
Quand une tâche tool_call réussit, le framework vérifie par le système de fichiers virtuel que le
fichier a été écrit par la tâche pendant le run : il lit l'état du fichier (existence, taille, date de
dernière écriture) une fois, au début de la première tentative de la tâche dans le run, et de nouveau à la
fin de chaque tentative. Un retry, une révision hiérarchique ou un autre bulletin d'un vote qui garde le
fichier qu'une tentative précédente de la même tâche a écrit n'est pas signalé. Un fichier absent à la fin,
ou présent mais inchangé depuis ce premier début (un fichier laissé par un run précédent), laisse la tâche réussie mais lui
pose le drapeau deliverableMissing (TaskResult.DeliverableMissing) : un avertissement nomme la tâche
(sa clé, sinon le début de sa description), l'agent et le chemin, AUTO_SUMMARY.md affiche
⚠ completed without writing its deliverable (⚠ completed on its iteration cap without writing its deliverable quand la tâche a aussi fini sur son plafond d'itérations), l'événement task.completed porte
deliverableMissing: true et run.finished la compte dans missingDeliverables
(bus d'événements de run). Un système de fichiers qui ne donne ni taille ni date
d'écriture se rabat sur la seule existence. La vérification est au mieux : un système de fichiers qui ne
peut pas répondre laisse le drapeau à false, une tâche exécutée sans système de fichiers n'est pas
vérifiée, et une annulation pendant la vérification annule la tâche comme toute autre. Seule une tâche
réussie reçoit le drapeau : une tâche en échec, y compris une tâche hiérarchique que le manager a rejetée
jusqu'au bout, jamais, et la sortie en échec d'une telle tâche hiérarchique ne nomme aucun chemin de
livrable aux tâches suivantes. Dans un vote consensuel, le fichier est jugé sur tout le vote : un candidat qui l'a
écrit compte, quelle que soit la réponse retenue.
Une tâche reprise rejoue le drapeau et le chemin depuis son checkpoint (un checkpoint écrit avant eux
rejoue false et aucun chemin) ; quand le fichier que nomme le checkpoint a disparu à la reprise, la
reprise ne donne aucun chemin aux tâches suivantes, et une tâche tool_call signale son livrable manquant
(un fichier écrit par le framework, avec final_message ou structured_output, perd seulement son chemin).
Une tâche de décision n'exécute aucun agent et n'écrit aucun fichier : un deliverable: déclaré sur
elle n'est jamais écrit, et le contrôle du chargement le signale une fois, quelle que soit la source, dans
une crew YAML, un crew.ork.ts comme sous --validate (livrables vérifiés au chargement).
Quand la sortie d'une tâche précédente est coupée pour tenir dans le prompt d'une tâche suivante et que le
fichier de son livrable est connu pour exister (écrit par le framework pour final_message et
structured_output, trouvé par cette vérification pour tool_call, dans tous les modes, reprise autonome
comprise), le texte coupé se termine par [full result in '<path>': read it with file_read] ; une sortie
précédente laissée de côté entièrement est nommée par
[result of task <id> in '<path>': read it with file_read]. Les deux renvois ne sont écrits que pour un
agent dont la boîte à outils contient file_read ; un agent qui ne l'a pas reçoit le texte coupé seul.
Une sortie sans fichier connu est coupée comme avant.
Supprimé : outputFile
La clé outputFile: d'une tâche n'existe plus, et une crew qui en écrit encore une est refusée au
chargement par un message qui indique le remplacement : le bloc deliverable: de la tâche (plus haut),
par exemple deliverable: { path: /output/report.md }. Avec la source: tool_call par défaut, l'agent
reçoit la consigne d'écrire ce chemin ; avec source: final_message, le framework y écrit la réponse finale.
Le chargement vérifie qu'un livrable tool_call peut être écrit (plus bas).
Livrables vérifiés au chargement
Un livrable tool_call qu'aucun agent capable d'exécuter sa tâche ne peut écrire est signalé au chargement
de la crew (#392) : un avertissement nomme la tâche, le chemin et les agents, et la crew se charge quand
même. orkeon run --validate l'imprime en une ligne WARNING: par tâche
(cli) ; un run signale de toute façon un fichier qui n'a pas été écrit
(le livrable tool_call).
- Les agents jugés sont ceux à qui le processus peut confier la tâche : l'agent que la tâche nomme
dans une crew
sequential,parallelougraph(chaque agent quand elle n'en nomme aucun, choisi à tour de rôle à l'exécution) ; chaque agent sauf lemanagerAgentdans une crewhierarchicalouconsensual; chaque agent dans une crewautonomous. L'avertissement ne vient que si aucun d'eux ne peut écrire le fichier. - Un agent peut écrire le fichier quand sa ceinture d'outils, ses outils plus ceux de la tâche, contient
un outil intégré qui écrit ce chemin :
docx_writerpour un.docx,xlsx_writerpour un.xlsx,image_generationpour un.png,.jpg,.jpegou.webp,firefox(sa capture d'écran) pour un.png, etfile_writepour tout fichier texte, jamais un fichier binaire. Un chemin est binaire quand son extension, quelle que soit sa casse, nomme un document bureautique (.docx,.xlsx,.pptx,.odt,.pdf,.epubet leurs voisins), une image, une archive, de l'audio ou de la vidéo, une base ou un fichier de données (.sqlite,.db,.parquet), une police ou un exécutable : le texte de la réponse finale ne peut pas en être un, si bien que seul un outil qui écrit son format le livre. Un format qui est du texte brut (.rtf,.svg,.csv,.html) n'est pas binaire :file_writel'écrit. Les éditeurs (edit_file,edit_batch,structural_rewrite) modifient un fichier existant, les téléchargeurs (drive_download,email_save_attachment) nomment le fichier eux-mêmes, etshell_commandne nomme aucun chemin : aucun ne compte. - Aucun avertissement quand la ceinture contient un outil qu'Orkeon ne livre pas (celui d'un serveur MCP, d'un script, d'un plugin) : le contrôle ne peut pas savoir ce qu'il écrit. Ni pour un agent dont le modèle exécute ses propres outils.
- Une tâche de décision qui déclare un
deliverable:reçoit son propre constat, quelle que soit la source : une décision n'exécute aucun agent et n'écrit aucun fichier, le remède est donc de retirer le bloc ou de le déplacer vers une tâche qui exécute un agent. Le contrôle des outils qui écrivent la saute. - Les chemins qui chargent sans le contrôle sont listés dans les limitations :
une crew construite en C# avec
CrewBuilder, un.ork.tsprocédural sous--validate, qui n'est pas chargé comme une crew, et un agent dont le modèle exécute ses propres outils (un agent Microsoft Agent Framework), qui compte comme capable d'écrire.
Un hôte C# lance le même contrôle avec DeliverableToolCheck.Check(tasks, agents, processType, managerAgentId) (Orkeon.Application.Crew), qui renvoie un DeliverableToolFinding par tâche, dont le
Message est le texte de l'avertissement et le Kind (DeliverableFindingKind.NoWriter ou DecisionTask)
ce qu'il signale. DeliverableToolCheck.IsBinary(path), WritersOf(path), PreferredWriterOf(path) et
WriterHeldFor(toolNames, path) donnent la règle que partagent le contrôle, le prompt et la forge. CrewFactoryOptions.WarnOnDeliverableTools (true par défaut)
coupe l'avertissement du chargement ; --validate le coupe, pour imprimer chaque constat une seule fois.
Budget autonome
budget: borne le run d'une crew process: autonomous (#218) :
process: autonomous
budget:
tokens: 400000 # somme courante prompt + complétion de chaque appel ; aucune par défaut
wallTimeSeconds: 1800 # aucune par défaut
toolCalls: 80 # tâches distribuées ; 50 par défaut
delegationDepth: 2 # délégations du run ; 4 par défaut
spawnedAgents: 3 # agents créés via spawn_agent ; 10 par défaut
Chaque clé est facultative, et une clé omise prend son défaut : une crew sans budget: n'a ni
plafond de tokens ni temps mural, si bien qu'une crew ordinaire n'est jamais écourtée par un chiffre
qu'elle n'a pas choisi. Une limite de 0 ou moins, ou un budget: sur une crew d'un autre process — le
seul qui le dépense est autonomous — fait échouer le chargement, en nommant la crew. L'export
réécrit le bloc, la durée en secondes entières. Le même budget est
CrewBuilder.Budget(new CrewBudget { ... }) en C# et
crewBuilder().budget({ tokens, wallTime, toolCalls, delegationDepth, spawnedAgents }) en .ork.ts
(voir le guide de l'orchestration Autonomous).
Export
YamlCrewExporter — qu'enregistre AddOrkeonYaml() — réécrit une CrewConfiguration en YAML :
ExportToString, ExportToFileAsync, ou ExportToDirectoryAsync pour le triplet plat crew.yaml +
agents.yaml + tasks.yaml. Rechargé, le fichier donne la même configuration — chaque clé que lit le
chargeur — et son propre export est le même texte, octet pour octet. Les clés sont écrites en
camelCase, et une clé que rien ne fixe n'est pas écrite du tout.
- Sous les clés de l'auteur. Une crew chargée depuis le YAML garde la clé de chaque agent et de
chaque tâche (
researcher,collect) : l'export écrit chacun sous elle, et chaque référence —agent:,dependencies:,managerAgent:— par elle. Une configuration bâtie en C# ou par un script.ork.tsn'a pas de clés : ses agents et ses tâches sont écrits sous leurs identifiants. Deux entrées sous un même nom, ou une référence qui ne nomme aucune entrée, font échouer l'export par uneInvalidOperationExceptionqui les nomme : le chargeur refuserait le fichier. - Ce que le chargeur a fait de votre fichier, pas votre fichier. L'export écrit ce que porte la
configuration : un
preset:de guardrails revient sous la forme duheader, desruleset destoolRulesqu'il a apportés, lellm:de crew sous la forme du bloc que chaque agent en a reçu, sous chaque agent, et lesanchors:sous la forme du texte qu'elles remplaçaient. Un attachement de connaissance qui ne nomme que sa collection est écrit en forme courte, tout autre en forme longue. - Une source relative suit le fichier. Une source de
rag:est écrite telle quelle :./data/faq.mdse lit donc par rapport au dossier d'où le fichier exporté est chargé (voir Configuration Knowledge & RAG) — exportez à côté des données, ou écrivez des sources absolues. Le dossier d'où la crew a été lue n'est pas une clé, et n'est pas écrit ; rien de ce pour quoi le schéma ci-dessus n'a pas de clé ne l'est non plus.
Modèles YAML
Tous les modèles YAML vivent dans Orkeon.Infrastructure.Configuration (src/core/Orkeon.Infrastructure/Configuration/Yaml/YamlConfigModels.cs) ; YamlCrewMapper les transforme en CrewConfiguration du Domain et CrewDefinitionValidator la vérifie. Ils comprennent :
CrewYamlConfig(définition complète d'une crew) etCrewSettingsYamlConfig(le fichier de réglages de crew des formats multi-fichiers —crew.yamlouconfig.yaml)AgentYamlConfig(rôle, objectif, backstory, outils, limites)TaskYamlConfig(description, résultat attendu, dépendances, outils, livrable, surcharge LLM, guardrails)LlmYamlConfig(profil, modèle, température, max tokens, topP, thinking, responseFormat/responseSchema, cache) avecThinkingYamlConfig,ResponseSchemaYamlConfig,CacheYamlConfigLlmOverrideYamlConfig(le blocllm_override:de tâche)DeliverableYamlConfig(le blocdeliverable:de tâche)GuardrailsYamlConfig(lesguardrails:d'agent et de tâche)LinkYamlConfig(l'ACLlinks:de crew)CrewYamlConfig.Mounts/CrewSettingsYamlConfig.Mounts(le blocmounts:de crew — items/racineou<ulid>|/racine) →CrewConfiguration.Mounts(MountReference)AgentYamlConfig.Filesystem(items chemin ou{path, access}) →AgentConfiguration.FileSystem(FileSystemScopeEntry) ;AgentYamlConfig.AnnounceMounts, sinon l'announce_mountsde la crew →AgentConfiguration.AnnounceMountsGraphYamlConfig(start, nœuds, arêtes, circuitBreakerPreset et ses limites) avecGraphNodeYamlConfig,GraphEdgeYamlConfigRagYamlConfig(collections + sources/chunking, défauts — avecRagCollectionYamlConfig,RagChunkingYamlConfig,RagDefaultsYamlConfig) →RagCrewConfigAgentYamlConfig.Knowledge(entrées forme courte/longue) →KnowledgeAttachment
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.
Voir aussi : YAML et Builders · Orchestration FSM · Orchestration Graph · Orchestration Autonome · Retour à l'index