Esecuzioni gestite degli agenti

Le esecuzioni gestite degli agenti ti permettono di avviare agenti AI autonomi direttamente da Archyl. Assegna loro un compito, scegli il profilo che ne definisce il comportamento, connettili a servizi esterni tramite connettori MCP, imposta una pianificazione ricorrente e lasciali lavorare sul tuo codebase con il contesto architetturale completo.

Vai su Hub Agenti → Esecuzioni nella barra laterale per gestire le tue esecuzioni, su Hub Agenti → Profili per definire il comportamento degli agenti, oppure su Hub Agenti → Pianificazioni per l'automazione ricorrente.

Panoramica

Un'esecuzione gestita corrisponde a una singola esecuzione dell'agente. L'agente:

1. Clona il repository del tuo progetto in uno spazio di lavoro nuovo sul worker degli agenti
2. Riceve il contesto architetturale (modello C4, ADR, regole di conformità, contratti API, stack tecnologico) insieme al briefing della sessione di lavoro: gli elementi toccati dal compito, ciò che le sessioni precedenti hanno imparato su di essi e il verdetto del preflight
3. Esegue il compito che hai definito, invocando strumenti e prendendo decisioni entro i limiti del suo profilo
4. Pubblica le modifiche al codice come pull request e restituisce un resoconto con la traccia completa di ogni azione

Le esecuzioni possono essere avviate manualmente (una tantum) o automaticamente tramite pianificazioni.

Avviare un'esecuzione

1. Vai su Hub Agenti → Esecuzioni
2. Seleziona il tuo progetto dal menu a tendina
3. Clicca su Nuova esecuzione
4. Scegli un profilo
5. Scrivi una descrizione del compito (ad esempio, "Controlla le dipendenze obsolete e crea un riepilogo")
6. Facoltativamente, associa dei connettori (vedi sotto)
7. Clicca su Avvia esecuzione

L'agente inizia a lavorare immediatamente. Puoi monitorare l'avanzamento in tempo reale nella pagina di dettaglio dell'esecuzione.

Profili degli agenti

Un profilo è una definizione riutilizzabile del comportamento di un agente. Ogni esecuzione e ogni pianificazione ne usa uno. Alla prima visita Archyl crea un profilo backend-fixer per la tua organizzazione; puoi crearne altri in Hub Agenti → Profili.

Eliminando un profilo, la cronologia delle esecuzioni che ha svolto viene conservata. Le pianificazioni che lo usavano vengono messe in pausa e contrassegnate come Profilo eliminato; scegli un altro profilo nella pianificazione per riprenderla.

Skill

Le skill sono playbook mantenuti da Archyl, sempre allineati agli strumenti di cui gli agenti dispongono davvero. Abilitale per profilo invece di copiare istruzioni nel prompt.

Un profilo con una skill sconosciuta o un pattern di strumenti consentiti non valido viene rifiutato al salvataggio.

Il profilo predefinito backend-fixer abilita Architecture memory, Conformance first e Decision records.

Pagina di dettaglio dell'esecuzione

Ogni esecuzione ha una pagina di dettaglio che mostra:

Il feed degli eventi mostra schede espandibili per ogni azione:

• Chiamate a strumenti — Mostra il nome dello strumento, i parametri di input e l'output. Ogni scheda visualizza un'etichetta di origine che indica da quale connettore proviene lo strumento (ad esempio github, archyl, linear).
• Messaggi — Il ragionamento e le decisioni dell'agente.
• Risultato — L'esito, il consumo di token, la pull request e i file modificati dall'agente.
• Errori — Evidenziati per una rapida identificazione.

Guidare un agente in esecuzione

Mentre un'esecuzione è in corso, scrivi un messaggio nella casella di guida per reindirizzare l'agente senza annullarlo ("salta la migrazione, concentrati sull'handler"). Il messaggio viene messo in coda subito e inserito nella conversazione dell'agente al passo successivo; il feed mostra Messaggio di guida consegnato all'agente non appena l'agente lo ha ricevuto.

Quando un'esecuzione si ferma prima del tempo

Se un'esecuzione fallisce, raggiunge il limite di costo o di tempo, o esaurisce le iterazioni, il lavoro già svolto non va perso: Archyl lo pubblica come pull request in bozza che spiega perché l'esecuzione si è fermata. Vedi Pull request più sotto. Un'esecuzione che annulli non pubblica nulla.

