Rivedi il tuo agente mentre lavora

Alle 10:40 avvii un'esecuzione gestita sul servizio di fatturazione: "Documenta come configurare ed eseguire il servizio in locale." Alle 11:02 arriva una pull request con un nuovo docs/setup.md. È fatto bene. La riga 12 dice ai nuovi arrivati di lanciare go build ./..., che salta i build tag di cui il servizio ha bisogno, quindi la loro prima build fallisce in un modo che il documento non spiega mai. E più o meno al sesto minuto, l'agente ha deciso che la sezione Docker del README era obsoleta e l'ha riscritta. Nessuno gliel'aveva chiesto.

Niente di tutto questo è difficile da correggere in review. Quello che la review non può restituire sono i venti minuti nel mezzo. L'agente ha fatto quelle scelte presto, senza nessuno a verificarle, e ci ha costruito sopra tutto il resto. La correzione è allora una seconda esecuzione che riparte da zero, rilegge gli stessi file e apre una seconda pull request.

È così che funzionavano finora le esecuzioni gestite degli agenti di Archyl. La pagina dell'esecuzione aveva un feed degli eventi e una casella di guida, quindi potevi seguire le chiamate ai tool se tenevi aperta la scheda, su un laptop o dal telefono. Ma quello che l'agente intendeva fare, e quello che aveva scritto fin lì, dovevi ricostruirlo dai payload delle chiamate ai tool o scoprirlo dalla pull request. Per un audit notturno delle dipendenze va bene. Per una modifica che rivedrai comunque, mette la review proprio nel punto in cui costa di più.

Ora le esecuzioni hanno un ciclo di review. Ecco cosa è cambiato:

Il resto di questo post rifà lo stesso task, nel nuovo modo, nell'ordine in cui lo vivresti. Il task è un esempio; ogni messaggio citato qui sotto ha il formato che l'agente riceve davvero.

Prima viene il piano

Prima di toccare un file, all'agente viene chiesto di chiamare propose_plan con un riepilogo di una frase e qualche passo concreto. Il prompt ne chiede da 3 a 8, e il tool ne rifiuta più di 12, così un piano resta leggibile a colpo d'occhio. Il pannello Piano, in cima alla pagina dell'esecuzione, lo trasforma in una checklist. Mentre lavora, l'agente segna ogni passo come In corso, Fatto o Saltato, a volte con una breve nota, e il pannello mostra il passo su cui si trova e l'avanzamento (2/4).

Per impostazione predefinita, il piano viene condiviso e l'agente parte subito. Attiva Rivedi prima il piano, nella sezione Coordinamento del profilo agente, e invece ti aspetta. Il pannello passa alla modalità di review, dove puoi rinominare i passi, aggiungere dettagli e aggiungere, rimuovere o riordinare i passi.

Per il documento di setup, l'agente ha proposto cinque passi. Il quarto era "Aggiornare la sezione Docker del README", la riscrittura che nessuno aveva chiesto. Lo rimuovi, aggiungi un dettaglio al passo 2, e il pulsante che diceva Approva il piano ora dice Approva il piano modificato. Ecco cosa riceve l'agente:

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

La tua versione modificata è il piano che l'agente segue, e quello che la checklist traccia. Quando un piano è sbagliato, e non solo un po' fuori strada, Richiedi modifiche invia invece un feedback. L'agente lo rivede e propone una nuova revisione, e le revisioni precedenti restano nel feed, così puoi vedere cosa ha cambiato il tuo feedback.

Finché un piano non è approvato, l'agente non può scrivere file, modificare il modello architetturale tramite i tool di Archyl né fare push su un repository tramite un connettore. Non è una riga del prompt che potrebbe convincersi ad aggirare. Le chiamate vengono rifiutate, e l'agente legge:

changes are refused until your plan is approved: call propose_plan and wait for the review

Se nessuno rivede il piano entro un'ora, l'esecuzione fallisce senza aver modificato nulla. Un profilo che richiede la review non può saltarla solo perché non si è presentato nessuno.

Domande, quando deve decidere una persona

Certe decisioni l'agente non dovrebbe prenderle da solo: un requisito ambiguo, un compromesso senza un vincitore chiaro, qualcosa di distruttivo. Per quelle ha ask_human. Le sue istruzioni gli dicono di non chiedere mai qualcosa che può cercare da solo, e ha al massimo 5 domande per esecuzione, così non può restituirti il lavoro una domanda alla volta.

