# Bonnes pratiques

Une liste focalisée de recommandations issues de workflows réels en production sur Systalink Agent Builder. Peu de théorie, beaucoup de ce qui vous fait gagner du temps, de l'argent et des nuits.

## Commencez petit, itérez

Construisez d'abord la version utile la plus petite — un seul nœud Agent qui prend un input et renvoie du texte. Exécutez-le. Lisez la sortie. Ensuite seulement, ajoutez le nœud suivant.

Piège classique : commencer avec cinq branches, deux boucles et un nœud RAG. Vous ne saurez pas lequel est cassé quand la sortie sera fausse.

- Déposez un nœud, câblez entrée → sortie, lancez.
- Ajoutez le suivant, relancez.
- Sauvegardez après chaque run vert — le versioning se déclenche automatiquement.

## Testez avec le chat de prévisualisation avant de publier

Chaque éditeur de workflow embarque un panneau de chat à droite. Utilisez-le. Il alimente votre workflow avec un vrai `input`, exécute le graphe complet et affiche la dernière sortie exactement comme une surface publiée le ferait.

- Moins coûteux qu'un redéploiement via l'API.
- Stream les appels d'outils — vous voyez *quel* outil a tourné et *ce* qu'il a renvoyé.
- Aucun credential, rate limit ou jeton de partage requis.

Si ça ne marche pas en preview, ça ne marchera pas en prod.

## Préférez la sortie structurée pour chaîner des Agents

Quand un Agent alimente un autre nœud (autre Agent, Transform, If/Else), réglez son **type de sortie** sur `JSON schema` et déclarez les champs que vous consommez réellement en aval.

```json
{
  "type": "object",
  "properties": {
    "intent":     { "type": "string", "enum": ["refund", "shipping", "other"] },
    "urgency":    { "type": "integer", "minimum": 1, "maximum": 5 },
    "customer_id": { "type": "string" }
  },
  "required": ["intent", "urgency"]
}
```

Pourquoi : du texte libre en aval, ça veut dire parsing fragile, "le modèle a oublié les accolades aujourd'hui", et échecs silencieux. Un schéma est validé côté serveur — le run échoue clairement si le modèle dérape.

Deuxième bénéfice : le schéma alimente l'assistance de l'éditeur. Classify pré-sélectionne le champ et pré-remplit ses catégories depuis l'enum, If/Else suggère des opérateurs typés et des expressions `champ == 'valeur'` prêtes à l'emploi, et l'autocomplétion `{` propose les chemins `{outputs.<id>.parsed.<champ>}` dans chaque champ templaté.

## Laissez l'autocomplétion écrire vos placeholders

