Costruire workflow

Costruire un workflow in CodeCourier significa definire un blueprint riutilizzabile che orchestra agenti IA in una pipeline multi-step. Questa guida percorre il processo di creazione del workflow, dalla scelta delle persona alla configurazione dei loop e delle impostazioni di sandbox.

Creare un nuovo workflow

Naviga alla pagina Workflows nel dashboard del tuo progetto e clicca il pulsante « New Workflow ». La finestra di dialogo di creazione del workflow ti guida attraverso la configurazione.

Architettura della pipeline

Ordinamento degli step

Gli step vengono eseguiti nell’ordine in cui appaiono nell’array personaPipelineSteps. L’orchestratore di workflow li elabora in sequenza - lo step 2 non parte finché lo step 1 non si completa. Questo garantisce che ogni step possa basarsi sul lavoro degli step precedenti.

Iteration Block (gruppi di loop)

Un Iteration Block è il modo per inserire un gruppo di step in un’esecuzione ripetuta. Gli step consecutivi che condividono lo stesso loopId formano un block, e il block si ripete finché il checker del block non restituisce un verdetto positivo o il loopMaxIterations del block non viene raggiunto. Gli step senza loopId vengono eseguiti una volta, in ordine. Il pattern di iterazione tipico è:

// Example: persona pipeline steps with a loop
personaPipelineSteps: [
  {
    personaId: prompterPersonaId,
    // No loopId -- runs once
  },
  {
    personaId: designerPersonaId,
    loopId: "design-review",
    loopMaxIterations: 3,
  },
  {
    personaId: checkerPersonaId,
    loopId: "design-review",
    loopMaxIterations: 3,
  },
  {
    personaId: optimizerPersonaId,
    // No loopId -- runs once after the loop
  },
]

In questo esempio, il prompter viene eseguito per primo (una volta), poi il designer e il checker iterano fino a 3 volte, e infine l’optimizer viene eseguito una volta dopo l’uscita dal loop.

Execution Block

L’orchestratore analizza l’array piatto di step in execution block:

• Single block - Step senza loopId. Vengono eseguiti una volta in ordine.
• Loop block - Gruppi di step con lo stesso loopId. Si ripetono come gruppo finché il checker non passa o il numero massimo di iterazioni non viene raggiunto.

Se nessuno step porta un loopId, la pipeline viene eseguita linearmente - ogni step viene eseguito esattamente una volta. Un checker senza Iteration Block produce comunque un verdetto sul suo run step, ma non innesca un retry automatico. Per abilitare il retry in caso di fallimento, avvolgi gli step rilevanti in un Iteration Block.

Modificare i workflow

I workflow esistenti possono essere modificati dalla pagina di dettaglio del workflow. Puoi cambiare:

• Nome e descrizione.
• Ordine e composizione degli step di persona.
• Loop ID e numero massimo di iterazioni.
• Configurazione di sandbox predefinita.

Le modifiche si applicano solo ai run futuri. I run già in corso proseguono con la configurazione con cui sono stati avviati. Il timestampupdatedAt del record del workflow traccia quando è stata fatta l’ultima modifica.

Duplicare i workflow

Puoi duplicare un workflow esistente per creare una variante. Il duplicato eredita tutta la configurazione dell’originale (nome, step, config di sandbox) con « (copy) » aggiunto al nome. Questo è utile per creare varianti di test A/B - ad esempio, la stessa pipeline con modelli o numeri di iterazioni diversi.

Tipi di workflow

Il campo type del workflow definisce il suo pattern di esecuzione. I nuovi workflow usano persona_pipeline, ma CodeCourier supporta diversi tipi per la retrocompatibilità:

• persona_pipeline - Il valore predefinito attuale. Gli step sono definiti da riferimenti a persona con gruppi di loop opzionali. È il tipo più flessibile.
• custom_pipeline - Gli step sono definiti inline con tipo, CLI, modello e istruzioni. Ogni step è un oggetto di configurazione grezzo anziché un riferimento a persona.
• designer_checker - Un pattern semplificato a due step: il designer viene eseguito, poi il checker produce un verdetto. Usa le defaultCheckerInstructions del workflow. La coppia viene eseguita una volta - per abilitare il retry in caso di fallimento, usa una pipeline di persona e avvolgi i due step in un Iteration Block.
• single_designer - Un singolo step che esegue il designer una volta senza loop di checker.

Best practice

• Inizia semplice - Comincia con un workflow designer-checker a due step prima di aggiungere altri step. Le pipeline complesse sono più difficili da debuggare.
• Usa modelli appropriati - Usa Opus per il lavoro di progettazione che richiede un ragionamento profondo e Sonnet o Haiku per gli step checker che eseguono la verifica. Gli step evaluator in genere si comportano bene su Sonnet dati i loro requisiti di output strutturato.
• Imposta limiti di iterazione ragionevoli - All’interno di un Iteration Block, 3 iterazioni sono un buon valore predefinito. Più di 5 raramente migliora i risultati e aumenta significativamente il costo.
• Scrivi istruzioni di persona chiare - La qualità dell’output del workflow dipende fortemente dalle istruzioni di ogni persona. Sii specifico su cosa ogni step deve fare e cosa costituisce successo.
• Controlla le PR con gli evaluator - Aggiungi un evaluator come ultimo step prima della creazione della PR per imporre una soglia di qualità. Inizia con una soglia di 70 e regolala verso l’alto man mano che la tua pipeline matura.
• Testa prima con task piccoli - Esegui il tuo workflow su un task piccolo e ben definito prima di usarlo per feature grandi. Questo ti aiuta a regolare la pipeline senza sprecare risorse.