A metà del passo 2, l'agente trova una STAGING_DATABASE_URL nella configurazione. Documentarla sarebbe utile, se non fosse che lo staging richiede un accesso VPN che i nuovi arrivati non ricevono nella prima settimana. Nel repository non c'è scritto da nessuna parte, quindi chiede.

La domanda compare sopra il feed, con le Risposte suggerite quando l'agente ne propone ("Lascia fuori lo staging", "Menzionalo, con una nota sull'accesso VPN"), e una casella per la tua risposta (Cmd/Ctrl + Enter la invia). Chiunque possa modificare il progetto può rispondere, e il feed registra chi l'ha fatto. L'agente legge The human answered: Leave staging out e va avanti.

Una domanda a cui nessuno risponde entro un'ora non fa fallire l'esecuzione. L'agente prosegue secondo il proprio giudizio e indica nel suo esito l'ipotesi che ha fatto. È l'opposto del piano, e la differenza sta in cosa c'è in gioco: un piano non rivisto significa che non si è concordato niente, mentre una domanda senza risposta è solo un'altra decisione del tipo che l'agente prende per tutta l'esecuzione.

Quanto costa aspettare

Mentre l'agente aspetta una revisione del piano o una risposta, l'esecuzione mostra In attesa di te, e l'elenco delle esecuzioni la mette sotto Serve il tuo intervento. Un banner sopra il feed dice cosa sta aspettando, In attesa della tua revisione del piano o L'agente ha una domanda, e ti porta lì.

L'attesa non conta nel limite di tempo dell'esecuzione. La sua scadenza slitta in avanti del tempo passato ad aspettare, quindi un'esecuzione con un limite di 30 minuti che ti ha aspettato per 20 minuti ha comunque 30 minuti di lavoro. Mantiene però il suo slot di esecuzione simultanea. Un'esecuzione In attesa di approvazione non è ancora partita, quindi non trattiene niente, ma un'esecuzione in attesa è a metà di una conversazione, con il suo workspace aperto, pronta a riprendere non appena la tua risposta la raggiunge.

Il diff, mentre viene scritto

La pagina dell'esecuzione ora ha due viste: Attività, il feed degli eventi, e Modifiche. Modifiche elenca ogni file che l'agente scrive, nel momento in cui lo scrive, con uno stato (Aggiunto, Modificato o Bloccato) e le righe aggiunte e rimosse, per file e per l'intera esecuzione. Seleziona un file per vedere cosa ha cambiato ogni scrittura (Modifica 2 di 3), non solo lo stato finale.

Il Guard, il controllo di conformità su ogni scrittura di file che ora gira dentro il worker, compare anche qui. Una scrittura che ha rifiutato risulta Bloccato: il diff mostra cosa l'agente ha tentato di scrivere, con la regola violata, anche se quel contenuto non è mai arrivato nel file. Una scrittura che si è limitato a segnalare passa, con un avviso sul file. Un rifiuto che prima trovavi nel risultato di un tool ora è un diff che puoi leggere.

Due limiti: i diff lunghi vengono troncati dopo 600 righe, e i file oltre 128 KB compaiono senza diff.

Un commento sulla riga 12

Torniamo a go build ./.... Non devi aspettare la pull request. In Modifiche, fai clic sul numero di riga, scrivi il commento e poi Invia all'agente (Cmd/Ctrl + Enter). Al passo successivo l'agente lo riceve come un commento di code review, con il file, la riga e il suo contenuto:

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

Corregge la riga, poi torna al suo passo. Sotto la riga, il commento riporta In coda finché l'agente non lo prende in carico, poi Consegnato. Compare anche in Attività, e ogni file nell'elenco mostra quanti commenti ha. La correzione, quando arriva, arriva come modifica successiva del file, quindi il diff in cui hai lasciato il commento è anche quello in cui la verifichi.

Puoi commentare righe aggiunte, invariate e rimosse. Un commento su una riga rimossa arriva all'agente come un commento su "the lines you removed", ed è così che gli dici di rimettere un controllo. I commenti sono accettati mentre l'agente lavora o ti aspetta, e un agente in attesa li legge quando riprende. Un commento ancora In coda quando l'esecuzione finisce risulta Non consegnato. Le scritture bloccate dal Guard non si possono commentare.