Garanzie di affidabilità

• I worker non più attivi vengono rilevati. Il worker degli agenti dà segni di vita ogni 10 secondi. Un'esecuzione il cui worker tace da 3 minuti, o che è ancora in corso 10 minuti dopo il suo limite di tempo, viene contrassegnata automaticamente come failed e il suo slot viene liberato.
• Le esecuzioni bloccate non occupano slot. Un'esecuzione che nessun worker degli agenti ha preso in carico entro 10 minuti fallisce, e così anche un'esecuzione che ha atteso la risposta di una persona per più di 1 ora e 10 minuti.
• Le credenziali non sopravvivono alle esecuzioni. Ogni esecuzione riceve una propria chiave API Archyl di breve durata, revocata non appena l'esecuzione termina.
• L'annullamento raggiunge l'agente. Un'esecuzione annullata si ferma al successivo segnale di vita anche se la richiesta diretta di arresto non ha mai raggiunto il worker.

Sessioni di lavoro e coordinamento

Ogni esecuzione è racchiusa in una sessione di lavoro Archyl, il protocollo che l'harness di Archyl offre agli agenti di coding locali. La piattaforma apre e chiude la sessione; l'agente non la gestisce mai.

La sessione di lavoro di un'esecuzione

All'avvio di un'esecuzione, Archyl apre una sessione sugli elementi architetturali toccati dal task. Prende i lease su quegli elementi, calcola il verdetto del gate di preflight (allow, warn o deny) e inserisce nel briefing dell'agente le decisioni, i guardrail e le memorie pertinenti. Il verdetto compare nel feed degli eventi come evento Controllo.

Rispettare il lavoro degli altri agenti

Rispetta il lavoro degli altri agenti è un'impostazione del profilo, nella sezione Coordinamento, disattivata per impostazione predefinita. Quando è attiva, la sessione viene aperta in esclusiva:

• Un altro agente occupa gli elementi. Se un altro agente ha un lease sugli stessi elementi, che sia un agente di coding come Claude Code o un'altra esecuzione gestita, l'esecuzione viene rifiutata. Il motivo indica chi ci sta lavorando.
• Il gate si limita ad avvisare, ad esempio perché si applica un guardrail di livello error. L'esecuzione resta In attesa di approvazione senza occupare uno slot di concorrenza. La pagina dell'esecuzione mostra i motivi, con Approva e avvia e Annulla esecuzione.

L'approvazione ricontrolla il gate: un conflitto emerso nel frattempo fa comunque rifiutare l'esecuzione. Un'esecuzione che nessuno approva entro 24 ore viene annullata.

Con l'impostazione disattivata, l'esecuzione parte qualunque sia il verdetto del gate; l'agente legge i motivi nel suo briefing.

Guard sulle scritture dei file

Ogni volta che l'agente lavora in un repository, collegato al progetto o aperto tramite il connettore GitHub, ogni chiamata a write_file ed edit_file viene verificata rispetto alle regole di conformità del progetto prima che la modifica venga applicata:

Se è la verifica stessa a fallire, la scrittura passa: il Guard non blocca mai un agente per un proprio errore. Si comporta come l'hook Guard degli agenti di coding locali, descritto nella guida all'harness.

Esito della sessione di lavoro

Prima di terminare, l'agente riporta il proprio esito: un riepilogo, le decisioni, i follow-up e le memorie su cui si è basato. Quando l'esecuzione termina, Archyl:

1. Attribuisce i file modificati alla sessione, individuando così gli elementi in lease su cui il lavoro è davvero ricaduto
2. Chiude la sessione e salva il riepilogo come memoria su quegli elementi
3. Registra le decisioni come memoria del progetto e apre una bozza di richiesta di modifica architetturale da revisionare. Solo un'esecuzione riuscita registra decisioni

La pagina dell'esecuzione mostra una scheda Esito della sessione di lavoro con il riepilogo, le decisioni, i follow-up, gli elementi toccati e un link alla richiesta di modifica. Gli elementi occupati da un'altra sessione sono segnalati come Occupato da un'altra sessione di lavoro.

Seguire un'esecuzione in tempo reale

La pagina di un'esecuzione ha due viste: Attività, il feed degli eventi, e Modifiche, i file scritti dall'agente. Quando l'agente ha bisogno di te, un banner sopra le viste indica cosa sta aspettando (In attesa della tua revisione del piano o L'agente ha una domanda) e ti porta lì.

