anhhung04/meilleures-pratiques-automatisation-tracecat

Meilleures pratiques d'automatisation Tracecat

Pour les automatisations orientées Slack, utilisez /skill:tracecat-slackbot-best-practices. Dans le Chat de l'espace de travail Tracecat, chargez d'abord /skill:tracecat-workspace-chat ; son mappage d'outils spécifique à l'hôte remplace les étapes MCP externes ci-dessous. Références à la demande : graph-shape, expressions, run-python, tables, trigger-inputs, case-triggers, secrets, agent-outputs, agent-presets, workflow-editing.

Workflow

Pour une connexion MCP externe à Tracecat, partez du contexte en direct plutôt que de deviner :

1. Découvrez l'espace de travail avec list_workspaces.
2. Lisez tracecat://platform/dsl-reference lorsque la syntaxe ou des exemples DSL sont nécessaires.
3. Utilisez get_workflow_authoring_context pour les schémas d'actions, les variables et les secrets.
4. Pour les workflows existants, utilisez get_workflow, puis des correctifs ciblés edit_workflow — voir workflow-editing. Avant d'ajouter ou de modifier un run_if, depends_on ou join_strategy, appelez get_workflow_graph là où l'hôte l'expose et lisez d'abord chaque action en amont et sa liste gated_by.
5. Validez avec validate_workflow, exécutez un brouillon ou une exécution publiée si approprié, puis inspectez les échecs avec list_workflow_executions et get_workflow_execution.

D'autres hôtes peuvent exposer une surface d'outils différente. Suivez leur adaptateur plutôt que de préfixer mécaniquement ces noms MCP nus.

Clarifiez les choix de production qui modifient le contrat du workflow : espace de travail, intégration/fournisseur, source de secret, comportement de publication/exécution, effets secondaires destructeurs, approbations ou critères d'acceptation. Si la demande est déjà suffisamment spécifique, procédez.

Forme du graphe

Esquissez la forme avant la création et gardez-la aussi proche d'une seule ligne que le travail le permet. Préférez le linéaire au parallèle, et le lisible au complètement connecté : moins d'arêtes est la mesure.

• depends_on est l'ordre d'exécution, pas le câblage des données. Une action peut lire ACTIONS.<ref>.result depuis n'importe quel ancêtre, pas seulement un parent direct — la validation vérifie que la référence existe dans le workflow, pas qu'elle soit un parent. Ajoutez une arête lorsque l'action doit attendre, jamais pour rendre une valeur accessible.
• Verrouillez une fois. Un run_if sur une action saute également chaque action en dessous sur la chaîne, donc ne le répétez jamais en aval. Une chaîne où chaque action porte la même garde TRIGGER.enabled && ... est erronée ; seule la première action en a besoin. Une action en aval obtient son propre run_if uniquement pour une nouvelle condition, écrite seule. L'exception est une jonction, et c'est un piège : une tâche avec plusieurs parents n'est pas forcée de sauter alors qu'un seul survit, mais la valeur par défaut join_strategy: all exige alors que chaque parent ait été visité, donc une branche sautée rend la jonction inaccessible et fait échouer le workflow. Utilisez join_strategy: any, ou répétez la condition de la branche sur la jonction afin qu'elle se saute d'abord elle-même.
• Par défaut, utilisez une seule chaîne. Ramifiez uniquement pour un travail véritablement indépendant qui vaut la peine d'être exécuté simultanément, et rejoignez uniquement lorsqu'une action ultérieure a besoin de résultats de plus d'une branche.
• Un parent est la norme. Plus d'un signifie une jonction délibérée — choisissez join_strategy à bon escient.
• Gardez chaque run_if court : une comparaison lisible pour la seule nouvelle condition. Une longue chaîne &&/|| restitue généralement des verrous en amont ou appartient à une transformation antérieure.
• Gardez les workflows ordinaires autour de 20 nœuds ou moins et les workflows agentiques autour de 6 nœuds ou moins. Préférez les flux lisibles de haut en bas ordonnés comme le processus se lit, et des références lisibles par l'humain. Tracecat MCP formate automatiquement le canevas lorsque les actions ou les arêtes changent, donc omettez layout plutôt que de placer les nœuds à la main.

