Diagnostiquer un agent

Ce guide montre comment déterminer pourquoi un agent ne produit pas d’exécutions.

Procédez du haut vers le bas : d’abord les exécutions de l’agent lui-même, puis son backend, puis le serveur, puis l’hôte.

1. Vérifier l’historique d’exécution de l’agent

Paramètres → Espace de travail → Agents → sélectionnez l’agent → Journaux.

Chaque exécution affiche une pastille d’état, une durée (« Running… » pendant qu’elle est en cours), ses heures de début et de fin, son PID et l’adaptateur utilisé. Vue ouvre le flux d’événements brut de cette exécution. Arrêter met fin à un processus en cours et marque l’exécution comme « Killed by user » ; Arrêter l’exécution dans l’en-tête fait de même pour toutes les exécutions en cours de cet agent.

Interprétez-le comme suit :

Aucune exécution du tout — le lancement n’a jamais eu lieu. Les mentions dans le composeur sont @ suivi de caractères de mot (lettres, chiffres, trait de soulignement). La résolution se fait par correspondance exacte ou par préfixe sur le nom de l’agent, donc @code-reviewer est interprété comme code et peut quand même réveiller un agent nommé code-reviewer. Un nom contenant un espace ne peut pas être mentionné comme un seul jeton. Passez ensuite à l’étape 2.
Une exécution qui s’est terminée immédiatement en erreur — ouvrez Vue. Un échec de démarrage du backend apparaît ici comme une erreur de processus.
Une exécution bloquée à « Running… » — arrêtez-la, puis vérifiez le Délai de silence (minutes) de l’agent dans l’onglet Paramètres. Sans délai défini, la valeur par défaut du mode s’applique.
Une exécution terminée sans sortie utile — l’état du journal d’exécution reste completed pour une exécution qui s’est terminée sans le livrable annoncé ; le signal honnête est le texte du résumé, pas la pastille.

L’onglet Journaux n’affiche aucun coût. Pour les dépenses, utilisez le tableau par agent dans Observabilité → Aperçu.

2. Vérifier le backend de l’agent

Paramètres → Serveur → Fournisseurs de modèles (/settings/server/providers).

La liste Exécuteurs détectés montre chaque adaptateur avec le résultat de sa sonde — une version installée, « Vérification… » ou « Non trouvé » — ainsi que le chemin résolu et les puces de capacités d’une CLI trouvée. Cliquez sur Actualiser dans l’en-tête de la page pour relancer la sonde.

La sonde s’exécute sur la machine qui héberge cc_server, pas sur celle que vous consultez. Si vous êtes sur le client web ou un appareil associé, « Non trouvé » signifie que la CLI manque sur l’hôte du serveur.

Deux points à confirmer :

L’agent a bien un adaptateur défini. Un agent dont l’adaptateur est vide est acheminé vers Control Center (built-in) et le journal d’exécution consigne cc-harness, de sorte que la transcription nomme ce qui s’est exécuté. Sans modèle non plus, il demande à Anthropic sa valeur par défaut — ce qui échoue avec No credential for provider "anthropic" à moins d’avoir connecté un compte Anthropic. Les spécialistes préinstallés sont livrés sans adaptateur.
L’adaptateur intégré a un modèle. Sa liste de modèles provient en direct des fournisseurs connectés plus bas sur cette même page ; un fournisseur sans identifiant enregistré ne contribue donc aucun modèle.

Le catalogue d’adaptateurs lui-même est fixe : il n’existe aucun moyen d’enregistrer un nouvel adaptateur. Ce que vous pouvez modifier par adaptateur ici, ce sont ses arguments de lancement et ses variables d’environnement. Notez qu’une substitution d’environnement propre à un adaptateur l’emporte silencieusement sur un compte de fournisseur connecté lors de la résolution des identifiants.

3. Vérifier le serveur

Paramètres → Serveur → Connexion et état (/settings/server/connection) indique à quel serveur ce client parle et ce que celui-ci rapporte.

Pour un serveur sans interface, GET /healthz fournit la même information sans client. Il est non authentifié et ouvert à CORS par conception :

curl http://localhost:9030/healthz

Il renvoie l’état du serveur, la durée de fonctionnement en secondes, le nombre de connexions actives, le port lié, la version de compilation et le SHA git, la version du schéma de l’espace de travail, la version du catalogue RPC, l’id, le nom et l’empreinte d’identité du serveur, si la liaison n’est pas sécurisée, et un bloc codeGraph avec les compteurs watching / indexing / pending. Lorsqu’un cache a déjà vu du trafic, il inclut aussi un bloc caches ; un serveur de démonstration ajoute demo: true.

