Meilleures pratiques

Cet article est un résumé des « fosses sur lesquelles on a marché ». Si vous avez écrit plus de 10 workflows, vous serez en mesure de sympathiser avec eux ; si vous ne les avez pas écrits, sauvegardez-les d'abord et revenez-y lorsque vous les rencontrez.

1. Comment rédiger un workflow pouvant être mis en production

Partir d'un modèle

Même si votre cas d'usage paraît très particulier, parmi les 240+ modèles il s'en trouve toujours un qu'il suffit de « démonter à moitié et modifier à moitié » pour l'exploiter. Partir d'un modèle évite de perdre beaucoup de temps à bâtir la structure à partir de zéro.

Instancier à partir d'un modèle C'est la première étape pour la plupart des utilisateurs.

Faites d'abord la "version stupide", puis la "version intelligente"

Première version du nouveau workflow :

• Valeurs par défaut codées en dur pour les variables
• N'ajoutez pas de condition, exécutez-les simplement.
• Utilisez la clé LLM unifiée de la plateforme, pas besoin de vous soucier du BYOK
• Ne suspendez pas cron, exécutez-le manuellement

Après avoir parcouru, nous « affinerons » un par un : variableisation, branchement, BYOK, cron et approbation. De cette façon, les problèmes peuvent être facilement localisés à chaque étape.

Effectuez un essai à chaque fois que vous effectuez une modification

Quelque chose changé → essai à sec pour voir la structure DAG et le débit variable → exécuter à nouveau. Le fonctionnement à sec ne coûte rien, ne sautez pas.

2. Sélection du type d'étape

La priorité va de haut en bas. Si vous rencontrez des difficultés pour choisir, choisissez celui qui est le mieux classé :

1. code — Si vous pouvez utiliser la logique déterministe, n'utilisez pas LLM. Rapide, bon marché, testable.
2. classifier — Utilisez-le lorsque LLM est requis mais que le résultat est une catégorie ; n'utilisez pas de single pour laisser l'agent jouer librement.
3. single — La plupart des tâches de type « résumer/extraire/réécrire ».
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — À utiliser lorsque la tâche nécessite que plusieurs points de vue débattent entre eux ; utilisez single lorsqu'un seul Agent peut la mener à bien de manière autonome.
6. agent_based — Les tâches ont de fortes caractéristiques de branchement, et chaque branche nécessite LLM pour déterminer où l'envoyer.
7. state_machine — Il existe des transitions d'état claires, telles que plusieurs cycles de cycle de vie d'interaction/ordre de travail.
8. manual_approval — Il doit être ajouté avant toute étape affectant les parties en ligne/dépensées/externes.

3. Variables et flux de données

Les grands champs sont d'abord extraits puis transmis

Lorsque l'étape en amont renvoie 100 Ko JSON, ne l'envoyez pas directement à la tâche en aval. Utilisez extract pour sélectionner les champs dont vous avez réellement besoin :

- id: fetch_data
  type: code
  code: |
    // 返回一个很大的 JSON
    return await heavyFetch();
  extract:
    user_count: $.data.stats.total_users
    top_3: $.data.items[:3].name

Utiliser | par défaut(...) pour le savoir