Voir graph-shape pour une réécriture travaillée de la surconnexion, des stratégies de jonction, des arêtes d'erreur, et pourquoi la dispersion n'est pas une ramification.

Priorité des actions

Choisissez l'action la plus spécifique qui fait le travail :

1. Actions d'intégration (tools.<integration_slug>.*) pour le produit appelé. Recherchez list_actions avec une sous-chaîne courte du produit ou du nom d'action (par exemple query="okta"), ou parcourez un espace de noms connu tools.<integration_slug>, avant d'écrire un appel API. La recherche correspond à des sous-chaînes littérales, pas à des mots-clés séparés. Suivez next_cursor tant que has_more est vrai lorsque la première page manque d'action appropriée. Inspectez les candidats avec get_action_context et comparez leurs identifiants et arguments requis.
2. Actions de base : core.http_request / core.http_paginate pour les produits ou points de terminaison avec aucune action d'intégration, core.transform.* pour le formatage, et core.table.* / core.cases.* pour les données de plateforme.
3. core.script.run_python uniquement pour une étape autonome qu'aucune action ne couvre. N'appelez jamais une API depuis Python lorsqu'une action d'intégration ou HTTP peut effectuer l'appel.

N'inventez jamais de noms tools.*. Si une requête générique correspond à plusieurs intégrations, montrez les candidats en premier.

Choisir entre un agent et Python

Décidez en fonction du type de travail, et optimisez l'ensemble du workflow pour la maintenabilité et la lisibilité — le moins d'actions et le moins de code qui fait le travail.

• Travail agentique → utilisez un agent (ai.agent / ai.preset_agent). Tout ce qui nécessite du jugement, de l'investigation, du routage, des choix d'enrichissement, une synthèse, la composition d'un message ou la publication sur Slack. Accordez les outils sur la liste d'autorisation actions du preset ou sur les metadata.tools d'un skill, puis faites confiance à l'agent. Préférez les agents, les invites et les skills — ils portent la pensée créative avec beaucoup moins de pièces mobiles qu'un graphe de nœuds déterministes.
• Plomberie de données déterministe → utilisez Python (core.script.run_python). Transformation, normalisation, rédaction, jointure et traitement par lots des lignes dans les tables. C'est exactement ce à quoi Python sert — ce n'est pas une odeur. Une seule action run_python claire bat la dispersion du même travail sur plusieurs nœuds. Les appels API ne sont pas de la plomberie de données : ils vont dans les actions d'intégration ou core.http_* (voir Priorité des actions).

L'odeur est d'utiliser Python pour la partie agentique — par exemple composer ou envoyer un message Slack d'agent à partir d'un script au lieu de donner à l'agent l'outil Slack.

Garde-fou de taille d'invite : repoussez le comportement dans l'invite jusqu'à une taille raisonnable. Quand une seule invite devient trop grande pour rester lisible, décomposez-la en sous-agents ou en un skill plutôt que de gonfler une méga-invite.

Automatisation axée sur l'agent

Lorsque l'utilisateur demande un workflow agentique, un preset d'agent, ou dit d'utiliser des agents, faites de l'agent le propriétaire principal du travail. Donnez-lui les outils dont il a besoin et faites-lui confiance pour investiguer, décider, router, composer des messages et agir. Par défaut, adoptez une forme mince : trigger -> remise en forme/rédaction -> mise à jour d'enregistrement d'événement -> ai.agent (ou ai.preset_agent).

