Table of Contents

🇬🇧 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/orkeon puis orkeon-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éfixe ORKEON_, __ comme séparateur de section), quand elle est posée, l'emporte sur elle. Une ApiKey é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à, le examples/appsettings/appsettings.json par 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 1 affiche Ă  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 .jsonl dans ./logs-llm, créé s'il manque. Il active le journal Ă  lui seul ; --llm-log seul Ă©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) :

  1. Le --settings <chemin> explicite, s'il est donné.
  2. L'appsettings.json voisin du fichier <config>.
  3. 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ée examples/appsettings/appsettings.json.
  4. Le fichier de config global propre à l'utilisateur écrit par orkeon init (%APPDATA%\Orkeon\appsettings.json sous 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