Panoramica dei workflow

I workflow sono il meccanismo di CodeCourier per orchestrare pipeline di agenti IA multi-step. Invece di inviare un singolo prompt a un singolo agente, i workflow ti permettono di definire una sequenza di step di agente - ciascuno con il proprio ruolo, strumento CLI, modello e istruzioni - che collaborano per produrre risultati di qualità superiore. Un workflow è un blueprint riutilizzabile; ogni volta che lo esegui, CodeCourier crea un run che traccia l’esecuzione attraverso ogni step.

Cos’è un workflow?

Un workflow in CodeCourier è un template che definisce come gli agenti IA collaborano su un task. Specifica:

• Quali agenti partecipano - Ogni step della pipeline corrisponde a una persona (una configurazione di agente denominata con il proprio strumento CLI, modello e istruzioni).
• In quale ordine vengono eseguiti - Gli step vengono eseguiti in sequenza. L’output di uno step diventa contesto per il successivo.
• Se un gruppo di step itera - Una coppia designer+checker può essere posta all’interno di un Iteration Block affinché il gruppo si ripeta finché il checker non approva, fino al limite di iterazioni del block. Gli step fuori da un Iteration Block vengono eseguiti una volta.
• Quale configurazione di sandbox usare - Il workflow porta una config di sandbox predefinita (strumento CLI, modello, risorse) che si applica a tutti gli step salvo override.

Concetti fondamentali

Blueprint vs. run

Esiste una distinzione cruciale tra un workflow e un run. Un workflow è un blueprint - definisce la struttura della pipeline ma non esegue nulla. Un run è un’istanza di esecuzione di un workflow. Quando avvii un workflow, CodeCourier crea un record di run che traccia lo stato di esecuzione, il prompt, la configurazione e i risultati. Puoi eseguire lo stesso workflow molte volte, producendo più run con prompt e configurazioni diversi.

Pipeline di persona

Il sistema di workflow di CodeCourier usa un’architettura di pipeline di persona. Ogni step della pipeline è legato a una persona - un’identità di agente preconfigurata con un ruolo specifico (designer, checker, optimizer, prompter, investigator, evaluator, judge o answerer), uno strumento CLI, un modello e istruzioni personalizzate. Questo significa che controlli non solo cosa fa l’agente, ma anche come lo fa.

Ad esempio, un workflow di code review potrebbe definire:

1. Una persona designer che usa Claude Opus per l’implementazione.
2. Una persona checker che usa Claude Sonnet per il testing E2E.
3. Una persona optimizer per la pulizia del codice dopo l’approvazione.

Iteration Block

L’iterazione è esplicita e opt-in: vive all’interno di un nodo Iteration Block. Gli step consecutivi che condividono lo stesso loopId formano un block, e il block si ripete come unità. Il pattern canonico è il block designer-checker:

1. Il designer implementa le modifiche richieste.
2. Il checker revisiona l’implementazione e produce un verdetto.
3. Se il checker passa, il block esce e la pipeline continua. Se il checker fallisce, il designer riceve il feedback del checker e il block viene rieseguito.

Ogni block ha il proprio limite loopMaxIterations (3 di default) per prevenire loop infiniti. Quando il limite viene raggiunto senza un verdetto positivo, il block termina e il run viene marcato come fallito.

Gli step fuori da un Iteration Block vengono eseguiti esattamente una volta. Un checker che non è dentro un block emette comunque un verdetto (persistito sul suo run step) ma non innesca un retry automatico.

Execution Block

Dietro le quinte l’orchestratore analizza la pipeline in execution block. Ogni block è o un block single (uno o più step che vengono eseguiti una volta) o un block loop (l’Iteration Block - un gruppo loopId che si ripete).

Modalità di esecuzione

I workflow possono essere avviati in diversi modi, ciascuno adatto a un caso d’uso differente:

• Run diretti - Un’esecuzione singola avviata manualmente dalla pagina di dettaglio del workflow o dalla pagina Runs. Il punto d’ingresso più comune per i task una tantum.
• Sprint Chain - Un’esecuzione batch che lancia lo stesso workflow più volte in sequenza, una volta per sprint. Ogni sprint produce la propria pull request. Le sprint chain sono ideali per il lavoro di sviluppo a fasi in cui ogni fase si basa sulla precedente. La chain traccia gli URL di PR per sprint e supporta la ripresa da qualsiasi indice di sprint se uno sprint fallisce.
• Recurring Task - Esecuzioni pianificate che si avviano automaticamente a una frequenza configurata (giornaliera, a giorni alterni, settimanale, bisettimanale o mensile). Ogni avvio crea un run standard con source scheduled. I task ricorrenti sono ideali per controlli di qualità continui, aggiornamenti di dipendenze automatizzati e altri workflow di manutenzione che devono girare a una cadenza regolare.
• Work Chain (guidate dalle issue) - Run sequenziali creati dalle work chain di sessione di issue. Ogni elemento della chain è una issue diversa elaborata attraverso la stessa pipeline di workflow.