Persistez l'événement normalisé avant que l'agent ne s'exécute. Lorsque les événements proviennent d'un SIEM, d'une plateforme de logs, d'un flux webhook SaaS, d'une piste d'audit ou d'un service cloud, stockez d'abord la charge utile normalisée et l'état de révision dans une table Tracecat, avec une mise à jour déterministe. Cela donne des nouvelles tentatives, des webhooks en double et une relecture d'une source de vérité durable. Pointez l'agent vers la ligne sauvegardée, afin que le workflow — pas l'agent — soit propriétaire du premier enregistrement durable de l'événement.

Un nœud déterministe mérite sa place en étant mince, direct et facile à auditer, et en faisant le travail que l'agent ne devrait pas posséder : rédiger les secrets avant que l'agent ne voie les données, normaliser le schéma, mettre à jour la ligne d'événement, protéger les exécutions coûteuses de l'agent avec une vérification de déduplication, préparer des lots bornés, ou checkpoint l'état durable. Gardez le jugement, le routage, l'enrichissement, la composition de message, les décisions d'approbation douce et le comportement de notification finale dans l'agent. Lorsqu'une question d'approbation elle-même nécessite du jugement, laissez l'agent décider ou rédiger la demande.

Deux mécanismes différents couvrent le risque, et ils ne concurrencent pas les outils appartenant au preset. Utilisez une porte déterministe pour un effet externe irréversible que le workflow lui-même effectue — le graphe décide si ce nœud s'exécute ou non. Utilisez tool_approvals par outil sur le preset pour un outil risqué que l'agent détient : l'agent conserve l'outil, et l'exécution fait une pause pour un humain avant que cet appel spécifique ne soit effectué.

Favorisez un agent bien instruit ou un preset réutilisable plutôt que plusieurs petits nœuds déterministes. Les outils d'un agent vivent normalement sur la liste d'autorisation actions du preset, ou sur les metadata.tools d'un skill attaché lorsque plusieurs agents partagent le groupe. Ainsi, l'agent a les mêmes outils dans Workspace Chat et dans chaque workflow qui l'appelle. Les instructions portent le comportement plutôt que les permissions : les contrats de sortie, le style Slack, les règles de déduplication, les limites de locataire et les effets secondaires autorisés vont dans les instructions du preset, que l'agent lit au lieu des fichiers du dépôt. Lorsque l'agent a besoin d'un outil, accorder l'outil étroit y surpasse généralement le wrapper du même appel dans une action de workflow.

Un nœud ai.preset_agent porte généralement juste preset et user_prompt, plus un instructions facultatif pour le contexte spécifique à l'exécution. Son argument actions remplace les outils de registre du preset et de ses skills pour cette exécution plutôt que de s'y ajouter — les outils MCP restent attachés, et une liste vide est ignorée — il convient donc pour essayer un preset avec un ensemble d'outils différent dans un test ou une évaluation. Une liste laissée là dans un workflow de livraison supprime également les outils de registre que les skills du preset contribuent, ce qui est rarement ce que l'auteur souhaitait.

Rédigez les instructions de l'agent comme des objectifs, un contexte et des raisons plutôt que des interdictions. Une règle générale peut annuler un outil donné à l'agent : un appelant a ajouté "Utilisez uniquement les preuves fournies" et l'agent a ignoré la seule recherche de politique pour laquelle il avait reçu un outil. Réservez les règles strictes pour les actions irréversibles ou tournées vers l'extérieur, et placez tool_approvals ou une porte déterministe derrière elles au lieu de compter sur le libellé d'une invite.

L'exécution d'un preset a plus de capacités que list_actions ne le montre : un véritable shell et des outils de fichiers, Python, curl, jq et DuckDB. Inspectez le contexte du preset/exécution avant d'ajouter un assistant de workflow pour compenser une limitation présumée — voir agent-presets.

Valeurs par défaut de création

