# Concepts

Le vocabulaire que vous verrez dans l'éditeur, l'API et les logs.

## Workflow

Un workflow est un graphe orienté de nœuds qui s'exécute d'un trigger vers un ou plusieurs états finaux. Chaque workflow appartient à un seul tenant et est versionné — chaque sauvegarde crée une nouvelle révision sur laquelle les runs peuvent se fixer.

```text
Workflow: customer-support
  Webhook ─▶ Classify ─▶ Agent ─▶ Respond
```

## Node

Un node est une étape. Catégories : **Core** (Agent, Classify, End, Note), **Triggers & HTTP** (Webhook, HTTP Request, Schedule, Event listener, Respond), **Logic** (If/else, While, User approval), **Data** (Transform, Set state, Generate file, RAG), et **Tools** (Guardrails, MCP). Chaque nœud a son propre schéma de config dans le panneau de droite.

## Edge

Une edge connecte la sortie d'un nœud à l'entrée d'un autre. Certains nœuds (Classify, If/else) ont **plusieurs sorties labellisées** — le handle source de l'edge choisit la branche.

```text
Classify ──(intent=remboursement)──▶ AgentRemb
         ──(intent=autre)──────────▶ AgentFallback
```

## Trigger

Un trigger est le nœud qui démarre un run. Quatre types :

| Trigger | Démarre sur |
|---------|-------------|
| Manuel / Start | Bouton "Run" de l'éditeur ou chat preview |
| Webhook | Requête HTTP entrante |
| Schedule | Expression cron ou intervalle |
| Event listener | Le poller trouve un nouvel événement sur une source externe |

## Règles de validation

Chaque sauvegarde lance des contrôles structurels. Un **blocage** renvoie `400` et le workflow n'est pas sauvé ; un **avertissement** est informatif et la sauvegarde passe quand même.

| Règle | Sévérité | Pourquoi |
|-------|----------|----------|
| Exactement **un nœud trigger** (Webhook / Schedule / Event listener) | Blocage | Un run a un seul point d'entrée |
| Ne pas mélanger un nœud trigger et un nœud **Start** | Blocage | Choisissez un point d'entrée — un trigger publié *ou* un Start manuel/API |
| Un **Webhook** doit être authentifié (`authType` ≠ `none`) et avoir un path | Blocage | Les endpoints publics non authentifiés sont refusés |
| Au plus **un nœud Respond**, et seulement avec un trigger Webhook ou une entrée Start | Blocage | Un nœud Respond a besoin d'un appelant HTTP — voir [Respond to webhook](#/node-respond-webhook) |
| **Nœud orphelin** — un nœud sans connexion entrante qui n'est pas l'entrée | Avertissement | Étape probablement isolée ; elle ne s'exécute jamais |

