Diagnostica un agente

Questa guida mostra come scoprire perché un agente non produce esecuzioni.

Procedi dall’alto verso il basso: prima le esecuzioni dell’agente stesso, poi il suo backend, poi il server, poi l’host.

1. Controlla la cronologia delle esecuzioni dell’agente

Impostazioni → Spazio di lavoro → Agenti → seleziona l’agente → Log.

Ogni esecuzione mostra un badge di stato, una durata («Running…» mentre è in corso), gli orari di avvio e di completamento, il PID e l’adapter usato. Visualizza apre il flusso di eventi grezzo di quell’esecuzione. Ferma termina un processo in esecuzione e contrassegna l’esecuzione come «Killed by user»; Termina in esecuzione nell’intestazione fa lo stesso per ogni esecuzione in corso di quell’agente.

Leggilo così:

Nessuna esecuzione — l’invio non è mai avvenuto. Le menzioni nel compositore sono @ più caratteri di parola (lettere, cifre, underscore). La risoluzione è una corrispondenza esatta o per prefisso sul nome dell’agente, quindi @code-reviewer viene analizzato come code e può comunque risvegliare un agente chiamato code-reviewer. Un nome con uno spazio non può essere menzionato come un unico token. Poi passa al punto 2.
Un’esecuzione terminata subito con errore — apri Visualizza. Un fallimento nell’avvio del backend compare qui come errore di processo.
Un’esecuzione bloccata su «Running…» — fermala, poi controlla il Timeout di silenzio dell’agente nella scheda Impostazioni. Un timeout non impostato usa il valore predefinito della modalità.
Un’esecuzione completata senza output utile — lo stato nel registro delle esecuzioni resta completed per un’esecuzione terminata senza il risultato dichiarato; il segnale affidabile è il testo di riepilogo, non il badge.

La scheda Log non mostra alcun costo. Per la spesa, usa la tabella per agente in Osservabilità → Panoramica.

2. Controlla il backend dell’agente

Impostazioni → Server → Fornitori di modelli (/settings/server/providers).

L’elenco Runner rilevati mostra ogni adapter con l’esito della sonda — una versione installata, «Verifica…» o «Non trovato» — più il percorso risolto e i chip delle capacità per una CLI trovata. Clicca Aggiorna nell’intestazione della pagina per rieseguire la sonda.

La sonda viene eseguita sulla macchina che ospita cc_server, non su quella che stai guardando. Se sei sul client web o su un dispositivo associato, «Non trovato» significa che la CLI manca sull’host del server.

Due cose da verificare:

Che l’agente abbia un adapter impostato. Un agente con adapter vuoto viene inviato a Control Center (built-in) e il registro delle esecuzioni annota cc-harness, così la trascrizione indica cosa è stato eseguito. Se manca anche il modello, chiede ad Anthropic il suo predefinito — cosa che fallisce con No credential for provider "anthropic" a meno che tu non abbia collegato un account Anthropic. Gli specialisti predefiniti vengono forniti senza adapter.
Che l’adapter integrato abbia un modello. Il suo elenco di modelli arriva in tempo reale dai fornitori collegati più in basso nella stessa pagina, quindi un fornitore senza credenziale memorizzata contribuisce con zero modelli.

Il catalogo degli adapter è fisso — non c’è modo di registrare un nuovo adapter. Ciò che puoi modificare per adapter qui sono i suoi argomenti di avvio e le variabili d’ambiente. Nota che una sovrascrittura dell’ambiente per adapter prevale silenziosamente su un account del fornitore collegato quando vengono risolte le credenziali.

3. Controlla il server

Impostazioni → Server → Connessione e stato (/settings/server/connection) mostra a quale server sta parlando questo client e cosa riporta.

Per un server headless, GET /healthz fornisce le stesse informazioni senza un client. Non richiede autenticazione ed è aperto al CORS per scelta progettuale:

curl http://localhost:9030/healthz

Restituisce lo stato del server, l’uptime in secondi, il numero di connessioni attive, la porta associata, la versione della build e lo SHA di git, la versione dello schema dello spazio di lavoro, la versione del catalogo RPC, id, nome e impronta dell’identità del server, se il binding non è sicuro e un blocco codeGraph con i conteggi watching / indexing / pending. Quando una cache ha visto traffico include anche un blocco caches; un server demo aggiunge demo: true.