Il piano

Prima di modificare qualsiasi cosa, l'agente condivide un piano: un riepilogo di una frase e una manciata di passi concreti, al massimo 12. Il pannello Piano, in cima alla pagina dell'esecuzione, lo trasforma in una checklist. L'agente segna ogni passo come In corso, Fatto o Saltato, a volte con una breve nota, e il pannello mostra il passo in corso e l'avanzamento (3/7).

Rivedi prima il piano è un'impostazione del profilo, nella sezione Coordinamento, disattivata per impostazione predefinita. Quando è attiva, l'agente attende una revisione prima di modificare qualsiasi cosa:

1. Il pannello passa a Rivedi il piano. Puoi rinominare i passi, aggiungere dettagli e aggiungere, rimuovere o riordinare i passi.
2. Approva il piano (Approva il piano modificato dopo che l'hai modificato) lascia proseguire l'agente. La tua versione modificata è il piano che l'agente segue e che la checklist traccia.
3. Richiedi modifiche invia il tuo feedback. L'agente rivede il piano e ti propone una nuova revisione da esaminare. Le revisioni precedenti restano nel feed.

Finché un piano non è approvato, l'agente può leggere ma non modificare nulla: la scrittura di file e qualsiasi strumento che crea, aggiorna, elimina, collega, importa, fa push o merge (su Archyl e su ogni connettore, ad esempio linear__create_issue) vengono rifiutati, così come remember. All'agente viene detto di attendere la revisione.

Domande

Quando una decisione richiede una persona, ad esempio un requisito ambiguo, un compromesso senza un'opzione chiaramente migliore o qualcosa di distruttivo, l'agente chiede. La domanda compare sopra il feed, con le Risposte suggerite quando l'agente ne propone, e una casella per una risposta libera (Cmd/Ctrl + Enter la invia). Chiunque possa modificare il progetto può rispondere, e il feed registra chi l'ha fatto.

L'agente pone al massimo 5 domande per esecuzione, e ha l'istruzione di non chiedere mai qualcosa che può cercare da solo.

Quando l'agente ti aspetta

Mentre l'agente attende una revisione del piano o una risposta, l'esecuzione mostra In attesa di te e compare sotto Serve il tuo intervento nell'elenco delle esecuzioni, insieme alle esecuzioni trattenute in In attesa di approvazione.

• L'attesa non conta nel limite di tempo dell'esecuzione: la sua scadenza slitta in avanti del tempo trascorso ad aspettare. L'esecuzione mantiene il suo slot di esecuzione simultanea.
• Una domanda a cui nessuno risponde entro un'ora: l'agente prosegue secondo il proprio giudizio e indica nel suo esito l'ipotesi che ha fatto.
• Un piano che nessuno rivede entro un'ora: l'esecuzione fallisce, senza aver modificato nulla.

Dove lavora l'agente

L'agente legge e modifica il codice nel suo spazio di lavoro, un clone del repository:

• Repository collegato al progetto: Archyl lo clona all'avvio dell'esecuzione.
• Nessun repository collegato, connettore GitHub associato: l'agente clona da solo il repository di cui si occupa il compito, con le credenziali del connettore, prima di toccare qualsiasi file. È supportato solo il server MCP ospitato da GitHub (api.githubcopilot.com). Il connettore deve autenticarsi con un header Authorization: Bearer, e il suo token deve avere accesso al repository.

Una volta aperto uno spazio di lavoro, l'agente modifica i file solo lì: inviare file o aprire pull request tramite gli strumenti di un connettore viene rifiutato. È così che ogni modifica passa dal Guard, compare nella vista Modifiche e finisce in un'unica pull request.

Modifiche

Modifiche elenca ogni file che l'agente scrive, nel momento in cui lo scrive: Aggiunto, Modificato o Bloccato, con le righe aggiunte e rimosse per file e per l'intera esecuzione. Seleziona un file per vedere cosa ha cambiato ogni scrittura.

• Se il Guard rifiuta una scrittura, il file risulta Bloccato: il diff mostra cosa l'agente ha tentato di scrivere, con la regola violata. Una scrittura che il Guard si è limitato a segnalare passa, con un avviso sul file.
• I diff lunghi vengono troncati dopo 600 righe, e i file oltre 128 KB compaiono senza diff.

Commentare una riga

Rivedi il diff mentre l'agente lavora. In Modifiche, fai clic su un numero di riga per commentare quella riga, poi su Invia all'agente (Cmd/Ctrl + Invio). L'agente riceve il file, la riga e il suo contenuto, gestisce il commento e poi prosegue con il suo piano.

• Il commento compare sotto la sua riga, In coda finché l'agente non lo legge, poi Consegnato. Compare anche in Attività, e ogni file mostra quanti commenti ha.
• Puoi commentare righe aggiunte, invariate e rimosse. Le scritture bloccate dal Guard non si possono commentare.
• I commenti sono accettati mentre l'agente lavora o ti aspetta. Un commento ancora In coda al termine dell'esecuzione risulta Non consegnato.

In un'esecuzione terminata, un commento diventa una nota per quella successiva: Tieni per il seguito lo conserva nel tuo browser, e la barra sopra i file (3 commenti per il seguito) prosegue l'esecuzione con quei commenti (Prosegui con questi).

Pull request

Al termine dell'esecuzione, Archyl esegue il commit delle modifiche dello spazio di lavoro su un branch chiamato archyl/agent- seguito dai primi 8 caratteri dell'ID dell'esecuzione, e apre una pull request verso il branch da cui è partito il clone. Il suo link compare in cima a Modifiche (Apri la pull request) e nel risultato.

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.

Le pull request vengono aperte su github.com, gitlab.com e bitbucket.org. Archyl invia le tue credenziali Git solo a questi host: un repository su un server Git self-hosted (GitHub Enterprise, un GitLab privato, Azure DevOps, Gitea) viene clonato senza credenziali, quindi uno privato non può essere clonato, e non viene aperta alcuna pull request.

Proseguire un'esecuzione

Un'esecuzione terminata, qualunque sia il suo esito, offre due pulsanti:

• Prosegui avvia una nuova esecuzione che riprende il lavoro di questa. Scrivi cosa deve fare l'agente dopo: i tuoi commenti per il seguito precompilano le istruzioni, uno per riga (percorso:riga — commento). Il profilo predefinito è quello dell'esecuzione, e puoi scegliere i connettori.
• Esegui di nuovo apre la finestra di avvio con lo stesso compito e lo stesso profilo, per ripartire da zero.

Una prosecuzione sa cosa era stato chiesto all'esecuzione precedente e cosa ha fatto. Parte dal branch pubblicato da quell'esecuzione, esegue il commit su di esso e aggiunge le sue modifiche alla stessa pull request invece di aprirne un'altra. Se l'esecuzione precedente ha inviato il suo branch senza aprire una pull request, la prosecuzione ne apre una, verso il branch a cui punterebbe una nuova esecuzione. Se l'esecuzione precedente aveva aperto un repository tramite il connettore GitHub, la prosecuzione lo riapre su quel branch.

• Se il branch non esiste più (ad esempio perché unito ed eliminato), la prosecuzione parte dal branch da cui partirebbe una nuova esecuzione, il branch collegato al progetto o il branch predefinito del repository, e apre una nuova pull request. Il feed lo segnala.
• Una pull request in bozza resta in bozza: contrassegnala come pronta per la revisione quando il lavoro è finito.
• Archyl prosegue solo sui branch creati dai suoi agenti, mai sui tuoi.

La pagina della nuova esecuzione rimanda all'esecuzione che prosegue (Prosegue l'esecuzione), e l'esecuzione precedente rimanda alle sue prosecuzioni (Proseguita in). Un'esecuzione ancora in corso non si può proseguire: commentane piuttosto le righe.

