Construire des workflows

Construire un workflow dans CodeCourier signifie définir un blueprint réutilisable qui orchestre des agents IA dans un pipeline multi-étapes. Ce guide parcourt le processus de création de workflow, du choix des personas à la configuration des boucles et des réglages de sandbox.

Créer un nouveau workflow

Naviguez vers la page Workflows de votre dashboard de projet et cliquez sur le bouton « New Workflow ». La boîte de dialogue de création de workflow vous guide à travers la configuration.

Architecture du pipeline

Ordonnancement des étapes

Les étapes s’exécutent dans l’ordre où elles apparaissent dans le tableaupersonaPipelineSteps. L’orchestrateur de workflow les traite séquentiellement - l’étape 2 ne démarre pas tant que l’étape 1 n’est pas terminée. Cela garantit que chaque étape peut s’appuyer sur le travail des étapes précédentes.

Iteration Blocks (groupes de boucle)

Un Iteration Block est la manière d’inscrire un groupe d’étapes dans une exécution répétée. Les étapes consécutives partageant le même loopId forment un block, et le block se répète jusqu’à ce que le checker du block renvoie un verdict de passage ou que le loopMaxIterations du block soit atteint. Les étapes sans loopId s’exécutent une fois, dans l’ordre. Le pattern d’itération typique est :

// 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
  },
]

Dans cet exemple, le prompter s’exécute en premier (une fois), puis le designer et le checker bouclent jusqu’à 3 fois, et enfin l’optimizer s’exécute une fois après la sortie de la boucle.

Execution Blocks

L’orchestrateur parse le tableau d’étapes plat en execution blocks :

• Single blocks - Étapes sans loopId. Elles s’exécutent une fois dans l’ordre.
• Loop blocks - Groupes d’étapes avec le même loopId. Elles se répètent en groupe jusqu’à ce que le checker passe ou que le nombre maximum d’itérations soit atteint.

Si aucune étape ne porte de loopId, le pipeline s’exécute linéairement - chaque étape s’exécute exactement une fois. Un checker sans Iteration Block produit quand même un verdict sur son run step, mais ne déclenche pas de retry automatique. Pour activer le retry en cas d’échec, enveloppez les étapes concernées dans un Iteration Block.

Éditer des workflows

Les workflows existants peuvent être édités depuis la page de détail du workflow. Vous pouvez changer :

• Le nom et la description.
• L’ordre et la composition des étapes de persona.
• Les loop IDs et le nombre maximum d’itérations.
• La configuration de sandbox par défaut.

Les éditions s’appliquent uniquement aux runs futurs. Les runs déjà en cours continuent avec la configuration avec laquelle ils ont été démarrés. Le timestamp updatedAt de l’enregistrement du workflow suit le moment de la dernière édition.

Dupliquer des workflows

Vous pouvez dupliquer un workflow existant pour créer une variante. Le duplicata hérite de toute la configuration de l’original (nom, étapes, config de sandbox) avec « (copy) » ajouté au nom. C’est utile pour créer des variantes de test A/B - par exemple, le même pipeline avec des modèles ou des nombres d’itérations différents.

Types de workflow

Le champ type du workflow définit son pattern d’exécution. Les nouveaux workflows utilisent persona_pipeline, mais CodeCourier prend en charge plusieurs types pour la compatibilité descendante :

• persona_pipeline - La valeur par défaut actuelle. Les étapes sont définies par des références de persona avec des groupes de boucle optionnels. C’est le type le plus flexible.
• custom_pipeline - Les étapes sont définies inline avec type, CLI, modèle et instructions. Chaque étape est un objet de configuration brut plutôt qu’une référence de persona.
• designer_checker - Un pattern simplifié à deux étapes : le designer s’exécute, puis le checker produit un verdict. Utilise les defaultCheckerInstructions du workflow. La paire s’exécute une fois - pour activer le retry en cas d’échec, utilisez un pipeline de personas et enveloppez les deux étapes dans un Iteration Block.
• single_designer - Une seule étape qui exécute le designer une fois sans boucle de checker.

Bonnes pratiques

• Commencez simple - Débutez avec un workflow designer-checker à deux étapes avant d’ajouter plus d’étapes. Les pipelines complexes sont plus difficiles à déboguer.
• Utilisez des modèles appropriés - Utilisez Opus pour le travail de conception qui nécessite un raisonnement approfondi et Sonnet ou Haiku pour les étapes checker qui effectuent la vérification. Les étapes evaluator fonctionnent généralement bien sur Sonnet compte tenu de leurs exigences de sortie structurée.
• Définissez des limites d’itération raisonnables - À l’intérieur d’un Iteration Block, 3 itérations est une bonne valeur par défaut. Plus de 5 améliore rarement les résultats et augmente significativement le coût.
• Écrivez des instructions de persona claires - La qualité de la sortie du workflow dépend fortement des instructions de chaque persona. Soyez précis sur ce que chaque étape doit faire et ce qui constitue un succès.
• Contrôlez les PR avec des evaluators - Ajoutez un evaluator comme dernière étape avant la création de PR pour imposer un seuil de qualité. Commencez avec un seuil de 70 et ajustez à la hausse à mesure que votre pipeline mûrit.
• Testez d’abord avec de petites tâches - Exécutez votre workflow sur une petite tâche bien définie avant de l’utiliser pour de grandes fonctionnalités. Cela vous aide à ajuster le pipeline sans gaspiller de ressources.