# Actions réutilisables

La même étape revient généralement dans plusieurs automatisations. Une alerte Slack, une écriture dans un journal d'audit, un appel à une API interne. Copier cette étape dans chaque automatisation oblige à répercuter chaque changement futur dans chaque copie.

`app.actions` est une bibliothèque de modèles nommés. Définissez l'étape une seule fois, avec des espaces réservés `$variable` là où les entrées diffèrent :

```yaml
actions:
  - name: notify-slack
    action:
      type: http
      operator: post
      props:
        url: $env.SLACK_WEBHOOK_URL
        body: { text: '$message' }
```

Invoquez-la ensuite depuis n'importe quelle automatisation avec une action `ref`, en passant les valeurs :

```yaml
automations:
  - name: order-alert
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - name: alert
        $ref: notify-slack
        $vars: { message: 'New order recorded.' }
```

## Propriétés d'un modèle

| Propriété   | Description                                                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `name`      | Identifiant kebab-case unique utilisé par `$ref`. Commence par une lettre minuscule, 100 caractères maximum. **Requis.**      |
| `action`    | L'étape que le modèle exécute : n'importe quel couple `type` / `operator` accepté par une étape d'automatisation. **Requis.** |
| `variables` | Valeurs par défaut des espaces réservés du modèle. Chaque site d'appel peut les remplacer avec `$vars`.                       |
| `aiAccess`  | Expose le modèle aux clients IA comme outil MCP `{app}_action_{name}`, dont les paramètres dérivent de `variables`.           |

:::callout
**Le modèle ne porte pas de nom d'étape.** Dans une automatisation, `name` sert aux étapes suivantes à référencer une sortie : il appartient donc au site d'appel, pas au modèle. C'est la raison pour laquelle `action` est un bloc imbriqué. Le modèle déclare quoi faire, l'invocation déclare comment l'appeler.
:::

## Invoquer un modèle

L'action `ref` est la seule action sans `operator`. Elle transporte une référence et, si besoin, les valeurs propres à ce site d'appel :

| Propriété | Description                                                                                                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `$ref`    | Nom du modèle à invoquer. Doit correspondre à un modèle déclaré dans `app.actions`.                                     |
| `$vars`   | Valeurs pour cette invocation. Fusionnées par-dessus les valeurs par défaut `variables`, qu'elles remplacent.           |
| `name`    | Nom d'étape enregistré dans l'historique d'exécution. C'est le nom du site d'appel qui est retenu, pas celui du modèle. |

Écrire `type: ref` reste facultatif. Un `$ref` est déjà sans ambiguïté : `{ name: alert, $ref: notify-slack }` et la forme explicite `{ name: alert, type: ref, $ref: notify-slack }` désignent la même action.

## Variables

Un espace réservé est un `$` suivi d'un nom alphanumérique (`$message`, `$channel`). À l'invocation, les variables fusionnées fournissent les valeurs :

| Règle                 | Détail                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| Où elles se résolvent | Dans toute valeur de chaîne, à n'importe quelle profondeur du bloc `action` du modèle.                |
| Priorité              | Les `$vars` du site d'appel l'emportent sur les valeurs par défaut `variables` du modèle.             |
| Noms inconnus         | Laissés intacts : `$env.SLACK_WEBHOOK_URL` et `{{trigger.data.id}}` survivent donc à la substitution. |

Cette dernière règle est ce qui permet à un modèle de mêler les trois familles de références. Déclarez les valeurs par défaut qui vous intéressent, et laissez les références d'environnement et les variables de gabarit d'automatisation être résolues plus tard par leurs propres moteurs.

Le même modèle avec des variables différentes produit des étapes différentes :

```yaml
actions:
  - name: notify-team
    variables:
      channel: general
      message: Something happened.
    action:
      type: http
      operator: post
      props:
        url: $env.SLACK_WEBHOOK_URL
        body: { channel: '$channel', text: '$message' }

automations:
  - name: order-alert
    trigger: { type: record, table: orders, events: [create] }
    actions:
      - { name: alert, $ref: notify-team, $vars: { message: 'New order.' } }
      - { name: escalate, $ref: notify-team, $vars: { channel: ops, message: 'Check stock.' } }
```

## Exposer un modèle à l'IA

Un modèle doté d'un bloc `aiAccess` devient un outil MCP directement invocable. Ses `variables` deviennent les paramètres de l'outil : la déclaration qui rend une étape réutilisable la rend donc aussi appelable.

```yaml
actions:
  - name: archive-order
    variables:
      reference: ''
    action:
      type: record
      operator: update
      props:
        table: orders
        filter:
          conditions: [{ field: reference, operator: equals, value: '$reference' }]
        data: { archived: true }
    aiAccess:
      description: Archive one order by its reference.
      annotations: { readOnly: false, destructive: false, idempotent: true }
```

Le fait que le serveur monte réellement ces outils relève de l'exploitant, via `MCP_ENABLED`. Voir [Serveur MCP](/fr/docs/mcp-server).

## Validation

| Règle               | Détail                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Noms uniques        | Un doublon rendrait un `$ref` ambigu, et il est rejeté au décodage de la configuration.                             |
| `ref` est réservé   | Ce nom entre en collision avec la méthode `context.actions.ref()` exposée aux actions de code, et il est rejeté.    |
| Références résolues | Un `$ref` désignant un modèle inexistant est détecté au démarrage, avant que l'automatisation ne puisse s'exécuter. |

:::callout
**Modèles vs étapes d'automatisation.** `app.actions` contient les étapes que vous invoquez depuis plus d'un endroit. Une étape utilisée par une seule automatisation a sa place en ligne, dans cette automatisation. Un modèle référencé depuis un seul site d'appel ajoute de l'indirection sans supprimer la moindre duplication.
:::

## Pages connexes

- [Vue d'ensemble des actions](/fr/docs/automation-actions-overview) — le modèle d'action et les ~22 familles qu'un modèle peut envelopper.
- [Vue d'ensemble des automatisations](/fr/docs/automations-overview) — l'anatomie déclencheur + actions.
- [Composants réutilisables](/fr/docs/reusable-components) — le même principe pour l'arbre de composants d'une page.
- [Serveur MCP](/fr/docs/mcp-server) — les modèles d'action exposés comme outils IA.
- [Variables d'environnement](/fr/docs/automation-env-vars) — les références `$env.NAME` que porte le corps d'un modèle.