# Merge

Le nœud **Merge** réunit les sorties de plusieurs branches entrantes. C'est un nœud de convergence : le moteur attend les branches amont disponibles, puis produit une valeur unique selon le mode sélectionné.

## Quand l'utiliser

- réunir des branches parallèles avant de poursuivre le workflow ;
- concaténer les listes renvoyées par plusieurs nœuds ;
- construire un objet à partir de résultats complémentaires ;
- attendre plusieurs branches tout en ne transmettant que la sortie de l'une d'elles.

Connectez chaque branche directement au nœud Merge. Il lit en priorité la sortie parsée de chaque nœud source ; si elle n'existe pas, il tente de décoder la sortie brute comme du JSON.

## Configuration

| Champ | Obligatoire | Description |
| --- | --- | --- |
| **Label** | Non | Nom affiché dans l'éditeur. Il n'a aucun effet sur l'exécution. |
| **Mode** | Oui | Détermine la forme du résultat fusionné. La valeur par défaut est **Collect inputs**. |
| **Source node ID** | Mode pass-through uniquement | Identifiant technique de la source à transmettre. Il s'agit de l'ID du nœud, et non de son label. |

## Modes

### Collect inputs — collecter les entrées

Conserve l'origine de chaque valeur. Le résultat est une liste d'objets `node_id` / `value`.

Entrées provenant de `customer` et `score` :

```json
{"id": 42, "email": "ada@example.com"}
85
```

Résultat :

```json
[
  {"node_id": "customer", "value": {"id": 42, "email": "ada@example.com"}},
  {"node_id": "score", "value": 85}
]
```

Utilisez ce mode lorsque la provenance est importante ou lorsque les branches renvoient des structures différentes.

### Append arrays — concaténer les tableaux

Crée une liste en concaténant les tableaux entrants sur **un seul niveau**. Les scalaires et les objets sont ajoutés comme des éléments individuels ; les valeurs `null` sont ignorées.

| Valeurs entrantes | Résultat |
| --- | --- |
| `[1, 2]`, `3`, `[4, 5]` | `[1, 2, 3, 4, 5]` |
| `[{"id": 1}]`, `{"id": 2}`, `null` | `[{"id": 1}, {"id": 2}]` |

Les tableaux imbriqués ne sont pas aplatis récursivement. Par exemple, `[[1, 2]]` reste `[[1, 2]]`.

### Combine objects — combiner les objets

Effectue une combinaison **superficielle** des objets entrants. Si plusieurs objets contiennent la même clé, la valeur de la branche entrante la plus tardive l'emporte. Les objets imbriqués sont remplacés, et non fusionnés récursivement.

```jsonc
// branche profile
{"id": 42, "name": "Ada", "preferences": {"theme": "dark"}}

// branche enrichment, traitée plus tard
{"name": "Ada Lovelace", "preferences": {"language": "fr"}}

// résultat
{"id": 42, "name": "Ada Lovelace", "preferences": {"language": "fr"}}
```

Si une valeur entrante n'est pas un objet, elle est conservée sous l'identifiant de son nœud source. Par exemple, un objet provenant de `profile` et le nombre `85` provenant de `score` produisent :

```json
{"id": 42, "name": "Ada", "score": 85}
```

Utilisez d'abord **Set fields** ou un nœud de transformation si vous avez besoin de noms de clés explicites ou d'une fusion profonde.

### Pass through source — transmettre une source

Attend le point de convergence, mais transmet une seule valeur entrante sans la modifier. Saisissez l'identifiant technique exact du nœud dans **Source node ID**.

Si le champ est vide ou ne correspond à aucune source entrante, la dernière valeur entrante disponible est transmise. Renseignez toujours l'ID lorsque le choix de la branche est important.

## Ordre et synchronisation des branches

Le nœud traite les entrées dans l'ordre de ses connexions entrantes tel qu'il est enregistré par le workflow. Cet ordre détermine :

- l'ordre des éléments avec **Collect inputs** et **Append arrays** ;
- la valeur qui l'emporte en cas de clés identiques avec **Combine objects** ;
- la valeur de repli avec **Pass through source**.

Évitez de faire dépendre une règle métier de l'ordre des connexions. Renommez ou normalisez les clés avant la fusion, ou sélectionnez explicitement une source.

Le moteur retarde l'exécution du point de convergence jusqu'à ce que ses parents amont accessibles aient été exécutés. Une branche conditionnelle qui ne produit aucune sortie est absente de la fusion : le nœud combine les sorties disponibles et ne crée pas de valeur de remplacement pour la branche manquante.

## Sortie d'exécution

La valeur fusionnée devient la sortie standard du nœud :

- `{outputs.<merge_node_id>.parsed}` — valeur fusionnée structurée, recommandée dans les nœuds aval ;
- `{outputs.<merge_node_id>.raw}` — représentation texte du résultat ;
- `{last_output_parsed}` — même valeur structurée immédiatement après le nœud Merge ;
- `{last_output}` — texte JSON pour les objets/listes, texte pour les scalaires ou chaîne vide pour `null`.

Le runtime enregistre aussi des métadonnées dans `merge` : `mode`, `source_count` et la liste ordonnée `sources`.

Exemples de références dans un nœud aval :

```text
{outputs.merge-customers.parsed}
{outputs.merge-customers.parsed.0}
{outputs.merge-profile.parsed.email}
```

## Choisir le bon mode

| Besoin | Mode |
| --- | --- |
| Conserver l'identité de chaque branche | **Collect inputs** |
| Produire une seule liste plate | **Append arrays** |
| Produire un seul objet fusionné superficiellement | **Combine objects** |
| Synchroniser les branches mais conserver une seule valeur | **Pass through source** |

## Problèmes fréquents

- **Le label est utilisé comme Source node ID :** copiez plutôt l'identifiant technique du nœud ; les labels ne servent pas à la sélection.
- **Des champs sont écrasés :** Combine objects est superficiel et la branche la plus tardive l'emporte. Rendez les clés uniques avant la fusion.
- **Une liste reste imbriquée :** Append arrays n'aplatit que le premier niveau des tableaux entrants.
- **Une branche manque dans le résultat :** seules les sources ayant produit une sortie sont incluses. Vérifiez la condition de la branche et sa trace d'exécution.
- **La provenance est perdue :** Append et Combine ne conservent pas les métadonnées de source. Utilisez Collect inputs si l'étape aval doit connaître l'origine.

## Exemple de workflow

Utilisez la carte ci-dessous pour créer un exemple sûr dans l'éditeur. Elle démarre deux branches, collecte leurs sorties, puis continue vers le nœud End.

---

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