Lorsque vous faites référence à une variable qui peut être vide (la sortie d'une étape ignorée par condition), ajoutez la valeur par défaut :

- id: summarize
  type: single
  agent: writer
  condition: "length({{steps.classify.categories}} | default([])) > 0"
  task: "{{steps.classify.output | default('无内容可摘要')}}"

condition Branche contre on_failure

Ne mélangez pas :

• les contrôles de condition "ne peuvent pas franchir cette étape dans des circonstances normales" - skip = SKIPPED (non considéré comme un échec)
• on_failure est "une action compensatoire après une erreur" - envoyer une notification / rétrograder vers une autre source de données

Utilisez on_failure comme try-catch, mais pas comme branche normale. La logique métier normale utilise la condition.

4. Agent et modèle

tool_set Plus c'est petit, mieux c'est

Les outils fournis par le préréglage par défaut ne sont pas utilisés dans la plupart des étapes. Couper en 2-3 morceaux - le taux de réussite augmente et la consommation de jetons diminue.

Les modèles sont sélectionnés en fonction des tâches

• Raisonnement / Revue de code → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• Résumé / Catégorie → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• Écriture chinoise → Claude Sonnet / Kimi K2
• Contexte long (32K+) → Kimi K2 / Claude 200K

Température Sélectionner par tâche

• 0,0 – 0,3 – Raisonnement/Classification/Extraction (pour être stable)
• 0,4 – 0,7 – résumé/réécriture (équilibré)
• 0,7 – 0,9 – Écriture créative/brainstorming (être créatif)

5. continuation idempotente et automatique

Toutes les étapes du pipeline de données pures ajoutent idempotent : true - le service peut continuer à s'exécuter après le redémarrage. N'ajoutez pas d'étapes contenant des effets secondaires (envoyer des messages/passer des commandes).

Voir les détails Reprise automatique.

6. Fractionnement et modularisation

1. Un flux de travail comporte plus de 15 étapes : il doit être divisé.
2. La même logique en 3 à 5 étapes doit être utilisée dans un autre flux de travail : elle doit être transformée en module (sub_workflow).
3. Une fois le module publié, la suppression de l'entrée/la modification du type rompra la compatibilité et la version MAJEURE devra être mise à niveau.

7. Contrôle des coûts

• faire d'abord un essai à sec — Comme déjà indiqué, une exécution réelle inutile est ce qui gaspille le plus d'argent ; ce point est le plus économique.
• Classification à l'aide de modèles bon marché — Le classificateur 9 sur 10 ne nécessite pas Opus/GPT-5.
• Il existe une limite supérieure à la simultanéité — Pour le traitement par lots, utilisez sub_workflow + max_parallel pour contrôler la concurrence et ne laissez pas le TPM exploser.
• Cacher l'index RAG — Il est coûteux de réintégrer le même corpus à chaque fois et de conserver les résultats dans le produit.
• Lier l'alarme de budget — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. Sécurité et conformité

• N'écrivez jamais de clés dans YAML - utilisez Credential Center.
• La liste des informations d'identification de l'étape de code doit être explicite : ne donnez pas les informations d'identification de l'étape dont elle n'a pas besoin.
• Ajouter manual_approval avant paiement / communication externe / rédaction de la base de données clients.
• Envisagez d'ouvrir des workflows impliquant des données utilisateur approbateurListe des approbateurs que l’équipe de conformité doit saisir.
• Faites tourner régulièrement l'API Key utilisée pour le Webhook (ainsi que le signing secret en mode de compatibilité).

9. Processus de test et de lancement

1. Le nouveau flux de travail est d'abord exécuté à sec sur la page du flux de travail de test.
2. Exécutez le script d’étape de code séparément dans le nœud local/python pour voir le résultat.
3. Exécutez le comportement de l'agent à l'aide du débogueur de point d'arrêt + un petit échantillon 10 fois pour vérifier la stabilité.
4. Utilisez « Déclencher une fois immédiatement » pour vérifier le fuseau horaire/paramètre prédéfini avant que la planification ne soit mise en ligne.

10. Collaboration et versions

• Avant d'apporter des modifications importantes, "exportez YAML" et effectuez une sauvegarde locale - même si vous ne connaissez pas l'historique des versions, une copie locale est plus fiable.
• Édition à plusieurs personnes : une personne prend le verrou, enregistre les modifications, libère le verrou, puis la personne suivante le prend. Veuillez diviser le changement parallèle en sous-workflows.
• Synchronisez-vous avec l'équipe avant les changements de version majeurs - d'autres peuvent compter sur votre module.

11. Surveillance et alarme

• L'exécution du workflow clé est liée à la notification Slack/Feishu - s'il échoue, vous le saurez immédiatement.
• Vérifiez régulièrement le tableau de bord des données : quel flux de travail est le plus coûteux/le plus lent/échoue le plus souvent ? L'optimisation commence par cela.
• Vérifiez le journal d'audit une fois par mois - y a-t-il des exceptions aux autorisations/qui a utilisé les informations d'identification.

12. J'ai rempli une liste de contrôle du flux de travail

1. essai à sec réussi
2. Une course réussie
3. La stratégie idempotente/nouvelle tentative pour chaque étape est confirmée
4. Il existe des contrôles explicites d'approbation manuelle ou de condition avant les effets secondaires externes.
5. Toutes les informations d'identification sont analysées depuis Credential Center, il n'y a pas de clé en texte brut dans YAML
6. cron / webhook lié et confirmé "prochaine heure de déclenchement"
7. Configurer les notifications d'échec (au moins pousser l'exécution.failed vers Slack)
8. Exporter une copie de YAML vers git pour une sauvegarde hors site

Lectures complémentaires recommandées

• Référence de syntaxe YAML — Les champs flous ne peuvent pas être vérifiés avec précision
• Débogage des points d'arrêt — Un outil pour localiser les problèmes dans les processus complexes
• Dépannage — Comparaison de symptômes spécifiques