🇬🇧 English version
Exécuter votre premier exemple (depuis les sources)
Voir aussi : Trois façons d'exécuter Orkeon · Vue d'ensemble · Bootstrap et exécution · Retour à l'index
C'est le point d'entrée si vous avez cloné le dépôt et voulez exécuter un crew embarqué depuis les sources. En cinq minutes environ, vous exécutez un vrai exemple à 3 agents et récupérez un rapport de synthèse. Si vous préférez télécharger un binaire précompilé ou utiliser un conteneur, voir Trois façons d'exécuter Orkeon.
Chemin le plus rapide (ni build, ni clone) :
docker run -it --rm -e ORKEON_ENTRYPOINT=shell ghcr.io/orkeon/orkeonpuisorkeon-example run 1— détails dans Trois façons d'exécuter Orkeon §3.
Prérequis
| Prérequis | Notes |
|---|---|
| SDK .NET ≥ 10.0.300 | Le dépôt épingle le SDK dans global.json avec rollForward: latestFeature. Un SDK plus ancien fait échouer le build (voir Dépannage). Vérifiez avec dotnet --version. |
| Git | Pour cloner le dépôt. |
| Un endpoint LLM + une clé | N'importe lequel des 16 fournisseurs pris en charge, ou un endpoint local type Docker Model Runner / Ollama. Fourni via un profil appsettings (ci-dessous). |
1. Cloner et compiler
git clone https://github.com/Orkeon/orkeon.git
cd orkeon
dotnet build Orkeon.sln
2. Choisir un exemple
Chaque crew sous examples/ est décrit par un config.yaml. Parcourez le
catalogue des exemples, ou commencez simplement
par l'assistant de recherche — un crew séquentiel à 3 agents qui explore le web,
analyse des documents et écrit un rapport de synthèse cité :
examples/01-enterprise/01-research-assistant/config.yaml
3. Choisir un profil LLM
Les runners lisent leur configuration LLM (endpoint, modèle, clé API) dans un
appsettings.json. Le dépôt livre une matrice de profils sous
examples/appsettings/ pour ne pas en écrire un à la main :
| Fichier | Cible |
|---|---|
appsettings.json |
Défaut — Docker Model Runner sur localhost:12434 (sans clé API) |
appsettings.docker-model-runner.local.json.example |
Gabarit Docker Model Runner |
appsettings.deepseek.local.json.example |
DeepSeek cloud |
appsettings.openai.local.json.example |
OpenAI cloud |
appsettings.glm.local.json.example / appsettings.glm-medium.local.json.example |
Z.AI (GLM) |
appsettings.gemini.local.json.example |
Google Gemini |
appsettings.grok.local.json.example |
Grok (x.AI) |
appsettings.minimax.local.json.example |
MiniMax (endpoint international ; les comptes de Chine continentale utilisent api.minimaxi.com) |
appsettings.openrouter.local.json.example |
OpenRouter (agrégateur — identifiants vendor/model) |
appsettings.mammouth.local.json.example |
Mammouth AI (agrégateur — identifiants nus des éditeurs, reconnu par son hôte) |
appsettings.local.json.example |
Gabarit générique — pointe sur DeepSeek ; changez BaseUrl / Model / ApiKeyEnvVar pour tout autre fournisseur |
Copiez le gabarit de votre fournisseur, déposez-le en vrai *.local.json
(git-ignoré) et posez votre clé dans la variable qu'il nomme :
cp examples/appsettings/appsettings.deepseek.local.json.example \
examples/appsettings/appsettings.deepseek.local.json
export DEEPSEEK_API_KEY=sk-...
Un gabarit garde la clé hors du fichier : son
"ApiKeyEnvVar": "DEEPSEEK_API_KEY"nomme la variable qui la contient, que chaque run lit.ORKEON_Llm__ApiKey(préfixeORKEON_,__comme séparateur de section), quand elle est posée, l'emporte sur elle. UneApiKeyécrite${DEEPSEEK_API_KEY}— un espace réservé que la configuration .NET ne développe jamais — refuse le démarrage, avec la correction.
Si Docker Model Runner (ou un autre endpoint
localhost:12434) tourne déjà , leexamples/appsettings/appsettings.jsonpar défaut n'exige ni clé ni copie — passez directement à l'étape 4 sans--settings.
Il n'y a pas de champ Provider à renseigner : le fournisseur est auto-détecté
depuis Llm.BaseUrl du profil — l'hôte du fournisseur, le port 11434 pour Ollama, sinon
un serveur compatible OpenAI (à défaut d'URL de base, depuis le nom du modèle, puis le
préfixe de la clé) ; changer de fournisseur revient à pointer le bon profil.
4. L'exécuter
Chaque exemple s'exécute via la CLI orkeon. Depuis un checkout
des sources, invoquez-la via son projet (aucune installation — elle embarque aussi
vos modifications locales) :
mkdir -p out
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run \
examples/01-enterprise/01-research-assistant/config.yaml \
--settings examples/appsettings/appsettings.deepseek.local.json \
--mount ./out:/output:rw \
-v 1
Cette seule commande exécute le crew de bout en bout et se termine. L'outil
file_write de l'agent rédacteur dépose son rapport sur le montage /output,
c'est-à -dire votre répertoire local ./out.
CLI installée ? Avec une archive de release ou
dotnet tool install, la même exécution devient :orkeon run examples/01-enterprise/01-research-assistant/config.yaml --settings … --mount ./out:/output:rw -v 1.
Suivre le run et garder les échanges LLM
Pour suivre le run dans le terminal et garder chaque requête et chaque réponse envoyées
au modèle dans un dossier de votre choix, ajoutez --llm-log-path :
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run \
examples/01-enterprise/01-research-assistant/config.yaml \
--settings examples/appsettings/appsettings.deepseek.local.json \
--mount ./out:/output:rw \
--llm-log-path ./logs-llm \
-v 1
-v 1affiche à la console ce que font les agents et les outils, et une ligne par échange LLM (fournisseur, modèle, statut, durée) dès que le journal est actif. Il n'affiche jamais les contenus.--llm-log-path ./logs-llmécrit chaque échange en entier (requête et réponse, en-têtes et payload) en fichiers.jsonldans./logs-llm, créé s'il manque. Il active le journal à lui seul ;--llm-logseul écrit dans./llm-logs.- Un dossier hors du répertoire courant (
/tmp/logs,~/logs) demande aussi--allow-external-mounts; sans lui, le run s'arrête avant d'appeler le modèle.
La section de settings LlmLogging règle ce que
les fichiers gardent (FullEmbeddingLog, LogStreamingExchanges, MaxBodyLengthChars). Elle
n'est lue qu'avec l'un des deux flags, et aucun setting ne choisit le dossier. La console
interactive orkeon-repl prend les deux mêmes flags (référence CLI).
Chaque flag, expliqué
Les options de la CLI orkeon que vous utiliserez vraiment :
| Flag | Court | Ce qu'il fait |
|---|---|---|
<config> (positionnel) |
— | Requis (sauf avec --list-tools). La définition de crew passée à orkeon run <config> — un fichier .yaml, un fichier .ork.ts de scripting, ou un répertoire contenant une crew YAML multi-fichiers. Le verbe run lui-même est facultatif : orkeon <config> fait la même chose. |
--settings <chemin> |
-s |
Chemin de l'appsettings.json portant la config LLM. Optionnel — voir la résolution des settings. |
--verbose <0-2> |
-v |
Verbosité. 0 (défaut) = silencieux, 1 = activité des agents et des outils, plus une ligne de résumé par échange LLM quand --llm-log est actif, 2 = debug complet. Le contenu des échanges n'est que dans les fichiers de --llm-log. |
--mount <phys>:<virt>:<droits> |
-m |
Expose un répertoire hôte au système de fichiers virtuel du crew. droits vaut ro, rw ou rwnd (lecture-écriture sans suppression) ; des segments ;<sous-chemin>:<droits> surchargent les droits sous le montage. Plusieurs montages se passent séparés par des espaces derrière un seul flag (--mount a:/x:ro b:/y:rw) — le parseur rejette un --mount répété. Un crew qui écrit des résultats a besoin d'un montage :rw (/output est la convention qui déclenche l'écriture automatique du résumé). |
--mount-id <id> |
Quand plusieurs entrées Orkeon:FileSystem:Mounts des settings déclarent la même racine virtuelle, garde celle dont l'identifiant (le préfixe de 26 caractères avant son \|) est donné. Plusieurs identifiants se passent séparés par des espaces derrière un seul flag. |
|
--allow-external-mounts |
Autorise des montages (et un chemin <config> ou --llm-log-path) situés hors du répertoire de travail. Sans lui, un --mount hors du répertoire de travail est refusé au démarrage (code 1) ; le dossier du script et toute entrée des settings en vigueur (une entrée choisie par id comprise) n'en demandent pas. La variable d'env ORKEON_ALLOW_EXTERNAL_MOUNTS=1 l'active pour chaque invocation (l'image conteneur ghcr.io/orkeon/orkeon l'embarque). |
|
--var CLE=VALEUR |
-V |
Injecte une variable dans l'entrée du crew. Les descriptions de tâches contenant {CLE} sont développées en VALEUR. Plusieurs variables se passent séparées par des espaces derrière un seul -V (un flag répété est rejeté). Crews YAML seulement — ignoré pour les scripts .ork.ts, qui prennent --inputs. |
--initial-context <texte> |
Une chaîne de contexte libre passée à l'entrée du crew. Crews YAML seulement — ignoré pour les scripts .ork.ts. |
|
--inputs <json> |
Entrées JSON inline transmises à un script comme variable globale inputs (voie .ork.ts). |
|
--inputs-file <chemin> |
Comme --inputs, lu depuis un fichier JSON. |
|
--llm-profile <id> |
Lance le run sur le profil LLM d'hôte <id> (Llm:Profiles:<id> dans les réglages ou l'environnement ORKEON_) comme défaut du run : la section Llm devient ce profil, en entier. Un id que la configuration ne définit pas est refusé avec exit 1 avant toute construction d'hôte — voir la référence CLI. |
|
--llm-log |
Capture chaque échange HTTP LLM (requête + réponse, en-têtes + payload) en .jsonl sous ./llm-logs. Les settings LlmLogging règlent ce qui est gardé. |
|
--llm-log-path <dir> |
Comme --llm-log, mais écrit dans <dir> (et implique --llm-log). Un <dir> hors du répertoire de travail demande --allow-external-mounts. |
|
--validate |
Exécution à blanc : résout les settings, construit l'hôte et charge la crew (résolution stricte des outils) sans sonder le LLM ni rien exécuter. Imprime VALIDATION OK/FAILED et sort 0 / non-zéro. Sur un .ork.ts, les types du script sont d'abord vérifiés avec tsc s'il est trouvé (sinon WARNING: type check skipped et le reste est validé ; TypeCheck: Off l'omet). Un livrable tool_call qu'aucun agent capable d'exécuter sa tâche ne peut écrire imprime une ligne WARNING: sur stderr ; le code de sortie ne change pas. |
|
--list-tools |
Construit l'hôte et imprime les noms d'outils enregistrés, triés, un par ligne, puis sort — aucune crew requise. | |
--events jsonl |
Émet le protocole d'événements JSONL versionné sur stdout au lieu du texte brut (c'est ainsi qu'un client externe pilote un run) — voir le bus d'événements de run. | |
--stream |
Avec --events, émet aussi les événements llm.delta token par token (verbeux par nature ; désactivé sauf demande). |
|
--client <nom> |
Avec --events, le nom du pair observateur sur le hub (client://<nom>, défaut client). |
|
--memory-limit-mb <n> |
Plafond mémoire Jint pour un run .ork.ts (surcharge l'appsettings ; 0 le désactive). |
Les montages et le VFS
Le code du framework Orkeon ne touche jamais le disque directement — toute E/S
passe par le système de fichiers virtuel.
--mount est le pont entre un répertoire hôte et cet espace virtuel :
--mount ./out:/output:rw # hôte ./out -> virtuel /output (lecture-écriture)
--mount ./data:/data:ro # hĂ´te ./data -> virtuel /data (lecture seule)
Le runner monte automatiquement en lecture seule le répertoire du fichier de config lui-même,
sous le nom /crew, si bien que le YAML et ses fichiers voisins sont toujours
visibles — un data.csv à côté de config.yaml se lit en /crew/data.csv, jamais
par son chemin sur votre disque
(ADR-008). Les chemins
hors du répertoire de travail exigent --allow-external-mounts (ou
ORKEON_ALLOW_EXTERNAL_MOUNTS=1 dans l'environnement — le défaut de l'image
conteneur).
Comment les settings sont résolus
Quand vous omettez --settings, le runner cherche un appsettings.json dans cet
ordre (premier trouvé gagne) :
- Le
--settings <chemin>explicite, s'il est donné. - L'
appsettings.jsonvoisin du fichier<config>. - En remontant l'arborescence depuis le config, en cherchant Ă chaque niveau un
sous-répertoire
appsettings/appsettings.json— c'est ainsi qu'est trouvée la matrice de profils partagéeexamples/appsettings/appsettings.json. - Le fichier de config global propre à l'utilisateur écrit par
orkeon init(%APPDATA%\Orkeon\appsettings.jsonsous Windows,$XDG_CONFIG_HOME/Orkeon/appsettings.json— par défaut~/.config/Orkeon/appsettings.json— sous Linux et macOS).
Si rien n'est trouvé, le runner se rabat sur les seules variables d'environnement
et imprime un avertissement. ĂŠtre explicite avec --settings reste l'option la
plus prévisible.
Dépannage
Les symptômes possibles sur une machine fraîche, avec le message exact et le correctif :
| SymptĂ´me / message | Cause | Correctif |
|---|---|---|
error CS9057: analyzer assembly ... references version 5.3.0 of the compiler |
SDK .NET plus ancien que 10.0.300 | Installez un SDK ≥ 10.0.300 (la version épinglée dans global.json). Vérifiez avec dotnet --version. |
error CS8795: Partial method ... must have an implementation part |
Le générateur de source n'a pas tourné — généralement le même SDK périmé que ci-dessus | Passez le SDK à ≥ 10.0.300 et recompilez. |
error NU1008: Projects that use central package version management should not define the version |
Un Version= égaré sur un PackageReference alors que la gestion centralisée est active |
Retirez la version inline ; déclarez-la dans Directory.Packages.props. |
dotnet: command not found (dans un script, alors que dotnet marche en interactif) |
dotnet est un alias/fonction shell invisible des shells non interactifs |
Mettez le SDK sur le PATH dans ~/.zprofile / ~/.profile, p. ex. export PATH="$HOME/.dotnet:$PATH". |
Connection refused (localhost:12434) |
Le profil par défaut vise Docker Model Runner, qui ne tourne pas | Démarrez Docker Model Runner, ou copiez un profil cloud (p. ex. appsettings.deepseek.local.json) et passez-le avec --settings. |
401 (Unauthorized) ou NU1301 au restore, mentionnant une source nuget.pkg.github.com |
Un nuget.config utilisateur déclare le flux GitHub Packages (reste d'une ancienne installation, ou ajouté pour le canal dev) sans jeton valide |
Inutile pour les releases : les paquets Orkeon et le tool orkeon sont sur nuget.org, et le nuget.config du dépôt épingle nuget.org comme unique source. Retirez le flux GitHub (dotnet nuget remove source <nom>) — aucun token n'est requis. Seul le canal dev en a besoin : renouvelez le jeton (read:packages) avec dotnet nuget update source <nom> --username <utilisateur> --password <PAT> --store-password-in-clear-text. |
ERROR: --allow-external-mounts is required ... |
Votre chemin <config>, un --mount ou --llm-log-path pointe hors du répertoire de travail |
Ajoutez --allow-external-mounts (ou posez ORKEON_ALLOW_EXTERNAL_MOUNTS=1), ou ramenez les chemins sous le cwd. |
WARNING: No appsettings.json found. Using environment variables only. |
La résolution des settings n'a rien trouvé | Passez --settings <chemin> explicitement (voir l'ordre de résolution). |
Étapes suivantes
- Trois façons d'exécuter Orkeon — binaires et conteneurs, sans checkout des sources.
- YAML, Builders et CrewFactory — le schéma derrière chaque
config.yaml. - Catalogue des exemples — les 104 exemples fournis, en 9 catégories thématiques.
- Inventaire des outils — ce que les agents savent réellement faire.
- Donner une boîte aux lettres à vos agents — un agent qui lit, range et rédige des brouillons de réponse dans une vraie boîte aux lettres.