Le tracce le lascia la superficie, non “l’agente”

Prima di classificare un fallimento bisogna sapere dove è scritto, e ogni superficie tiene un registro diverso e non intercambiabile. Attribuire al cloud agent un’evidenza che esiste solo nel Copilot SDK è l’errore più grave che si possa fare in questo dominio.

Sul cloud agent di Copilot l’evidenza principale sono i session logs. Nella timeline della pull request l’evento Copilot started work espone il pulsante View session: da lì i log si possono seguire in streaming mentre l’agente lavora, senza aspettare la fine. La stessa sessione si raggiunge anche dalla agents page, dove aprendo una riga si ottengono session log e overview con l’avanzamento, il consumo di token e la durata della sessione. La documentazione è precisa sul contenuto: i session log mostrano il ragionamento interno di Copilot e gli strumenti che ha usato per capire il repository, applicare le modifiche e validare il proprio lavoro. Ogni commit, inoltre, porta un link ai session log, quindi in code review o in un audit si risale al perché di una singola modifica.

Sulla Copilot CLI la memoria dell’esecuzione sta in locale: il comando /chronicle genera insight dalla cronologia delle sessioni, che vive in un database SQLite locale chiamato session store, con i file sotto ~/.copilot/session-state/. /chronicle search KEYWORD ritrova la sessione, /chronicle reindex ricostruisce il session store dai file, e copilot --continue o copilot --resume riprendono una sessione per riprodurre il problema. Se il sospetto è che l’agente non sia riuscito a toccare un percorso, /sandbox status dice se il sandboxing è attivo e /sandbox policy mostra i percorsi read/write, read-only e denied che un comando lanciato da lì riceverebbe davvero.

Con il Copilot SDK l’osservabilità è la propria: si alza il livello con l’opzione logLevel (da "error" fino a "debug" e "all"), si sposta la cartella dei log della CLI con --log-dir, e si leggono gli eventi in streaming. Servono soprattutto tool.execution_complete, che scatta quando uno strumento termina sia con successo sia con errore, e session.error, che porta campi come errorType, message e statusCode. Per correlare l’esecuzione con il resto del sistema si configura la telemetria OpenTelemetry: l’SDK può propagare il W3C Trace Context (traceparent/tracestate) sui payload JSON-RPC, così gli span dell’applicazione e quelli della CLI finiscono in un’unica traccia distribuita.

{
  "otlpEndpoint": "http://localhost:4318",
  "otlpProtocol": "http/protobuf",
  "exporterType": "otlp-http",
  "captureContent": false
}

Nei GitHub Agentic Workflows il Markdown viene compilato in un file .lock.yml irrobustito, quindi l’esecuzione è una run di GitHub Actions e si legge come tale: i log del workflow, più gh aw logs per l’elenco delle run recenti con durata e consumo di token e gh aw audit RUN-ID per ispezionare una singola run.

Un’evidenza che si dimentica sempre: il firewall

L’accesso a internet del cloud agent è limitato per impostazione predefinita da un firewall. Quando una richiesta viene bloccata, l’avviso non sta nascosto nei log: viene aggiunto al corpo della pull request se è nuova, oppure a un commento se la pull request esiste già, e indica quale indirizzo è stato bloccato e quale comando lo ha richiesto. È la traccia che trasforma un “l’agente non è riuscito a installare le dipendenze” in una causa accertata. La configurazione vive in Settings > Copilot > Internet access, con le voci Enable firewall, Recommended allowlist e Allow repository custom rules.

Attenzione a un secondo sintomo ingannevole: sui push di Copilot i workflow non partono da soli, va premuto Approve and run workflows nel merge box. Se i check risultano assenti, il fallimento non è dell’agente, semplicemente la validazione non è mai stata eseguita.

Dare un nome alla causa

L’esame chiede di classificare, non solo di trovare. Tre classi coprono quasi tutto.

Un errore di ragionamento significa che il piano era sbagliato: l’agente ha capito male l’obiettivo, ha scelto una strategia non pertinente, ha concluso troppo presto. Si vede nel ragionamento interno esposto dai session log, oppure nel piano stesso, che sul cloud agent è un artefatto rivedibile: la doc descrive un flusso in cui si fa ricerca, si crea un piano e si itera con Copilot finché corrisponde all’intento, prima di scrivere codice.

Un uso improprio dello strumento è quando lo strumento giusto viene invocato male, oppure viene scelto quello sbagliato: argomenti incoerenti, output non interpretato, un tool chiamato dove ne serviva un altro. L’evidenza sta nella sequenza delle chiamate — nei session log sul cloud agent, in tool.execution_complete con l’SDK.

Un problema di contesto o di ambiente è tutto ciò che sta fuori dal modello: una dipendenza non installabile, una richiesta di rete bloccata dal firewall, un percorso negato dal sandbox locale, un permesso mancante, istruzioni assenti nel repository.

Che cosa verifica l’esame

Non tanto il nome del log quanto la mappatura fra evidenza e rimedio, perché la stessa schermata porta ad azioni opposte secondo la classificazione. Un test che non passa dopo un errore di ragionamento si affronta rendendo espliciti obiettivo e criteri di accettazione, per esempio con istruzioni personalizzate nel repository. Lo stesso test che non passa perché il registry era bloccato non si aggiusta riscrivendo il prompt: si estende l’allowlist. Riscrivere le istruzioni per un problema di ambiente è la confusione tipica che l’esame va a cercare. Regola pratica: rileggere il log e l’avviso del firewall prima di toccare qualsiasi istruzione.