Les nouveaux workflows sont créés en **Draft**. Passer en **Live** lance un contrôle d'activation supplémentaire — voir [Dépannage → Impossible d'activer](#/troubleshooting).

## Run (exécution)

Un run est une exécution d'un workflow. Le runtime enregistre input, output, durée et erreur de chaque nœud. Visible dans le panneau **Runs** et interrogeable via API. Les runs échoués peuvent être rejoués depuis le nœud en erreur.

```json
{
  "run_id": "run_01HX...",
  "status": "succeeded",
  "duration_ms": 1842,
  "nodes": [
    { "id": "agent_1", "status": "ok", "tokens_in": 312, "tokens_out": 87 }
  ]
}
```

## Credential

Un credential est un secret nommé et chiffré, stocké chiffré au repos dans le credential store de votre workspace. Les nœuds référencent les credentials **par nom** — la valeur est déchiffrée à l'exécution et n'est jamais transmise au LLM. Voir [Credentials](#/credentials).

## Agent

Un agent est un nœud Core qui appelle un LLM avec un system prompt, des tools optionnels et un output mode. Il reçoit l'input des nœuds amont (ou du chat), raisonne, appelle éventuellement des tools, et émet un résultat.

```yaml
agent:
  name: Triage
  model: gpt-4.1-mini
  system_prompt: "Classe le message de l'utilisateur et appelle route_ticket."
  tools: [function:route_ticket, web_search]
  output_mode: structured
```

## Tool

Un tool est quelque chose qu'un agent peut appeler en cours de raisonnement. Tools intégrés : `function` (code custom ou HTTP), `web_search`, `code_interpreter`, `file_search`, `image_generation`, `shell`, `mcp`. Les tools ont des schémas que le LLM utilise pour savoir quand et comment les appeler.

## Output mode

Chaque agent émet son résultat sous l'une de trois formes, choisie par nœud :

| Mode | Type de sortie | À utiliser quand |
|------|----------------|------------------|
| `text` | String simple | Réponses libres, résumés |
| `json` | Objet JSON parsé | Le LLM doit renvoyer des données structurées souples |
| `structured` | Schéma typé que vous définissez | Le nœud aval a besoin de champs stricts |

Les nœuds aval peuvent référencer les champs avec l'interpolation `{outputs.<node-id>.parsed.<champ>}` en mode `json` ou `structured`.

## Templates & placeholders

Partout où un nœud accepte une chaîne (prompts, URLs, corps HTTP, valeurs de set-state, corps de respond-webhook, templates de fichiers…), tu peux interpoler des valeurs du contexte de run via `{clé.chemin}`.

| Placeholder | Pointe vers |
|---|---|
| `{event.body}`, `{event.body.X}` | Payload du trigger qui a lancé le run (marche pour **webhook**, **schedule**, **event listener**) |
| `{event.headers.X}`, `{event.query.X}` | Webhook seulement : headers et query string entrants |
| `{webhook.body.X}` | Alias legacy de `{event.body.X}` — même valeur, plus explicite |
| `{input}` | Input initial du workflow (corps du trigger, ou ce que tu as envoyé à `/execute`) |
| `{last_output}` | Sortie du **nœud précédent uniquement** — écrasée à chaque étape |
| `{last_output.field}` | Un champ d'un `last_output` JSON |
| `{state.<clé>}` | Valeur écrite par un nœud **Set state**, avec namespace explicite (recommandé) |
| `{<clé>}` | Raccourci pour `{state.<clé>}` |
| `{outputs.<node-id>.raw}` | La sortie brute (texte) de n'importe quel nœud passé |
| `{outputs.<node-id>.parsed.<champ>}` | Un champ de la sortie structurée de n'importe quel nœud passé |

> Les placeholders résolvent une seule fois, au moment où le nœud s'exécute. Si un chemin n'existe pas, le `{chemin}` littéral est laissé intact — pratique pour repérer les clés mal orthographiées.

### Autocomplétion `{` et panneau de données

Pas besoin de mémoriser ces chemins. Dans tout champ templaté, **tapez `{`** et une liste d'autocomplétion propose chaque variable réellement disponible à ce point du graphe — champs du trigger, sorties des nœuds en amont (avec leurs champs de schéma quand l'agent amont sort du JSON), et clés d'état. Flèches + Entrée insèrent le `{chemin}`.

Le panneau de config a aussi une **icône `{}`** qui ouvre la référence **données disponibles en entrée** : les mêmes variables, groupées par source, avec un bouton copier sur chaque chemin.

### Sorties structurées par nœud

Chaque nœud enregistre à la fois `outputs.<id>.raw` (texte) et, quand il a de la structure, `outputs.<id>.parsed` :

| Nœud | `.parsed` contient |
|---|---|
| Agent (json / structured) | Les champs de votre schéma de sortie |
| HTTP Request | Le corps JSON parsé de la réponse — `{outputs.<id>.parsed.<champ>}` |
| Classify | `.classification` — le nom de la catégorie choisie |
| If/else | `.branch` (sortie prise), `.condition_met` (booléen) |
| Guardrails | `.safe` (booléen), `.reason` |
| RAG | `.answer`, `.sources` |
| File search | `.matches`, `.count` |
| Code execution | `.output`, `.exit_code`, détails du provider |
| Generate file | `.url`, `.filename`, `.format`, `.size_bytes` |
| Transform / MCP | JSON parsé quand la sortie est du texte JSON |

---

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