Dans la partie 1, vous avez vu AgentX fonctionner sans rien installer : la démo a lancé trois démons, fait passer une tâche de l'un à l'autre, puis tout nettoyé. Cette partie installe AgentX pour de bon sur votre ordinateur.

L'installation tient en une commande. Ce qui compte vient juste après : savoir si l'installation est saine et, si elle ne l'est pas, ce qui manque précisément. AgentX a une commande pour cela, agentx doctor. Elle vérifie les raisons les plus courantes pour lesquelles AgentX ne marche pas et affiche un correctif sous chaque problème. L'essentiel de ce guide consiste à lire ce bilan.

Ceci est la partie 2 d'AgentX en pratique, une série de guides courts où chaque partie fait fonctionner une seule chose.

Ce que vous obtenez à la fin

La commande agentx installée sur votre ordinateur, à une version que vous savez nommer.
Un dossier de projet qui contient un fichier de réglages AgentX.
Le démon d'AgentX, son service d'arrière-plan, démarré et qui répond.
Un bilan doctor que vous savez lire, avec deux erreurs restantes que vous comprenez. Toutes deux concernent le modèle d'IA, et la partie 3 les règle.

Ce que cette partie ne fait pas. Elle ne connecte pas de modèle, donc aucun agent ne répond encore à un message. C'est voulu : une seule tâche par partie. AgentX fait partie du programme de produits de Noqta et reste expérimental. Vous en verrez un défaut à l'étape 5, et ce guide le contourne.

Prérequis

Node.js 22.19 ou plus récent, jusqu'à la version 26. AgentX refuse de démarrer sur les autres versions. Ce guide a été exécuté sur Node.js 22.22.0.
macOS ou Linux. Windows n'est pas testé par les mainteneurs d'AgentX ; utilisez WSL. Nous avons exécuté ce guide sur macOS.
Un terminal et un navigateur.
Environ deux minutes pour le téléchargement.

Pour cette partie, vous n'avez besoin ni de Git, ni de Docker, ni d'un compte, ni d'une clé API.

Comment nous l'avons exécuté. Nous avons installé AgentX dans un dossier personnel vierge et séparé, sur un Mac qui fait déjà tourner un autre AgentX, pour que rien dans ce guide ne repose sur une installation antérieure. Pour séparer les deux, nous avons placé le démon de test sur le port 19021 et le tableau de bord sur le port 19031. Là où notre sortie montre ces numéros, la vôtre montrera les valeurs par défaut : 18800 pour le démon et 4202 pour le tableau de bord. Nous avons lancé agentx setup avec --no-open, qui affiche l'adresse du tableau de bord au lieu d'ouvrir un navigateur. Nous avons aussi raccourci les chemins de dossiers, retiré quelques lignes de sortie et remplacé le nom de notre ordinateur par my-computer.

Étape 1 : vérifier la version de Node.js

node --version

Notre sortie :

v22.22.0

Si le numéro est inférieur à v22.19 ou supérieur à v26, installez Node.js 22 depuis nodejs.org et relancez la commande. Node.js 20 est trop ancien ; la section de dépannage montre le message obtenu.

Étape 2 : installer AgentX depuis npm

npm install -g agentix-cli@latest

Le paquet s'appelle agentix-cli. La commande qu'il installe s'appelle agentx. Notre sortie :

npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm warn deprecated domexception@4.0.0: Use your platform's native DOMException instead
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
 
added 347 packages in 2m

Les trois lignes npm warn deprecated sont sans conséquence. Elles concernent des bibliothèques dont dépend AgentX, pas votre installation. Sur notre machine, l'installation a pris 93 secondes.

Pour obtenir exactement ce que montre ce guide, fixez la version que nous avons testée :

npm install -g agentix-cli@0.137.3

AgentX publie souvent, parfois plusieurs fois par jour ; une version plus récente peut donc formuler une ligne autrement. Les étapes restent les mêmes.

Étape 3 : confirmer que la commande est là

agentx --version

0.137.3