Due cose da sapere quando una modifica «funziona nei test ma non nell’app»:

Il desktop avvia un binario cc_server precompilato preferendolo al codice sorgente. Una nuova operazione RPC o uno strumento MCP non compare finché il binario non viene ricompilato, e l’avvio registra un avviso quando lo SHA di git del processo figlio differisce da quello dell’app.
Il desktop termina un server avviato che non ha stampato il proprio banner di pronto entro 20 secondi e passa a una schermata di errore.

4. Controlla l’host

Impostazioni → Server → Diagnostica e privacy (/settings/server/diagnostics) è la pagina a livello di host. Contiene:

Sandbox — l’interruttore principale, il backend rilevato e un suggerimento di installazione. Solo il backend rilevato proviene dal server; vedi l’avvertenza sotto. Non esiste un controllo di ripristino.
Ricerca semantica — il ciclo di vita del modello di embedding sul dispositivo: installato, in download con una percentuale, non installato o con errore di installazione. Finché non è installato, la memoria e la ricerca nel codice restano solo per parole chiave.
Comportamento del sistema — mantiene il computer attivo mentre gli agenti vengono eseguiti.
Livello di registro — alzalo prima di riprodurre un errore.
Privacy — se il contenuto grezzo dei diff può essere inoltrato al modello dell’agente e se vengono inviati i report di arresto anomalo.

Rilevamento e applicazione ora concordano: dove il rilevatore segnala un backend nativo, le esecuzioni degli agenti su quell’host sono davvero avvolte in esso. Ma il rilevatore è l’unica cosa attiva in questa sezione. L’interruttore principale e il selettore del backend sono preferenze memorizzate sul tuo dispositivo e il server non ne legge nessuna — l’interruttore proprio del server è --sandbox (on per impostazione predefinita, off per rinunciarvi).

Quindi un avviso qui vale la pena di essere gestito, ma di solito non è il motivo per cui un agente sta fallendo. Per confermare in quale stato si trova il server, leggi il suo registro di avvio: stampa agent sandbox ON con la nota sul backend, no OS-native agent sandbox on this host con un suggerimento di installazione, oppure agent sandbox DISABLED by --sandbox off. GET /healthz non contiene alcun campo del sandbox.

Dove non esiste un backend — sempre su Windows, su Linux o WSL2 senza bwrap e socat — le esecuzioni non sono isolate e a limitarle sono il checkout della conversazione stessa, il suo token del forge di sola lettura e il gateway dei push, i guardrail delle azioni, la sanificazione dell’ambiente e la superficie di strumenti consentita dalla sua modalità.

Errori comuni

L’esecuzione non parte mai e l’adapter mostra «Non trovato»

Installa la CLI sull’host del server, poi clicca Aggiorna nella pagina Fornitori di modelli. Oppure passa l’agente all’adapter integrato, che non richiede alcuna CLI, e collega un fornitore nella stessa pagina.

L’agente non riesce a fare push né ad aprire una pull request

Leggi cosa hanno stampato git o l’agente. Control Center policy: … significa che una regola delle azioni l’ha negato o che un’approvazione è rimasta senza risposta: controlla Eseguire il push a un remoto e Aprire una pull request in Impostazioni → Spazio di lavoro → Autorizzazioni degli agenti. Se git dice che Control Center non ha alcuna credenziale GitHub in grado di eseguire il push, installa la GitHub App su quel repo o collega GitHub.

La ricerca semantica non restituisce nulla di utile

Controlla Impostazioni → Server → Diagnostica e privacy → Ricerca semantica. Finché il modello di embedding non è installato, la ricerca è solo per parole chiave. Le righe scritte prima dell’installazione del modello non vengono mai riempite a posteriori, quindi restano solo per parole chiave anche dopo.

Il server non si avvia affatto

Le librerie native sono necessarie e non esiste una modalità degradata. Una dylib mancante fa sì che cc_server rifiuti di avviarsi e indichi il colpevole nell’errore. Prepara le librerie native con scripts/natives/build_natives.sh e ricompila il binario del server.

Un’azione viene negata silenziosamente

Una decisione di guardrail prompt senza alcun approvatore collegato viene negata, per scelta progettuale. Controlla le regole dello spazio di lavoro in Impostazioni → Spazio di lavoro → Autorizzazioni degli agenti.