La casella di guida c'è ancora, per reindirizzare l'agente con testo libero senza annullare l'esecuzione ("salta la migrazione, concentrati sull'handler"). Un commento di riga è lo stesso meccanismo, fissato a una riga. Quello che ti risparmia è il preambolo: "in docs/setup.md, dove hai scritto go build" è già nel messaggio.

L'esecuzione che non aveva niente da rivedere

Mentre costruivo Modifiche, ho chiesto a un'esecuzione di aggiungere documentazione a uno dei nostri repository Git, e ho guardato la vista restare vuota. Nessun file, nessun diff, niente da commentare.

Il progetto non aveva un repository collegato, quindi Archyl non aveva clonato niente. L'esecuzione però aveva un connettore GitHub, e l'agente ha fatto la cosa ragionevole con i tool che aveva davanti: ha scritto i file direttamente su GitHub con il tool push_files del connettore. Niente è passato da un workspace. Quindi niente è passato dal Guard, niente è comparso in Modifiche, e il ciclo di review che stavo costruendo non aveva niente da rivedere.

Ora l'agente lavora in un workspace in entrambi i casi:

• Al progetto è collegato un repository. Archyl lo clona all'avvio dell'esecuzione, come prima.
• Nessun repository collegato, ma è associato un connettore GitHub. L'agente clona da solo il repository di cui parla il task, chiamando open_repository con le credenziali del connettore, prima di toccare qualsiasi file. Funziona solo con il server MCP ospitato da GitHub (api.githubcopilot.com), e il token deve avere accesso al repository.

Una volta aperto un workspace, i tool del connettore che scrivono su un repository (push_files, create_or_update_file, delete_file, create_pull_request) vengono rifiutati, e l'agente legge:

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

È questa regola che fa passare ogni modifica dal Guard, la mette in Modifiche e la porta in un'unica pull request.

Quando l'esecuzione finisce

Archyl esegue il commit delle modifiche del workspace su archyl/agent-<run id>, usando i primi otto caratteri dell'ID dell'esecuzione, e apre una pull request verso il branch da cui è partito il clone. Il link sta in cima a Modifiche (Apri la pull request) e nel risultato. Il modo in cui l'esecuzione finisce decide cosa viene pubblicato:

Su GitLab la bozza è una merge request Draft:. Su Bitbucket il branch viene inviato senza pull request. Un'esecuzione che non ha modificato alcun file non pubblica nulla.

I tuoi commenti diventano l'esecuzione successiva

La review non si ferma quando si ferma l'esecuzione. La pull request è aperta, e stai leggendo il diff finale in Modifiche. Un commento su un'esecuzione terminata non ha più un agente da raggiungere, quindi diventa una nota per la successiva: Tieni per il seguito lo conserva nel tuo browser. Una barra sopra i file li conta (3 commenti per il seguito) e propone Prosegui con questi.

Ogni esecuzione terminata, qualunque sia il suo esito, offre due pulsanti. Esegui di nuovo apre la finestra di avvio con lo stesso task e lo stesso profilo, per una nuova esecuzione da zero: la scelta giusta quando il primo tentativo è andato in una direzione su cui non vuoi costruire. Prosegui avvia una nuova esecuzione che riprende il lavoro di questa, con le istruzioni precompilate a partire dai tuoi commenti per il seguito, se ne hai lasciati, uno per riga:

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

Modificali come vuoi. Il profilo predefinito è quello dell'esecuzione, e puoi scegliere i connettori.

Stesso branch, stessa pull request

Una prosecuzione è più di una nuova esecuzione con un prompt più lungo. Parte dal branch pubblicato dall'esecuzione precedente, esegue il commit su di esso e aggiunge le sue modifiche alla stessa pull request invece di aprirne un'altra. Se l'esecuzione precedente aveva aperto il suo repository tramite il connettore GitHub, la prosecuzione lo riapre su quel branch prima che l'agente parta.

