Diagnostiquer un agent

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

Procédez de haut en 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 des exécutions de l’agent

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

Chaque exécution affiche un badge d’état, une durée (« Running… » tant 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 tue un processus en cours et marque l’exécution « 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 ces informations ainsi :

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 : @code-reviewer est donc analysé comme code et peut tout de même réveiller un agent nommé code-reviewer. Un nom contenant un espace ne peut pas être mentionné en 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 lancement du backend apparaît ici comme une erreur de processus.
Une exécution bloquée sur « Running… » — arrêtez-la, puis vérifiez le Délai de silence de l’agent dans l’onglet Paramètres. Un délai non défini utilise la valeur par défaut du mode.
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 son livrable déclaré ; le signal fiable est le texte du résumé, et non le badge.

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 détectée. Cliquez sur Actualiser dans l’en-tête de la page pour relancer la détection.

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

Deux points à confirmer :

L’agent a bien un adaptateur défini. Un agent dont l’adaptateur est vide est lancé sur Control Center (built-in) et le journal d’exécution enregistre cc-harness, ce qui permet à la transcription de nommer ce qui a été exécuté. Sans modèle non plus, il demande à Anthropic son modèle par défaut — ce qui échoue avec No credential for provider "anthropic" si vous n’avez pas connecté de compte Anthropic. Les spécialistes préchargé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 la même page : un fournisseur sans identifiant enregistré ne contribue aucun modèle.

Le catalogue d’adaptateurs lui-même est figé — il n’existe aucun moyen d’enregistrer un nouvel adaptateur. Ce que vous pouvez modifier ici, adaptateur par adaptateur, ce sont ses arguments de lancement et ses variables d’environnement. Notez qu’une surcharge 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 qu’il remonte.

Pour un serveur sans interface, GET /healthz fournit les mêmes informations sans client. Il est non authentifié et ouvert au CORS par conception :

curl http://localhost:9030/healthz

Il renvoie l’état du serveur, sa durée de fonctionnement en secondes, le nombre de connexions actives, le port d’écoute, la version de build 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 l’écoute est non sécurisée, et un bloc codeGraph avec les compteurs watching / indexing / pending. Lorsqu’un cache a vu du trafic, il inclut aussi un bloc caches ; un serveur de démonstration ajoute demo: true.

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

L’application de bureau lance en priorité un binaire cc_server précompilé plutôt que les sources. Une nouvelle opération RPC ou un nouvel outil MCP n’apparaît qu’après la recompilation du binaire, 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 tue un serveur lancé qui n’a pas affiché sa bannière de disponibilité dans les 20 secondes et bascule sur un écran d’erreur.

4. Vérifier l’hôte

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

Bac à sable — l’interrupteur principal, le backend détecté et une indication d’installation. Seul le backend détecté provient du serveur ; voir l’avertissement ci-dessous. Aucun contrôle de réinitialisation n’est disponible.
Recherche sémantique — le cycle de vie du modèle d’embedding local : installé, en cours de téléchargement avec un pourcentage, non installé ou en erreur d’installation. Tant qu’il n’est pas installé, la recherche dans la mémoire et le code reste limitée 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 les 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 de cette section. L’interrupteur principal et le sélecteur de backend sont des préférences stockées sur votre appareil, et le serveur n’en lit aucun — son propre interrupteur est --sandbox (on par défaut, off pour s’en désengager).

Un avertissement ici mérite donc d’être traité, mais ce n’est généralement pas la cause de la défaillance d’un agent. Pour confirmer l’état du serveur, lisez son journal de démarrage : il affiche agent sandbox ON avec la note sur le backend, no OS-native agent sandbox on this host avec une indication d’installation, ou agent sandbox DISABLED by --sandbox off. GET /healthz ne contient aucun champ de bac à sable.

Là où il n’y a pas de backend — toujours sous Windows, sous Linux ou WSL2 sans bwrap ni socat — les exécutions ne sont pas isolées et ce qui les encadre, c’est l’arbre de travail propre à la conversation, son jeton de forge en lecture seule et la passerelle de push, 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 sur la page Fournisseurs de modèles. Ou bien basculez l’agent sur l’adaptateur intégré, qui ne nécessite aucune CLI, et connectez un fournisseur sur la même page.

L’agent ne peut pas pousser ni ouvrir de pull request

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 ne porte que sur les mots-clés. Les lignes écrites avant l’installation du modèle ne sont jamais rétro-remplies : elles restent limitées aux mots-clés même après.

Le serveur refuse de démarrer

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

Une action est refusée silencieusement

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