• Pour les workflows agentiques, repoussez la plupart du comportement dans l'invite/preset de l'agent. Pour les workflows pilotés par événements, une seule action de remise en forme/rédaction/mise à jour avant l'agent est généralement la bonne limite déterministe.
• Utilisez ai.agent / ai.preset_agent pour le travail agentique ; l'action tools.* du produit (ou core.http_request quand aucune n'existe) pour les appels API déterministes ; core.script.run_python pour le travail de données déterministe, après avoir exclu une expression en ligne, run_if ou une action core.transform.* — voir expressions et run-python.
• Pour les écritures en masse dans les tables, préférez une action native core.table.insert_rows lorsque les lignes sont déjà formatées (jusqu'à 1000 lignes par lot). Si le formatage, le morcellement ou des écritures mixtes table/cas sont nécessaires, utilisez core.script.run_python avec des assistants importés et des lots bornés plutôt que de disperser plusieurs actions basées sur la base de données.
• Ne donnez pas core.http_request à un agent à moins que l'utilisateur n'accepte explicitement la large capacité réseau. Mettez HTTP déterministe dans le graphe du workflow ou un sous-flux étroitement cadré.
• Divisez en sous-flux uniquement lorsqu'il y a une véritable frontière d'orchestration, un workflow enfant réutilisable, un historique d'exécution séparé, des approbations, des actions de longue durée ou un point de contrôle indépendant. Utilisez core.workflow.execute et préférez workflow_alias aux ID codés en dur. Valeurs par défaut du sous-flux en masse : loop_strategy: batch, batch_size: 32, fail_strategy: isolated, wait_strategy: wait (utilisez detach uniquement lorsque le parent n'a pas besoin des résultats de l'enfant).
• Gardez les sorties de run-python et d'agent petites : lignes en aval, comptes rendus récapitulatifs, échantillons d'erreur bornés.
• Préférez un preset d'agent réutilisable à un ai.agent en ligne, et l'objet model aux model_name/model_provider obsolètes au niveau supérieur — voir agent-presets.

Erreurs courantes

• Utiliser Python pour la partie agentique — composer ou publier un message Slack d'un agent, ou effectuer des appels de routage/jugement dans un script. L'agent est propriétaire de la composition des messages, de la publication (via un outil Slack) et du jugement ; Python possède la plomberie de données déterministe.
• Surconnecter le graphe : une arête de chaque producteur à chaque consommateur. Lisez à partir des ancêtres et conservez une seule chaîne (voir graph-shape).
• Répéter un run_if le long d'une chaîne, en reformulant une condition qu'un ancêtre a déjà appliquée. Le saut se propage tout seul — verrouillez une fois en haut, et donnez une action en aval un run_if uniquement pour une nouvelle condition qu'elle introduit elle-même (voir graph-shape).
• Les noms d'actions de workflow ne sont pas des noms d'outils MCP. Utilisez des outils MCP tels que create_workflow pour gérer les workflows, et des noms d'actions tels que core.http_request uniquement dans le YAML du workflow.
• Inventer des noms d'actions tools.*. Découvrez les actions avec list_actions, puis inspectez les schémas exacts avec get_action_context.
• Appeler l'API d'un produit depuis core.script.run_python (requests, httpx) ou un core.http_request nu alors qu'une action tools.* appropriée existe. Recherchez et parcourez d'abord list_actions pour le produit.
• Utiliser for_each pour la gestion de boucle ordinaire, ou utiliser scatter/gather pour le traitement par lots de données lourdes, le filtrage, les jointures ou les écritures dans des tables. Par défaut, scatter pour les boucles au niveau du workflow ; ajoutez gather uniquement lorsque les étapes en aval ont besoin de résultats combinés, et omettez-le autrement. Soyez particulièrement prudent avec plus de 10 actions de table/cas dispersées et basées sur la base de données, qui peuvent épuiser les connexions Postgres. L'intervalle facultatif de scatter peut espacer le travail, mais il ne regroupe pas les écritures en base de données ; utilisez une seule core.table.insert_rows ou core.script.run_python pour les écritures en masse. Voir scatter et tables.
• Utiliser Python pour intégrer des données brutes d'un fichier, d'une notification de cas, d'une charge utile webhook ou d'une sortie d'outil dans une table sans d'abord inspecter la structure de la table et (si transmogrifiée) la vue du cas. Utilisez column pour les tables issues de list_tables et list_table_columns, lisez les métadonnées de champ de cas dans la définition du cas, puis écrivez du Python qui correspond. Voir tables, cases-and-triggers.

Ne pas faire qui fait mal

Ces règles ont une portée plus large que les choix de création ordinaires. Les enfreindre casse le workflow pour d'autres utilisateurs, d'autres outils de création ou le moteur lui-même :

• Ne traitez pas get_workflow comme la source pour les entrées d'action. Le get_objectives du workflow (lorsqu'il est exposé) guide la modification ; l'arborescence actions de get_workflow manque de détails. Utilisez get_action_context pour le schéma complet d'une action.
• Ne traitez pas core.workflow.execute comme core.script.run_python. Un sous-flux de workflow est une orchestration séparée, pas un module de code. Partagez la logique via un preset d'agent ou un skill, pas via un sous-flux.
• Ne créez pas de boucles dans le graphe. Le moteur de workflow Tracecat ne supporte pas les cycles ; toute tentative de boucler en arrière vers un nœud déjà connecté provoquera une erreur ou un comportement indéfini. Utilisez scatter/gather, for_each, ou un re-déclenchement par core.trigger.send_event en tant que boucle intentionnelle.
• Ne codez pas en dur les versions de package dans run_python. Utilisez REQUESTS_VERSION ou des variables d'environnement nommées similaires disponibles globalement ; si la variable n'existe pas, omettez la contrainte de version. Mettez les versions verrouillées dans les dépendances du projet, pas dans les définitions de nœud de workflow.
• Ne présumez pas du comportement des écrasements d'actions. L'argument actions sur un nœud ai.preset_agent remplace les outils du preset — lire Presets d'agent la section sur l'écrasement des actions.
• Ne sautez pas l'étape de découverte. Appelez list_workspaces, list_tables, list_actions, et get_action_context avant de construire le workflow. Payer le coût de quelques appels de listing MCP en vaut la peine par rapport à l'écriture d'un YAML qui fait référence à des entités inexistantes.