All'agente viene anche detto su cosa sta costruendo. Il task precedente, cosa ha fatto quell'esecuzione (il riepilogo del suo esito, o perché si è fermata) e dove si trova il suo lavoro finiscono tutti in cima al suo prompt (gli ID, l'URL e il riepilogo sono esempi):

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

I revisori vedono crescere una sola pull request, non una scia di pull request. Il Copilot cloud agent di GitHub gestisce i follow-up allo stesso modo: menzioni @copilot in un commento su una pull request e, per impostazione predefinita, fa push dei commit sul branch di quella pull request (GitHub Docs). Una pull request per unità di lavoro è la forma giusta, e le prosecuzioni la rispettano.

Cosa aspettarsi nei casi limite:

• Il branch non c'è più, per esempio perché è stato unito ed eliminato. La prosecuzione parte dal branch predefinito e apre una nuova pull request, e una riga ambra nel feed lo segnala: "Impossibile recuperare il branch archyl/agent-4f1c2a9e dell'esecuzione precedente. Questa esecuzione parte dal branch predefinito e aprirà una nuova pull request."
• La pull request è in bozza. Resta in bozza. Contrassegnala come pronta per la review quando il lavoro è finito.
• Solo branch degli agenti. Archyl prosegue sui branch creati dai suoi agenti, quelli sotto archyl/, e non esegue mai commit su un branch creato da una persona.

Le due esecuzioni si collegano a vicenda: la nuova mostra Prosegue l'esecuzione, la precedente Proseguita in. Un'esecuzione ancora in corso non si può proseguire. Commentane piuttosto le righe.

La prosecuzione conserva anche il suo contesto architetturale. La sua sessione di lavoro viene aperta per il task precedente più il follow-up, non per il solo follow-up, così trova gli stessi elementi architetturali e la stessa memoria dell'esecuzione che prosegue. Conta più di quanto sembri. "Scrivi che make seed ha bisogno del container del database in esecuzione" non nomina nessun servizio, e una sessione aperta solo su quella riga avrebbe ben poco con cui fare match.

Cosa non fa

Il worker non ha una shell. Legge, scrive, modifica, elenca e cerca file, ma non può compilare il progetto né eseguire i test. In questo esempio può leggere il Makefile, non lanciare make build per verificare che il documento sia corretto. Un diff pulito non è una build che passa, e quel lavoro lo fa ancora la CI.

Un commento di riga è un'indicazione, non un gate. Non c'è uno stato di risolto, e niente verifica che l'agente abbia gestito un commento. Vedi la sua modifica successiva nel diff, e la giudichi tu.

Le note per il seguito vivono in un solo browser. Finché non prosegui l'esecuzione, i tuoi colleghi non vedono i commenti che hai tenuto per il seguito. I commenti inviati a un agente al lavoro sono diversi: stanno nel feed, visibili a tutti.

La review del piano presuppone che ci sia qualcuno. È un'impostazione per profilo, disattivata per impostazione predefinita, e ogni esecuzione su quel profilo la rispetta, comprese quelle pianificate. Un'esecuzione alle 3 di notte su un profilo con la review attiva aspetta un'ora, poi fallisce senza modificare nulla. Anche le domande aspettano un'ora, poi l'agente decide da solo.

Il clone tramite connettore funziona solo con GitHub. open_repository funziona con il server MCP ospitato da GitHub. Per qualsiasi altro host, collega il repository al progetto.

Da dove iniziare

Scegli un task piccolo che rivedresti comunque, ed eseguilo su un profilo con Rivedi prima il piano attivo. Tieni aperta la pagina dell'esecuzione. Modifica il piano prima di approvarlo, anche se ti limiti a rimuovere il passo che non avresti chiesto. In Modifiche, commenta la prima riga che avresti segnalato nella pull request, e guardala passare da In coda a Consegnato. Quando l'esecuzione finisce, lascia il resto come commenti per il seguito e premi Prosegui.

Lascia disattivata la review del piano sui profili usati dalle tue pianificazioni, a meno che qualcuno non sia sveglio per fare la review.

Piani, domande, il diff in tempo reale, i commenti di riga e le prosecuzioni fanno parte delle esecuzioni gestite degli agenti in Archyl. Ogni impostazione ed etichetta citata sopra è nella documentazione delle esecuzioni gestite degli agenti. Letture correlate: gli agenti gestiti ora rispondono all'Harness, per il Guard e le sessioni di lavoro su cui si basa tutto questo, e il lancio delle esecuzioni gestite degli agenti.