Connettori MCP

I connettori ti permettono di associare servizi esterni alle esecuzioni dei tuoi agenti. Qualsiasi servizio che espone un server MCP (Model Context Protocol) può essere connesso.

Servizi supportati

Creare un connettore

1. Vai su Hub Agenti → Connettori
2. Clicca su Nuovo connettore
3. Inserisci un nome (ad esempio, "github")
4. Incolla l'URL del server MCP
5. Aggiungi header di autenticazione se necessario
6. Clicca su Crea connettore — Archyl interroga il server e mostra gli strumenti disponibili

Namespace degli strumenti

Quando un connettore viene associato a un'esecuzione, i suoi strumenti vengono prefissati con il nome del connettore:

Gli strumenti del server MCP integrato di Archyl non hanno prefisso (ad esempio get_agent_context, list_conformance_rules).

Questo sistema di namespace evita collisioni tra i nomi degli strumenti, rende il feed degli eventi facile da consultare e permette agli strumenti consentiti di un profilo di coprire un intero connettore con un solo pattern come github__*.

Pianificazioni

Le pianificazioni ti permettono di definire esecuzioni ricorrenti degli agenti utilizzando espressioni cron standard.

Creare una pianificazione

1. Vai su Hub Agenti → Pianificazioni
2. Clicca su Nuova pianificazione
3. Scegli un profilo e scrivi la descrizione del compito
4. Seleziona un'espressione cron (sono disponibili preset o puoi inserirne una personalizzata)
5. Associa dei connettori se necessario
6. Clicca su Crea pianificazione