Ne tapez pas les chemins de template de mémoire. Dans tout champ templaté (prompts, URLs, corps, champs d'email…), **tapez `{`** et choisissez dans la liste — elle ne propose que les variables qui existent réellement en amont du nœud, donc les typos comme `{outputs.agent1.parsed.emial}` n'arrivent jamais. L'**icône `{}`** du panneau de config affiche la référence complète « données disponibles en entrée » avec des chemins copiables.

Chaque nœud expose aussi une sortie structurée — `{outputs.<id>.parsed.url}` pour Generate file, `.parsed.safe` pour Guardrails, `.parsed.branch` pour If/Else, etc. Voir le tableau par nœud dans [Concepts](#/docs/concepts).

## Lancez Workflow Doctor avant les grosses modifications

Avant de refactorer un ancien workflow, lancez **Workflow Doctor** depuis l'éditeur. Il vérifie la compatibilité sans modifier le graphe, y compris les types de nœuds marqués deprecated dans le node registry.

- Les nœuds deprecated sont signalés comme avertissements de compatibilité.
- Quand un remplacement est connu, Workflow Doctor propose une action de migration.
- Pour les nouveaux changements, utilisez le remplacement au lieu d'ajouter un autre nœud deprecated.

## Gardez les prompts système ciblés : 1 rôle, 1 tâche

Un prompt système de 4 paragraphes qui demande à un Agent de "classifier, résumer, traduire et appeler le bon outil" fera les quatre mal. Découpez-le en un nœud Classify suivi d'Agents spécialisés.

Règle : si vous ne pouvez pas décrire le job de l'agent en une phrase, il en fait trop.

## Validez les triggers avec "Fetch real event"

Chaque trigger (Webhook, Schedule, Gmail, Notion) a un bouton **Fetch real event**. Cliquez avant de publier. Il récupère un payload réel récent — vrais headers, vrai JSON, vrais noms de champs — et l'épingle comme fixture de test de l'éditeur.

Ça attrape le bug classique *"j'ai templaté `{event.body.email}` mais le champ est en fait `{event.body.from.email}`"* en 5 secondes au lieu de 50 minutes de debug en prod.

## Utilisez le credential store — ne collez jamais de secrets dans des placeholders

Le credential store chiffre les secrets au repos et ne les déchiffre qu'à l'exécution, pendant le run. Coller une clé API en clair dans un champ de nœud, c'est laisser le secret dans le JSON du workflow, l'historique des versions, la fiche marketplace et tous les logs qui dumpent la config.

- Créez le credential une fois → référencez-le par nom dans chaque nœud.
- Rotation en un seul endroit.
- Les fiches marketplace n'embarquent jamais le secret.

## Sandbox obligatoire pour les outils risqués

Les outils **Shell** et **Code Interpreter** exécutent du code généré par le modèle (un LLM, pour ce besoin, n'est pas de confiance). Ils tournent toujours dans une sandbox isolée garantie par la plateforme — vous n'avez rien à configurer.

- Chaque exécution est isolée : aucun accès au filesystem hôte, environnement éphémère.
- La sortie réseau est restreinte par défaut — gardez-la ainsi sauf si une étape a réellement besoin d'un host précis.
- Ne collez jamais de secret dans une étape Shell/Code — référencez plutôt un credential.

## Posez des timeouts et un max d'itérations sur les While

Un nœud While sans condition de sortie est un incident de facturation. Toujours définir :

- **Max iterations** (`maxIterations`) — plafond dur, même si la condition reste vraie.
- **Timeout par itération** — arrête le corps si une passe pend.
- Une condition de sortie explicite et lisible par le modèle (ne vous reposez pas sur "l'agent saura quand s'arrêter").

Idem au niveau workflow — définissez **Execution timeout** dans l'espace Production de l'agent → **Settings**. Un run qui dépasse échoue clairement au lieu de brûler des crédits en silence.

## Versionnez votre workflow — et utilisez l'historique

Chaque sauvegarde crée une version. Vous n'avez rien à faire. Ce que vous *devriez* faire :

- **Labelisez** les versions importantes ("avant refacto", "prod 2026-05", "démo acme").
- **Prévisualisez** le JSON d'une ancienne version avant de la restaurer — confirme que c'est bien celle dont vous vous souvenez.
- **Restore** crée une nouvelle version avec l'ancien graphe ; la version actuelle n'est jamais perdue.

Traitez-le comme git : sauvegardes petites et fréquentes avec labels clairs > une grosse sauvegarde par jour.

## Réutilisez depuis la marketplace

Avant de partir de zéro, cherchez dans la marketplace. Les patterns courants — RAG sur docs, qualification de lead, digest quotidien, CSV → email — y sont déjà. Install crée une copie modifiable dans votre compte. Vous recâblez les credentials, ajustez les prompts, livrez.

Si vous construisez quelque chose d'utile, republiez-le. Seul le graphe part — les credentials et la config de déploiement restent privés.

---

*Source: https://agentbuilder.systalink.sn/docs/best-practices — human documentation.*
*Other language: [/docs-md/en/best-practices.md](/docs-md/en/best-practices.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*