Utilisation des références

Lorsque vous demandez un paramètre, la conception d'une table, une importation, une syntaxe DSL, ou tout ce qui semble inconnu, lisez le module d'aide du dépôt référencé ci-dessous. Ne devinez pas la syntaxe.

Référence	Quand l'utiliser
graph-shape	Connexions du graphe, join_strategy, run_if, propagation de saut, arêtes d'erreur, disperser/rassembler
expressions	Expressions FS {{ }}, fonctions de modèle, Trigger, ACTIONS, ACTIONS.STEPS, run_if, filtrage
run-python	import tracecat helpers, session, context, Env, limites de bibliothèque, variables d'environnement
tables	Schémas de table, colonnes, index, insert_rows, update_rows, lecture, écritures en masse
trigger-inputs	Webhooks, entrées manuelles d'exécution, core.trigger.send_event, payloads Declarative, arg, headers, body
cases-and-triggers	Workflows de cas, déclencheurs de cas, champs de cas, schémas, suppressions
secrets	Types de secret, get_secret, OAuth, partage entre actions
agent-outputs	Sorties structurées d'agent, schémas, limiteurs, guides de format
agent-presets	Création de preset, instructions, modèles, actions, skills, variables, runtime, slots
workflow-editing	edit_workflow payloads, correctifs ciblés, modifications de entry_point, changements de layout

---

Ce skill fournit les directives pour créer des workflows Tracecat maintenables et lisibles. Pour les automatisations orientées Slack, utilisez /skill:tracecat-slackbot-best-practices. Pour l'assistance au chat de l'espace de travail, chargez d'abord /skill:tracecat-workspace-chat. Consultez les fichiers de référence liés ci-dessus pour des détails supplémentaires sur chaque sujet.