Gestione delle pianificazioni

Ogni pianificazione mostra:

• Espressione cron — Quando l'agente viene eseguito
• Prossima esecuzione — Quando è pianificata la prossima esecuzione
• Ultima esecuzione — Quando l'agente è stato eseguito l'ultima volta
• Stato — Attiva o in pausa, oppure Profilo eliminato quando il suo profilo è stato eliminato

Puoi:

• Mettere in pausa una pianificazione senza eliminarla
• Riprendere una pianificazione in pausa
• Esegui ora — Eseguire immediatamente al di fuori della cadenza normale
• Modificare il testo del compito, l'espressione cron o i connettori associati
• Eliminare la pianificazione

Una pianificazione il cui profilo è stato eliminato resta in pausa: riprenderla o usare Esegui ora viene rifiutato finché non modifichi la pianificazione e scegli un altro profilo.

Esempi di pianificazioni

Contesto architetturale

Ogni esecuzione gestita riceve automaticamente accesso al server MCP del tuo progetto Archyl. L'agente può:

• Interrogare il modello C4 per comprendere i confini del sistema
• Leggere gli ADR per comprendere le decisioni architetturali passate
• Verificare le regole di conformità per sapere quali pattern seguire
• Consultare i contratti API per comprendere le interfacce dei servizi
• Controllare le assegnazioni tecnologiche per scegliere gli strumenti giusti
• Recuperare e memorizzare fatti sugli elementi tramite la memoria architetturale

Questo contesto viene iniettato prima che l'agente inizi a lavorare: non ha bisogno di scoprire la tua architettura da zero. Inoltre ogni esecuzione è racchiusa in una sessione di lavoro dell'harness, così il suo esito diventa memoria degli elementi che ha toccato.

Provider di IA

Le esecuzioni usano il modello gestito da Archyl, a meno che la tua organizzazione non abbia attivato Porta il tuo provider di IA. Con BYO attivo, le esecuzioni girano sul tuo provider con le tue credenziali: Anthropic, AWS Bedrock, OpenAI o un endpoint compatibile OpenAI che implementa la Responses API. Google Gemini non può ancora eseguire agenti gestiti: le esecuzioni vengono rifiutate con un messaggio esplicito invece di ripiegare in silenzio sul modello di Archyl.

Quote e concorrenza

Le esecuzioni gestite degli agenti sono disponibili nei piani Scale e Custom. L'utilizzo viene tracciato per organizzazione con quote mensili, visualizzate in cima alle pagine Esecuzioni e Pianificazioni. Anche proseguire un'esecuzione e approvare un'esecuzione trattenuta contano come esecuzioni. Le organizzazioni con BYO AI attivo non consumano quota, sia per le esecuzioni manuali sia per quelle pianificate.

Ogni esecuzione attiva (pending, running o waiting_for_input) occupa uno degli slot di esecuzione simultanea della tua organizzazione. Lo slot si libera nel momento in cui l'esecuzione termina, qualunque sia il motivo.

Buone pratiche

• Sii specifico nelle descrizioni dei compiti — "Controlla i pacchetti Go con CVE note ed elencali con la relativa gravità" funziona meglio di "controlla le dipendenze"
• Dai a ogni lavoro il suo profilo — Un revisore in sola lettura con allowedTools limitato a list_*, get_* e read_file non può modificare nulla per errore.
• Associa solo i connettori necessari — Ogni connettore aggiunge strumenti al contesto dell'agente. Meno strumenti significa un'esecuzione più focalizzata.
• Inizia con esecuzioni manuali — Testa la descrizione del compito con un'esecuzione una tantum prima di creare una pianificazione.
• Usa le regole di conformità insieme — Definisci prima i guardrail, poi abilita la skill Conformance first perché le esecuzioni le verifichino automaticamente.