Deux choses à savoir lorsqu’une modification « fonctionne dans les tests mais pas dans l’application » :

L’application de bureau lance un binaire cc_server précompilé de préférence à la source. Une nouvelle opération RPC ou un nouvel outil MCP n’apparaît qu’une fois le binaire recompilé, et le journal de démarrage émet un avertissement lorsque le SHA git du processus enfant diffère de celui de l’application.
L’application de bureau arrête un serveur lancé qui n’a pas affiché sa bannière de disponibilité dans les 20 secondes et bascule vers un écran d’erreur.

4. Vérifier l’hôte

Paramètres → Serveur → Diagnostics et confidentialité (/settings/server/diagnostics) est la page de l’hôte. Elle contient :

Bac à sable — l’interrupteur principal, le backend détecté et un indice d’installation. Seul le backend détecté provient du serveur ; voir l’avertissement ci-dessous. Il n’y a aucune commande de réinitialisation.
Recherche sémantique — le cycle de vie du modèle d’embedding sur l’appareil : installé, en téléchargement avec un pourcentage, non installé ou en erreur d’installation. Tant qu’il n’est pas installé, la mémoire et la recherche de code restent limitées aux mots-clés.
Comportement du système — garder l’ordinateur éveillé pendant l’exécution des agents.
Niveau de journalisation — augmentez-le avant de reproduire une défaillance.
Confidentialité — si le contenu brut des diffs peut être transmis au modèle de l’agent et si des rapports de plantage sont envoyés.

Détection et application concordent désormais : là où le détecteur signale un backend natif, les exécutions d’agents sur cet hôte y sont réellement enveloppées. Mais le détecteur est la seule chose active dans cette section. L’interrupteur principal et le sélecteur de backend sont des préférences enregistrées sur votre appareil, et le serveur n’en lit aucune — l’interrupteur propre au serveur est --sandbox (on par défaut, off pour s’en retirer).

Un avertissement ici mérite donc d’être pris en compte, mais ce n’est généralement pas la cause de l’échec d’un agent. Pour confirmer dans quel état se trouve le serveur, consultez son journal de démarrage : il affiche agent sandbox ON avec la note du backend, no OS-native agent sandbox on this host avec un indice d’installation, ou agent sandbox DISABLED by --sandbox off. GET /healthz ne comporte aucun champ de bac à sable.

Là où il n’y a pas de backend — Windows en tout temps, Linux ou WSL2 sans bwrap ni socat — les exécutions ne sont pas isolées dans un bac à sable, et ce qui les borne est l’arbre de travail propre à la conversation, son jeton de forge en lecture seule et la passerelle de poussée, les garde-fous d’action, l’assainissement de l’environnement et la surface d’outils que son mode autorise.

Défaillances courantes

L’exécution ne démarre jamais et l’adaptateur affiche « Non trouvé »

Installez la CLI sur l’hôte du serveur, puis cliquez sur Actualiser dans la page Fournisseurs de modèles. Ou faites passer l’agent à l’adaptateur intégré, qui n’a besoin d’aucune CLI, et connectez un fournisseur sur la même page.

L’agent ne peut pas pousser ni ouvrir une demande de tirage

Lisez ce que git ou l’agent a affiché. Control Center policy: … signifie qu’une règle d’action l’a refusé ou qu’une approbation est restée sans réponse : vérifiez Pousser vers un dépôt distant et Ouvrir une pull request sous Paramètres → Espace de travail → Autorisations des agents. Si git indique que Control Center n’a aucun identifiant GitHub capable de pousser, installez la GitHub App sur ce dépôt ou connectez GitHub.

La recherche sémantique ne renvoie rien d’utile

Vérifiez Paramètres → Serveur → Diagnostics et confidentialité → Recherche sémantique. Tant que le modèle d’embedding n’est pas installé, la recherche se limite aux mots-clés. Les lignes écrites avant l’installation du modèle ne sont jamais remplies rétroactivement ; elles restent donc limitées aux mots-clés même après.

Le serveur refuse de démarrer

Les bibliothèques natives sont obligatoires et il n’existe aucun mode dégradé. Une dylib manquante fait refuser le démarrage à cc_server, qui nomme le fichier fautif dans l’erreur. Préparez les bibliothèques natives avec scripts/natives/build_natives.sh et recompilez le binaire du serveur.

Une action est refusée en silence

Une décision de garde-fou prompt sans approbateur connecté est refusée, c’est voulu. Vérifiez les règles de l’espace de travail sous Paramètres → Espace de travail → Autorisations des agents.