agentx-code

v0.2.0

Published

2 months ago

Terminal-first multi-provider AI agent orchestrator with the agentx CLI.

0High
0Medium
0Low

abdelmad

agentx ai agents cli codex openai orchestration

Terminal Agent Orchestrator

Ce workspace contient le socle d'un orchestrateur terminal-first pour agents IA multi-fournisseurs.

Le produit abandonne l'interface site. La cible est une CLI interactive, inspiree des workflows Claude Code, qui comprend le workspace local, orchestre une chaine d'agents specialises, connecte plusieurs fournisseurs possedes par l'utilisateur et garde un audit clair des decisions.

Positionnement

terminal-first: interaction principale dans le terminal, avec commandes naturelles et mode scriptable.
multi-provider: Claude, OpenAI/GPT, Gemini et modeles locaux via contrats communs.
multi-account conforme: plusieurs profils de connexion utilisateur, sans mutualisation de comptes ni contournement de limites fournisseur.
agent-chain: un modele orchestrateur choisit planner, executor, reviewer, security, QA ou agents metier selon la tache.
local-first: secrets, contexte projet, checkpoints et artefacts restent locaux par defaut.

Structure

agents/: specs Markdown des agents reutilisables.
.codex/agents/: exports TOML chargeables par Codex.
agents/catalog.json: registre machine-readable et routage par defaut.
apps/control-api/: API locale et store JSON pour le prototype.
apps/worker-*: workers providers et routeur d'execution.
packages/orchestration-core/: chaines d'agents, planification, handoff.
packages/account-manager/: refs de secrets, linkage de comptes et registre utilisateur.
packages/agent-registry/: agents built-in, utilisateur et projet avec precedence.
packages/skill-registry/: skills provider-agnostiques partageables entre modeles.
packages/session-memory/: memoire compacte de checkpoints pour reprise et handoff.
packages/model-router/: scoring deterministe provider/modele avec raisons et fallbacks.
packages/provider-contracts/: contrat commun providers, slots et profils.
packages/policy-engine/: garde-fous, budgets, data classification.
packages/permission-gate/: decisions allow/ask/deny pour fichiers, shell et reseau.
packages/tool-runtime/: outils locaux bornes par permissions.
packages/local-models/: detection Ollama/LM Studio pour modeles locaux.
packages/quota-ledger/: suivi quota/budget.
packages/checkpointing/: bundles de reprise et handoff.
packages/prompt-registry/: prompts et versions.
packages/telemetry/: evenements, logs et traces.
packages/qa-bench/: evaluation qualite/cout.
templates/: briefs et handoffs reutilisables.
apps/terminal-cli/: CLI agentx pour piloter le projet depuis le terminal.
docs/implementation/: plan d'implementation executable.
docs/qa-validation-plan-multi-providers.md: strategie QA et non-regression.

Installation en une commande

Prérequis : Node.js >= 24.14 (node --version)

One-liner depuis GitHub (recommandé)

npm install -g github:abdelmad10/Orchestre

Puis lance :

agentx

npm clone le repo, exécute prepare (qui build dist/agentx.js), et installe la commande agentx dans le PATH global (%APPDATA%\npm sur Windows, ~/.npm-global/bin ou /usr/local/bin sur Unix).

Pour mettre à jour :

npm install -g github:abdelmad10/Orchestre

Pour désinstaller :

npm uninstall -g agentx-code

Installation depuis un tarball local

Depuis le repo cloné :

npm run build
npm pack
npm install -g ./agentx-code-0.2.0.tgz

Mode développement (depuis le repo)

git clone https://github.com/abdelmad10/Orchestre.git
cd Orchestre
npm install
npm link
agentx

npm link crée la commande globale agentx qui pointe vers le checkout local — utile pour itérer.

Permissions npm global (Unix)

Si npm install -g retourne EACCES, configure un préfixe utilisateur (une seule fois) :

mkdir -p "$HOME/.npm-global" && \
  npm config set prefix "$HOME/.npm-global" && \
  echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && \
  source ~/.zshrc

Sur Windows, le préfixe %APPDATA%\npm est dans le PATH par défaut — pas de configuration nécessaire.

Premier lancement

agentx

Au premier lancement, agentx détecte automatiquement les CLIs providers installés (codex, claude, gemini, ollama) et leur statut d'authentification, puis te propose de choisir un modèle d'orchestration. La config est sauvée dans ~/.agentx/config.json.

Tu peux relancer l'onboarding à tout moment :

agentx --reset-onboarding

Commandes slash disponibles

Dans agentx, tape /help pour voir les 24 commandes groupées :

Session : /help, /clear, /status, /quit
Plan & Run : /plan, /model, /skip, /retry, /pause
Providers : /providers, /login, /logout, /doctor
Agents & Skills : /agents, /skills
Config : /config
Historique : /runs, /resume, /export, /cost
Utilitaires : /init, /memory, /compact