Quality Scoring

Ogni workflow run partecipa al sistema di quality scoring di CodeCourier. Quando la pipeline include uno step Evaluator, quello step produce punteggi di qualità strutturati su cinque dimensioni:

• Correctness - L’implementazione soddisfa i requisiti?
• Type Safety - I tipi TypeScript sono corretti e completi?
• Code Style - Il codice segue le convenzioni del progetto?
• Test Coverage - Le modifiche sono coperte da test?
• Completeness - L’implementazione è completamente finita?

Questi cinque punteggi di dimensione vengono combinati in un punteggiocomposite (0-100). Ogni run traccia anche un qualityScore complessivo derivato da tutti gli step Evaluator della pipeline. I punteggi sono visibili nella vista di dettaglio del run e nel dashboard di Monitoring, abilitando l’analisi dei trend nel tempo.

Configurazione del workflow

Ogni workflow porta una configurazione che controlla come vengono eseguiti i suoi step:

• Nome e descrizione - Un nome leggibile e una descrizione opzionale per il blueprint del workflow.
• Config di sandbox predefinita - La configurazione base per tutte le sandbox create durante i run: template ID, timeout, memoria, numero di CPU, modello designer e modello checker.
• Step della pipeline di persona - Un array ordinato di riferimenti a persona. Gli step che appartengono a un Iteration Block portano un loopId (e il loopMaxIterations del block); gli step fuori da qualsiasi block non portano nessuno dei due e vengono eseguiti una volta.

Come vengono eseguiti i workflow

Quando un workflow viene avviato, si verifica la seguente sequenza:

1. Creazione del run - Un record di run viene creato nel database con il prompt, la configurazione e un riferimento al blueprint del workflow.
2. Dispatch Trigger.dev - Un task in background viene inviato alla coda di task di Trigger.dev. È l’orchestratore di workflow che gestisce l’intera esecuzione.
3. Esecuzione degli step - L’orchestratore elabora ogni execution block in sequenza. Per ogni step, crea una sandbox E2B, imposta l’ambiente, esegue l’agente IA e registra i risultati.
4. Gestione dei verdetti - Per gli step checker, il verdetto (pass/fail con feedback) determina se il loop continua.
5. Completamento del run - Quando tutti gli step terminano, lo status del run viene aggiornato a completed. Se uno step fallisce in modo fatale, il run viene marcato come failed.
6. Creazione di PR - Se il run ha lavorato su una branch Git, una pull request viene creata automaticamente.

Relazione con le altre funzionalità

• Sandbox - Ogni step di workflow crea e usa la propria sandbox. Il ciclo di vita della sandbox è gestito dall’executor dello step.
• Persona - Gli step di workflow fanno riferimento alle persona per la loro configurazione di agente. Modificare una persona aggiorna tutti i workflow che la usano.
• Issue - Le sessioni di issue possono scoprire problemi che vengono eseguiti come workflow run sequenziali tramite le work chain.
• Sprint Chain - Un’esecuzione batch che lancia lo stesso workflow più volte, con ogni sprint che produce la propria PR.
• Recurring Task - Un’automazione pianificata che avvia il workflow a una frequenza configurata senza intervento manuale.
• Learning - I learning vengono estratti dalle sandbox dei workflow run e reimmessi nei run futuri tramite versioni di learning compilate.
• Tracciamento dell’usage - Ogni workflow run genera record di usage per il tempo di compute E2B, il consumo di token IA e il costo complessivo.

Casi d’uso

• Cicli Design-Review - Un designer implementa modifiche e un checker le verifica con test E2E, iterando finché la qualità non passa.
• Raffinamento del prompt - Un agente prompter affina una descrizione di task vaga in un prompt dettagliato prima di passarla a un designer.
• Investigazione poi correzione - Un investigator analizza la codebase per comprendere la issue, poi un designer implementa la correzione basandosi sull’investigazione.
• Generazione di codice multi-agente - Agenti diversi gestiscono aspetti diversi (frontend, backend, testing) di una feature in sequenza.
• Consegna a qualità controllata - Uno step evaluator valuta l’implementazione rispetto alle soglie di qualità prima che la PR venga aperta, garantendo che solo modifiche pronte per la produzione siano sottoposte a revisione.
• Sviluppo batch a fasi - Le sprint chain lanciano lo stesso workflow attraverso più fasi di un progetto, con ogni sprint che consegna un insieme di modifiche discreto e revisionabile.
• Automazione continua - I task ricorrenti avviano workflow di qualità, sicurezza o dipendenze secondo un planning, mantenendo la codebase sana senza intervento manuale.