Si le terminal répond command not found: agentx, l'installation a réussi mais votre terminal ne la voit pas. Le correctif est dans la section de dépannage.

Étape 4 : lancer doctor dans un dossier vide

AgentX garde ses réglages dans le dossier d'où vous le lancez. Créez-lui un dossier et entrez-y :

mkdir my-agentx
cd my-agentx

Demandez maintenant un bilan de santé :

agentx doctor

Notre sortie :

  agentx doctor
 
  Environment
    ✓ Node.js 22.22.0
    ✓ npm on PATH
      /Users/you/.nvm/versions/node/v22.22.0/bin/npm
    ! claude CLI not on PATH
      Only required for agents on the claude-code tier.
      → See https://docs.anthropic.com/en/docs/claude-code
    ! codex CLI not on PATH
      Only required for agents on the codex-cli tier.
      → Install with `npm i -g @openai/codex`.
    ! opencode CLI not on PATH
      Only required for agents on the opencode tier.
      → Install from https://opencode.ai/docs/.
    ✓ better-sqlite3 loads for Node v22.22.0
      NODE_MODULE_VERSION 127
 
  Config
    ✗ agentx.json not found
      Looked in /Users/you/my-agentx/agentx.json
      → Run `agentx setup` to create one via the web wizard.
 
  1 error, 3 warnings. Fix the error and rerun.

Voici comment lire n'importe quel bilan doctor :

✓ la vérification est passée.
! un avertissement. À lire, mais il n'empêche pas AgentX de fonctionner.
✗ une erreur. AgentX ne fonctionnera pas correctement tant qu'elle n'est pas corrigée.
→ le correctif proposé pour la ligne du dessus.
Les vérifications sont regroupées. Ici il y a deux groupes, Environment (votre ordinateur) et Config (vos réglages). D'autres apparaissent dès qu'il y a des réglages à vérifier.
La dernière ligne compte les erreurs et les avertissements.

Doctor se contente de vérifier. Il n'installe et ne répare rien.

Ce que dit ce premier bilan :

L'environnement est bon. Node.js est à une version prise en charge, et better-sqlite3, la petite base de données où AgentX range ses enregistrements, se charge correctement. Cette seconde ligne compte : c'est l'élément qui casse le plus facilement quand la version de Node.js ne correspond pas.
Les trois avertissements sont un menu, pas une liste de tâches. claude, codex et opencode sont trois outils d'IA pour le code qu'AgentX peut utiliser comme moteur d'un agent. Chaque avertissement dit la même chose : cet outil n'est nécessaire que si un agent s'en sert. Vous n'avez pas besoin des trois. Peut-être d'aucun.
L'unique erreur est attendue. Il n'y a pas encore de fichier de réglages, puisque vous n'en avez pas créé.

Étape 5 : créer le fichier de réglages

Doctor propose agentx setup, qui ouvre une page de configuration dans le navigateur. Sur la version que nous avons testée, cette commande ne fonctionne pas dans un dossier vide. Nous l'avons lancée et avons obtenu ceci :

  No agentx.json yet — the wizard will create one.
  Opening http://127.0.0.1:19031/setup
 
  Starting dashboard server on port 19031 (Ctrl-C to quit)…
  No agentx.json found — starting dashboard in setup-only mode.
  Visit http://127.0.0.1:19031 to run the wizard.
 
  Cannot read properties of undefined (reading 'enabled')

La commande s'arrête ensuite et la page de configuration ne se charge jamais. C'est un défaut d'AgentX 0.137.3, pas une erreur de votre part. Si vous voyez cette dernière ligne, prenez le chemin ci-dessous. Une version ultérieure le corrigera peut-être ; ce chemin fonctionne dans les deux cas.

Créez plutôt le fichier de réglages depuis le terminal :

agentx init

  agentx init
 
  ✓ Created agentx.json
  ✓ Created .env template
  ✓ Created .agentx/sessions/
  ✓ Created .claude/
 
  Next steps:
    1. Edit agentx.json — configure agents, channels, crons
    2. Edit .env — add API keys and bot tokens
    3. Run  agentx daemon start — start the daemon
    4. Run  agentx daemon status — verify everything