Commandes

npm run check:structure: valide le scaffold attendu.
npm run install:agentx: installe agentx dans ~/.agentx sans sudo ni /usr/local.
npm run build: genere le bin installable dist/agentx.js.
npm pack: cree le package npm local agentx-code-0.1.0.tgz.
npm install -g ./agentx-code-0.1.0.tgz: installe la CLI agentx.
npm run cli -- help: lance la CLI locale.
npm run cli: lance le mode interactif.
npm run cli -- interactive --task "<objectif>" --approve: lance une session interactive scriptable avec timeline.
npm run cli -- init: initialise .agentx/config.json.
npm run cli -- doctor --json: verifie la sante du workspace.
npm run cli -- login local --url http://127.0.0.1:11434 --json: lie un runtime local.
npm run cli -- login openai --secret-ref env:OPENAI_API_KEY --json: lie un provider sans stocker le secret brut.
npm run cli -- agents list: liste les agents disponibles.
npm run cli -- agents add ./agent.md: installe un agent projet.
npm run cli -- skills add ./skill-dir: installe une skill projet.
npm run cli -- providers list: liste les profils providers locaux.
npm run cli -- providers test: verifie les refs de secrets configurees.
npm run cli -- providers add --provider openai --label main --secret-ref env:OPENAI_API_KEY: ajoute un profil sans stocker le secret brut.
npm run cli -- models list: liste les modeles connus et locaux detectes.
npm run cli -- models add --label dev --model llama3.1 --url http://127.0.0.1:11434: ajoute un modele local.
npm run cli -- plan "<objectif>" --json: propose une chaine d'agents sans execution.
npm run cli -- run "<objectif>" --dry-run --json: cree un run simule et persiste son artefact.
npm run cli -- run "<objectif>" --yes --json: execute via worker configure ou fallback local, avec events, checkpoints, handoffs et artifacts sous .agentx/runs.
npm run cli -- status --json: liste les runs locaux.
npm run cli -- resume <run_id> --json: inspecte un run local et affiche la prochaine action.
npm run cli -- config get --json: inspecte la configuration locale.
npm run demo:orchestration: lance une demonstration locale de chaine d'agents.
npm run start:api: demarre l'API locale.
npm run start:worker:openai: demarre le worker OpenAI local (OPENAI_API_KEY requis pour appel reel, simulation sinon).
npm run start:worker:router: demarre le routeur local de workers.
npm run smoke:api: verifie les endpoints API critiques.
npm run smoke:cli: verifie le parcours CLI minimal.
npm run smoke:openai: verifie le worker OpenAI Responses API avec fetch mocke, sans cle reelle.
npm run smoke:install: verifie pack npm, installation globale avec prefix temporaire et projet vierge.
npm test: lance les smoke tests CLI et API.
.\scripts\start-local-stack.ps1: demarre le runtime local API-only sous Windows.
.\scripts\stop-local-stack.ps1: arrete le runtime local API-only sous Windows.

AGENTX_HOME peut remplacer ~/.agentx pour les tests, la CI ou les environnements isoles.

Test OpenAI reel:

npm run install:agentx
Ajoute ~/.agentx/bin au PATH si le script te le demande.
Dans un nouveau projet: agentx
Choisis OpenAI dans l'onboarding; agentx ouvre https://platform.openai.com/api-keys.
Colle ta cle API ou exporte OPENAI_API_KEY.
Lance une tache: agentx run "Analyse ce projet" --yes

Important: le login web ChatGPT qui genere une cle automatiquement est un flux officiel propre a Codex CLI. Pour agentx, le flow product-ready disponible publiquement utilise une cle API OpenAI stockee via Keychain macOS (keychain:openai:<profile>) ou referencee par env:OPENAI_API_KEY.

Le worker OpenAI se lance seulement si tu veux isoler le provider dans un processus separe: npm run start:worker:openai, puis OPENAI_WORKER_URL=http://127.0.0.1:3002 agentx run "..." --yes. Sans worker, agentx run appelle directement l'API OpenAI Responses quand OPENAI_API_KEY est present.

Direction Produit

Le MVP doit livrer une CLI capable de:

connecter des profils Claude, OpenAI, Gemini et local;
installer des agents et skills reutilisables sur tous les providers;
recommander une chaine d'agents adaptee a une demande;
executer ou simuler les etapes avec checkpoints;
expliquer le choix de provider, modele et agent;
appliquer budgets, permissions et politiques de donnees;
reprendre proprement apres panne, quota ou interruption.
injecter les skills et la memoire de session dans les prompts workers.
proposer un flux interactif plan -> approval -> timeline -> resume.

Le plan de reference est docs/implementation/terminal-agent-orchestrator-plan.md.