Ce que la commande a créé :

agentx.json est le fichier de réglages. Il démarre avec un agent nommé assistant, aucun canal et aucune planification.
.env accueille les clés privées. C'est d'abord un modèle dont toutes les lignes sont commentées ; il ne contient donc encore aucune clé.
.agentx/ est le dossier de travail d'AgentX pour cette installation : sa base de données, ses sessions et ses enregistrements.
.claude/ contient des réglages pour le dossier de l'agent.

Vous pouvez vérifier que le fichier de réglages est valide, à part :

agentx config check

  ✓ Config valid
    Node: my-computer (my-computer)
    Bind: 127.0.0.1:19021
    Agents: 1
    Crons: 0
    Mesh peers: 0
    Telegram: disabled
    WhatsApp: disabled
  ✓ All workspaces valid

Node désigne cet ordinateur, dont il reprend le nom. Bind est l'adresse sur laquelle le démon écoutera. 127.0.0.1 signifie « cet ordinateur seulement » : rien d'extérieur ne peut atteindre AgentX. Chez vous, la ligne indique 127.0.0.1:18800.

Étape 6 : relancer doctor

agentx doctor

Le groupe Environment est identique. À partir de Config, notre bilan donnait désormais :

  Config
    ✓ agentx.json valid (1 agents, 0 schedules)
    ✗ 1 agent(s) use claude-code tier but claude CLI is missing
      assistant
      → Install Claude Code (https://docs.anthropic.com/en/docs/claude-code) or switch these agents to tier=sdk.
 
  Secrets
    ✗ 1 env var(s) referenced in agentx.json but missing
      ANTHROPIC_API_KEY
      → Add to .env — e.g. ANTHROPIC_API_KEY=<value>
 
  Workspaces
    ✓ All agent workspace folders exist
 
  Workspace settings
    ✓ All 1 agent .claude/settings.json files clean
 
  Routing
    ✓ 0 webhook(s), 0 telegram account(s) — all routing references resolve
 
  Notifications
    ! AgentX Helper is not installed, so banners come from Script Editor and show its icon.
      → Run agentx desktop install, then run agentx notify "Hello" --title "Test" and click Allow.
 
  Runtime
    ! Daemon not reachable (not running?)
      http://127.0.0.1:19021
      → Run `agentx daemon start`. Skip this check with `agentx doctor --no-running`.
 
  2 errors, 5 warnings. Fix the errors and rerun.

Le fichier de réglages est trouvé et valide, et de nouveaux groupes apparaissent. Il y a aussi plus d'erreurs qu'avant. C'est un progrès : doctor voit maintenant assez loin pour vous dire ce dont l'agent lui-même a besoin.

claude CLI is missing. L'agent de départ est réglé pour utiliser Claude Code comme moteur, et Claude Code n'est pas installé sur cette machine. À l'étape 4, ce n'était qu'un avertissement, car aucun agent n'en avait besoin. Maintenant un agent en a besoin, donc c'est une erreur. Doctor est précis, il ne se contredit pas.
ANTHROPIC_API_KEY manquante. Le fichier de réglages fait référence à une clé que le fichier .env ne contient pas encore.
AgentX Helper is not installed. Affiché sur Mac seulement. Cela concerne les bannières de notification du bureau et reste facultatif.
Daemon not reachable. Un avertissement, et la seule ligne que vous corrigez dans cette partie. Le service d'arrière-plan n'a pas été démarré.

Les deux erreurs disent la même chose : l'agent n'a pas de modèle d'IA pour réfléchir. En connecter un est l'objet de la partie 3. Laissez-les pour l'instant.

Étape 7 : démarrer le démon et le vérifier

Le démon est le service d'arrière-plan d'AgentX. Il reçoit les messages, lance les agents et envoie les réponses. Démarrez-le en arrière-plan :

agentx daemon start --detach

Daemon started in background (PID: 33860)
  Logs: tail -f /tmp/agentx-daemon.log
  Stop: agentx daemon stop

Puis demandez-lui comment il va :

agentx daemon status

  my-computer (my-computer)
  Status: running — uptime 9s
  AgentX 0.137.3 (c2e6a0a)   node my-computer
  Running since   2026-10-13 10:05 (Africa/Tunis), 9s ago, pid 33860
  Last restart    2026-10-13 10:05, first start on record
  Restarts        1 today, 1 in the last 7 days (on record since 2026-10-13 10:05)
  Build on disk   dist newer than process: no
  Service         none (started from a terminal, nothing starts it again)
 
  Agents:
    Assistant (claude-code)
      /Users/you/my-agentx

Deux lignes méritent une lecture attentive :

Status: running est celle que vous attendez.
Service: none (started from a terminal, nothing starts it again) annonce franchement une limite. Vous avez démarré le démon à la main ; si l'ordinateur redémarre, le démon ne revient pas tout seul. Pour l'instant, cela convient.

Lancez doctor une troisième fois. Le dernier groupe change :

  Runtime
    ✓ Daemon healthy — 1 agents live, uptime 0m
      http://127.0.0.1:19021
    ✓ Daemon finds ffmpeg to measure phone recordings
 
  2 errors, 4 warnings. Fix the errors and rerun.

L'avertissement Daemon not reachable a disparu, remplacé par Daemon healthy. Les deux erreurs liées au modèle restent, comme prévu.

Étape 8 : voir le même bilan dans le navigateur

AgentX a un tableau de bord dans le navigateur, et le bilan doctor s'y trouve. Maintenant qu'un fichier de réglages existe, agentx setup démarre le tableau de bord sans le défaut de l'étape 5 :

agentx setup

  Found agentx.json — the wizard will extend your current install.
  Opening http://127.0.0.1:19031/setup
 
  Starting dashboard server on port 19031 (Ctrl-C to quit)…
 
  Live dashboard: http://127.0.0.1:19031
 
  (bound to localhost; no auth token — safe default)

Laissez ce terminal ouvert ; il fait tourner le tableau de bord. Votre navigateur ouvre la page de configuration. Ne la remplissez pas encore : c'est la partie 3. Ouvrez plutôt /admin/health à la même adresse (chez vous, http://127.0.0.1:4202/admin/health) et sélectionnez l'onglet Doctor.

L'onglet Doctor de la page Health d'AgentX : les groupes Environment, Config et Secrets avec les marques OK, WARN et FAIL, et le résumé ok=9 warn=4 fail=2

Ce sont les mêmes vérifications, avec OK, WARN et FAIL à la place des trois marques, et un bouton Re-run checks. Le résumé indique ok=9 warn=4 fail=2, ce qui correspond au terminal : 2 erreurs, 4 avertissements.

Ouvrez ensuite Live dans la barre du haut.

L'onglet Live d'AgentX après une installation neuve : 1/1 machines, un agent nommé @assistant, inactif et pas encore utilisé

Live affiche 1/1 machines et un agent, @assistant, marqué IDLE et not used yet. Dans la partie 1, cette page montrait trois machines simulées. Celle-ci est la vôtre.

Quand vous avez fini, appuyez sur Ctrl-C dans le terminal qui fait tourner le tableau de bord. Le démon continue de tourner ; c'est un programme distinct.

Étape 9 : arrêter le démon

agentx daemon stop

Daemon stopped (PID: 33860)

agentx daemon status indique alors AgentX is stopped et rappelle comment le redémarrer. Lancez ces commandes depuis votre dossier my-agentx : AgentX retrouve son démon grâce au fichier de réglages du dossier courant.

Options utiles de doctor

Les deux ont été exécutées pour ce guide sur la version 0.137.3.

Option	Ce qu'elle fait
`agentx doctor --no-running`	Saute la vérification que le démon répond. À utiliser quand vous avez arrêté le démon volontairement. Notre bilan est passé de 5 avertissements à 4.
`agentx doctor --json`	Affiche les mêmes vérifications dans un format lisible par d'autres programmes. Chaque vérification a une `severity`, un `group`, un `title` et, s'il y en a un, un `fix`.

Doctor se termine avec le code de sortie 1 dès qu'il y a au moins une erreur. Un script peut s'appuyer dessus.

Vérifier que cela a marché

agentx --version affiche un numéro de version.
agentx doctor affiche ✓ agentx.json valid sous Config.
Démon démarré, agentx doctor affiche ✓ Daemon healthy sous Runtime.
Les seules lignes ✗ restantes sont les deux qui concernent le modèle : le moteur manquant et la clé manquante.

Si les quatre points sont vrais, AgentX est installé et tourne, et vous savez exactement ce qui vous sépare d'un agent qui fonctionne.

Dépannage

AgentX needs Node.js 22.19 or newer, up to 26. This is Node.js 20.20.2. Nous avons reproduit ce message en lançant le même agentx sur Node.js 20. Toutes les commandes, agentx doctor compris, s'arrêtent sur cette seule ligne. Installez Node.js 22 et vérifiez avec node --version.

command not found: agentx. Le paquet est installé, mais le dossier où npm place les commandes n'est pas dans le chemin de recherche de votre terminal. Nous l'avons reproduit en retirant ce dossier du chemin. Trouvez le dossier avec :

npm prefix -g

La commande agentx se trouve dans le dossier bin à l'intérieur du dossier affiché. Ajoutez ce dossier bin à votre PATH, ou ouvrez un nouveau terminal si vous venez d'installer Node.js.

Cannot read properties of undefined (reading 'enabled') après agentx setup. C'est le défaut de l'étape 5. Il se produit sur la version 0.137.3 quand le dossier ne contient pas de agentx.json. Lancez d'abord agentx init, puis agentx setup.

Daemon not reachable (not running?). Démarrez-le avec agentx daemon start --detach, depuis le dossier qui contient votre agentx.json. Si vous l'avez arrêté volontairement, utilisez agentx doctor --no-running.

agentx.json not found. Vous êtes dans un autre dossier que celui où vous avez lancé agentx init. Doctor affiche le chemin où il a cherché ; revenez dans votre dossier my-agentx avec cd.

npm install -g échoue avec une erreur de permission (EACCES). Nous n'avons pas reproduit ce cas. Il survient quand Node.js a été installé pour tout le système et que npm n'a pas le droit d'écrire dans son dossier. Installer Node.js avec un gestionnaire de versions comme nvm l'évite.

Le désinstaller

Nous avons testé cela aussi. Depuis votre dossier my-agentx :

agentx daemon stop
npm uninstall -g agentix-cli

removed 347 packages in 2s

Cela supprime la commande. Votre dossier de projet n'est pas touché : agentx.json, .env, .agentx et .claude restent en place, ainsi que AGENTS.md et CLAUDE.md, deux fichiers d'instructions présents dans notre dossier à la fin de l'exécution. Supprimez le dossier my-agentx si vous ne voulez rien garder. Si vous continuez avec la partie 3, gardez tout.

En vidéo

La deuxième vidéo Learn AgentX couvre l'installation : youtu.be/arOqm5bB1Lw.

La suite de la série

La partie 3 crée votre premier agent : elle connecte un modèle d'IA, ce qui règle les deux erreurs que doctor affiche encore, et envoie à l'agent son premier message. D'ici là, la documentation d'AgentX se trouve sur github.com/anis-marrouchi/agentx.

Conclusion

Vous avez installé AgentX, créé ses réglages, démarré son service d'arrière-plan et lu son bilan de santé trois fois, en le voyant changer à mesure que chaque pièce se mettait en place. Vous avez aussi vu à quoi sert un bilan de santé : il a transformé « ça ne marche pas » en deux lignes nommées, chacune avec son correctif.

Si vous voulez des agents sur les outils de votre équipe, installés, vérifiés et maintenus en bon état pour vous, parlons-en.