> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Exécuter des actions d’application pendant les conversations

> Transformez une action d’une application connectée, comme l’ajout d’une ligne de tableur, en outil que votre assistant utilise en appel, en chat et par e-mail

Un outil d’action d’application permet à un assistant d’exécuter une action dans une application connectée à votre espace de travail, pendant que la conversation est encore en cours. Par exemple : ajouter une ligne à une feuille Google Sheets ou créer un contact dans HubSpot. Vous choisissez l’application, la connexion et l’action, et Famulor transforme les champs de l’action en outil avec de vrais paramètres. Vous n’avez besoin ni de votre propre point de terminaison API ni d’une automatisation.

> [!NOTE]
>
> Les outils d’action d’application sont en bêta. Les propriétaires et les administrateurs les voient dès que l’interrupteur **Fonctionnalités bêta** est activé sous [Paramètres → Espace de travail](https://docs.famulor.io/fr/settings/workspaces.md), et le forfait de l’espace de travail doit inclure les automatisations. Les autres membres voient les outils d’action d’application attribués, sans pouvoir les modifier.

## Fonctionnement d’un outil d’action d’application

Un salon de coiffure veut enregistrer les demandes de rappel de ses appelants dans un tableur. Il crée un outil d’action d’application pour l’action Google Sheets « Add row ». Le classeur et la feuille sont des valeurs fixes, l’assistant remplit le nom et la demande de l’appelant, et le numéro de téléphone provient du numéro présenté par l’appelant. Avant d’écrire la ligne, l’assistant relit les informations et demande à l’appelant de les confirmer.

L’outil apparaît dans **Outils d’agent** à côté de vos autres outils, et vous l’attribuez aux assistants comme n’importe quel outil. Il fonctionne sur tous les canaux de conversation :

* appels téléphoniques, appels web et appels WhatsApp
* chat web, y compris le Test Chat
* tous les [canaux de messagerie](https://docs.famulor.io/fr/channels/messaging.md), comme WhatsApp, SMS, Telegram ou Slack
* l’[e-mail](https://docs.famulor.io/fr/channels/email.md), qu’il s’agisse de l’adresse propre de l’assistant ou de boîtes aux lettres connectées

## Choisir le bon type d’outil

Un outil d’action d’application couvre une seule action dans une seule application. Pour tout le reste, un autre type d’outil convient mieux :

| Vous avez besoin de | Utilisez |
| - | - |
| Une action dans une application connectée | Un outil d’action d’application (cette page) |
| Une requête vers votre propre point de terminaison HTTP | Un [outil API](https://docs.famulor.io/fr/api/tools-and-webhooks.md#outils-api) |
| Plusieurs étapes, conditions ou applications en une exécution | Une automatisation [appelée depuis la conversation](https://docs.famulor.io/fr/automations/overview.md#appeler-une-automatisation-depuis-une-conversation) |

Pour une seule action, un outil d’action d’application est plus rapide qu’une automatisation appelable. L’assistant envoie chaque champ directement : aucune étape d’IA supplémentaire n’a besoin d’extraire les valeurs d’un texte libre.

## Avant de commencer

Vérifiez d’abord ces conditions :

* Vous êtes propriétaire ou administrateur de l’espace de travail.
* L’interrupteur **Fonctionnalités bêta** est activé sous **Paramètres → Espace de travail**.
* Le forfait de l’espace de travail inclut les automatisations, et sa limite **Outils et MCP** permet d’ajouter un outil.
* L’application est connectée sous **Automatisations → Connexions**. Vous pouvez aussi la connecter pendant la création de l’outil.

## Créer un outil d’action d’application

**1. Choisir l’application et l’action**

Ouvrez **Outils d’agent** et sélectionnez **Nouvel outil → App (Bêta)**. Vous pouvez aussi partir de la carte **Apps** sous **Connecteurs d'agent**, où le logo d’une app ouvre directement cette app, ou sélectionner **Utiliser dans l’assistant** à côté d’une app sous **Automatisations → Connexions**. L’éditeur liste vos apps connectées. Pour ajouter une autre app, sélectionnez **Connecter une app** : la même liste d’apps que dans les automatisations s’ouvre, et vous revenez ici après la connexion. Choisissez ensuite l’action. Si l’application a plusieurs connexions, choisissez-en une sous **Connexion**.

**2. Nommer l’outil et préciser quand l’utiliser**

**Nom** est prérempli, par exemple `google_sheets_add_row`. Dans **Utiliser quand**, décrivez la situation dans laquelle l’assistant doit appeler l’outil, par exemple « Quand l’appelant demande un rappel. » Utilisez au moins 10 caractères. Une phrase précise fonctionne mieux qu’un libellé court.

**3. Choisir la source de chaque valeur**

Chaque champ de l’action possède un réglage **Valeur de**, décrit dans la section suivante. Les champs obligatoires apparaissent en premier. Les champs facultatifs commencent sur **Désactivé** sous **Plus de champs**.

**4. Décider si l’assistant demande d’abord**

Pour les actions qui modifient des données, **Demander d’abord** est activé. Laissez-le activé, sauf si la modification ne demande aucune confirmation. La section « Demander d’abord » ci-dessous explique son fonctionnement.

**5. Vérifier l’aperçu et tester**

**Ce que voit l’assistant** montre l’outil exactement tel que l’assistant le reçoit. Testez-le sous **Test** avant d’enregistrer, comme décrit plus bas.

**6. Enregistrer et attribuer**

Sélectionnez **Créer un outil**, puis [attribuez l’outil](https://docs.famulor.io/fr/assistants/agent-tools.md#installed) aux assistants. Dans les réglages d’un assistant, **Avancé → Outils → Ajouter un outil** liste vos **Applications connectées** : sélectionnez-en une pour ouvrir le même éditeur, ou sélectionnez **Connecter une app** pour connecter d’abord une autre app. L’outil est attribué lorsque vous sélectionnez **Ajouter à l’assistant**. Un outil d’action d’application ne peut pas encore servir de nœud **Tool** dans un [Flow](https://docs.famulor.io/fr/flow-builder/nodes.md#tool) ; attribuez-le plutôt à l’assistant.

## Choisir la source de chaque valeur

**Valeur de** détermine qui fournit la valeur d’un champ :

| Valeur de | La valeur vient de | À utiliser pour |
| - | - | - |
| **IA** | L’assistant, à partir de la conversation | Les informations données par le client, comme un nom, une demande ou une date souhaitée |
| **Valeur fixe** | Votre saisie, envoyée à chaque exécution | Les identifiants d’un classeur, d’un agenda, d’une liste ou d’un pipeline, et des libellés fixes |
| **Variable** | Une variable de conversation, comme **Numéro de l'appelant** | Le numéro de l’appelant, l’adresse e-mail du client ou une variable d’assistant |
| **Désactivé** | Personne : le champ n’est pas envoyé | Les champs facultatifs dont vous n’avez pas besoin |

Pour les champs **IA**, Famulor rédige une description à partir des informations de l’application sur le champ, avec le format attendu, comme `YYYY-MM-DD`, et un exemple. Saisissez votre propre description pour la remplacer. Jusqu’à 12 champs peuvent utiliser **IA**. Restez à 8 ou moins : moins de champs rendent les appels plus rapides et plus fiables.

L’assistant ne voit jamais les champs **Valeur fixe** et **Variable** et ne peut pas les modifier. Un texte fixe peut contenir des [variables](https://docs.famulor.io/fr/assistants/variables.md) comme `{{caller_number}}` ainsi que les valeurs des champs IA, écrites avec le nom de paramètre affiché dans **Ce que voit l’assistant**, par exemple `{{start_time}}`. Si vous collez un lien vers un élément Google Sheets, Docs, Drive, Notion ou Airtable, Famulor ne garde que son identifiant.

Quelques règles s’appliquent encore aux champs :

* Les champs de téléphone commencent avec la variable **Numéro de l'appelant**. Sur les canaux de messagerie, elle contient le numéro de téléphone du contact.
* Les champs obligatoires ne peuvent pas être sur **Désactivé**.
* Certains champs attendent des lignes de tableau, par exemple les valeurs d’une nouvelle ligne de tableur ou les participants d’un événement. Ils affichent **Colonnes**. Pour une ligne de tableur, sélectionnez **Ajouter une colonne** pour chaque valeur et nommez la colonne. Pour une liste comme les participants, l’application définit les colonnes, par exemple Email et Name ; sélectionnez **Ajouter une ligne** pour chaque entrée. Choisissez **IA**, **Valeur fixe** ou **Variable** pour chaque cellule. Une colonne obligatoire a besoin d’une valeur dans chaque ligne.
* Dans une liste comme les participants, les colonnes facultatives commencent sur **Désactivé**. Activez-les pour une ligne lorsque vous en avez besoin. Les cellules de nombre et de oui/non acceptent **IA** ou **Valeur fixe**.

**Ce que voit l’assistant** liste le nom de l’outil, sa description et tous les champs IA. Les valeurs fixes et les variables y figurent comme non visibles pour l’assistant. La description peut compter jusqu’à 900 caractères. L’icône de crayon vous permet de rédiger la description vous-même. Les phrases sur la confirmation des modifications et sur les résultats inconnus restent toujours à la fin.

## Demander d’abord

Pour les actions qui modifient des données, comme ajouter une ligne ou créer un contact, **Demander d’abord** est activé par défaut. Les actions qui ne font que lire des données ne demandent jamais. Avec **Demander d’abord**, une modification se déroule ainsi :

1. L’assistant appelle l’outil. Rien ne change encore : Famulor renvoie un résumé des valeurs.
2. L’assistant lit ce résumé au client et lui demande s’il est correct.
3. L’assistant appelle de nouveau l’outil avec les mêmes valeurs. Cet appel exécute l’action dans l’application si la condition du canal est remplie :
   * En messagerie et par e-mail, le client a envoyé un nouveau message depuis le résumé.
   * En appel et dans le chat web, au moins 4 secondes se sont écoulées depuis le premier appel. Famulor ne peut pas y vérifier si le client a répondu.

Un appel trop précoce ne modifie rien, et l’assistant est invité à attendre la réponse du client. Si une valeur change entre-temps, l’assistant relit les nouvelles informations et redemande. Une modification préparée expire après 10 minutes en appel et dans le chat web, après 72 heures par e-mail, y compris dans les boîtes aux lettres connectées, et après 24 heures sur les autres canaux de messagerie.

> [!WARNING]
>
> En appel et dans le chat web, **Demander d’abord** impose seulement une pause : une modification peut s’exécuter après 4 secondes, même si le client n’a pas répondu. En messagerie et par e-mail, une modification ne s’exécute qu’après un nouveau message du client. Sur aucun canal, **Demander d’abord** n’est une preuve de consentement : Famulor ne vérifie pas ce que le client a répondu et ne conserve aucune preuve d’accord distincte. Lorsque vous avez besoin d’un consentement documenté, par exemple pour un contrat ou un paiement, recueillez-le avec un processus conçu pour cela.

Vous pouvez désactiver **Demander d’abord** pour une modification qui ne demande aucune confirmation. L’assistant modifie alors les données dans l’application sans les relire au préalable.

## Tester avant utilisation

Testez chaque outil avant de l’attribuer à un assistant qui parle à des clients. Sous **Test**, saisissez des valeurs d’exemple pour les champs IA et les variables, puis sélectionnez **Exécuter un test** :

* Les actions qui lisent des données s’exécutent réellement.
* Les actions qui modifient des données s’exécutent d’abord à blanc : rien ne change, et vous voyez ce que l’assistant relirait. Sélectionnez **Exécuter pour de vrai** et confirmez pour effectuer la modification dans l’application.

Le résultat indique si l’exécution a réussi, combien de temps elle a pris et exactement ce que l’assistant reçoit. En appel, l’appelant attend pendant l’exécution de l’action : surveillez donc la durée. Essayez ensuite l’outil dans un appel de test ou dans le Test Chat avec l’assistant auquel il est attribué.

## Ce que reçoit l’assistant

Famulor raccourcit chaque résultat avant que l’assistant le lise. Famulor supprime les identifiants internes, les numéros de version et les valeurs qui ressemblent à des secrets. Il coupe aussi les textes à 500 caractères et les listes à 10 éléments, et limite le résultat complet à 2 000 caractères.

Sous **Avancé → Résultat**, choisissez **Champs sélectionnés** pour ne garder que les champs choisis dans un résultat de test réussi. Via l’API, `result_config.max_chars` relève la limite à 3 500 caractères. L’assistant reçoit les résultats marqués comme données externes, et non comme instructions.

## Limites

| Limite | Valeur |
| - | - |
| Durée par exécution | 12 secondes ; l’application doit répondre en 8 secondes |
| Champs IA par outil | 12 |
| Description de l’outil | 900 caractères |
| Texte par valeur | 4 000 caractères |
| Résultat pour l’assistant | 2 000 caractères, jusqu’à 3 500 via l’API |
| Exécutions par outil | 60 par minute |
| Exécutions par espace de travail | 300 par minute |
| Exécutions par outil dans une conversation | 15 par minute, dont 5 modifications au maximum (la relecture des informations n’est pas une modification) |
| Actions qui suppriment des données | Pas encore disponibles |

Si l’application ne répond pas à temps, la suite dépend de l’action. Une action qui lit des données n’a pas été exécutée, et l’assistant peut réessayer. Pour une modification, le résultat est inconnu : l’assistant ne réessaie pas et indique au client que l’équipe va vérifier.

## Modifier, reconnecter ou supprimer un outil

Ouvrez l’outil dans **Outils d’agent** pour modifier ses champs, **Utiliser quand** ou **Demander d’abord**. **Exécutions** liste les dernières exécutions de l’outil sur tous les canaux, y compris la messagerie, l’e-mail et les tests. Une modification préparée qui attend le client et une exécution à blanc n’y figurent pas, car rien n’a été exécuté dans l’application. Les exécutions en échec et celles dont le résultat est inconnu apparaissent comme des erreurs. Pour utiliser une autre action, créez un nouvel outil.

* Vous pouvez basculer l’outil sur une autre connexion de la même application.
* Lorsqu’une connexion expire, l’outil affiche **Reconnecter** et ne s’exécute plus tant que vous ne l’avez pas reconnectée. Sélectionnez **Reconnecter** et connectez-vous de nouveau : Famulor renouvelle la même connexion et vous ramène à l’outil. Si l’outil a des modifications non enregistrées, Famulor vous demande d’abord si vous voulez les abandonner. Si la connexion échoue, l’outil affiche l’erreur et de nouveau **Reconnecter**.
* Vous ne pouvez pas supprimer une connexion utilisée par des outils d’action d’application. Basculez d’abord ces outils sur une autre connexion ou supprimez-les.
* Pour supprimer un outil d’action d’application, retirez-le d’abord de chaque assistant qui l’utilise. Supprimez-le ensuite comme n’importe quel outil.
* Les outils d’action d’application ne peuvent pas être déplacés vers un autre espace de travail. Recréez l’outil dans l’autre espace de travail.

## API, MCP, CLI et SDK

Vous pouvez créer, lire, modifier et tester des outils d’action d’application sans le tableau de bord. Chaque requête exige un accès propriétaire ou administrateur. Lister et lire des actions, ainsi que créer, modifier ou tester un outil, exigent aussi un forfait incluant les automatisations. Lister et lire des actions demande la portée `automations:read`, lire un outil `assistants:read`, et créer, modifier ou tester un outil demande à la fois `assistants:write` et `automations:write`. Comme dans le tableau de bord, la création exige aussi **Fonctionnalités bêta**.

| API | MCP | CLI | SDK |
| - | - | - | - |
| `GET /api/v1/automations/connections/{id}/actions` | `list_app_actions` | `famulor list-app-actions <id>` | `client.api.listAppActions({ path: { id } })` |
| `GET /api/v1/automations/connections/{id}/actions/{action}` | `get_app_action` | `famulor get-app-action <id> <action>` | `client.api.getAppAction({ path: { id, action } })` |
| `POST /api/v1/tools/app-actions` | `create_app_action_tool` | `famulor create-app-action-tool --input tool.json` | `client.api.createAppActionTool({ body })` |
| `GET /api/v1/tools/app-actions/{toolId}` | `get_app_action_tool` | `famulor get-app-action-tool <toolId>` | `client.api.getAppActionTool({ path: { toolId } })` |
| `PATCH /api/v1/tools/app-actions/{toolId}` | `update_app_action_tool` | `famulor update-app-action-tool <toolId> --input patch.json` | `client.api.updateAppActionTool({ path: { toolId }, body })` |
| `POST /api/v1/tools/app-actions/{toolId}/test` | `test_app_action_tool` | `famulor test-app-action-tool <toolId> --input test.json` | `client.api.testAppActionTool({ path: { toolId }, body })` |

Les outils d’action d’application apparaissent aussi dans `GET /api/v1/tools`, avec un résumé sous `app_action`. Attribuez-les avec `PUT /api/v1/assistants/{id}/tools`, ou indiquez `assistant_id` lors de la création ; un assistant inconnu renvoie `404` avant que l’outil ne soit créé. `GET /api/v1/tools/{id}/runs` et l’outil MCP `list_tool_runs` renvoient les exécutions affichées sous **Exécutions**. Retirez un outil de ses assistants, puis supprimez-le avec `DELETE /api/v1/tools/{id}`. Le `PATCH /api/v1/tools/{id}` général permet toujours de renommer un outil ou de l’activer et le désactiver ; toute autre modification par ce biais renvoie `409`. Le test général, `POST /api/v1/tools/test` ou `test_tool`, renvoie lui aussi `409` pour un outil d’action d’application.

### Créer un outil via l’API

Listez d’abord les actions d’une connexion. `q` recherche par nom. Les actions qui suppriment des données ne sont pas listées.

```bash theme={null}
curl "https://app.famulor.io/api/v1/automations/connections/CONNECTION_ID/actions?q=row" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Lisez les détails de l’action choisie avec `get-app-action`. Ils listent les `fields` de l’action, chacun avec sa `key`, son `path`, son `param` et un `mode` proposé. Dans la requête de création, n’envoyez que les champs à modifier, identifiés par leur `path` ou leur `key`. Vous pouvez définir `mode`, `value`, `variable` et `description` ; les autres champs gardent leur réglage proposé. Cette requête crée l’outil et l’attribue à un assistant :

```json theme={null}
{
  "connection_id": "CONNECTION_ID",
  "action": "ACTION_ID",
  "use_when": "Quand l’appelant demande un rappel.",
  "confirmation": "ask_first",
  "assistant_id": "ASSISTANT_ID",
  "fields": [
    { "key": "spreadsheet_id", "mode": "fixed", "value": "SPREADSHEET_ID" },
    { "key": "phone", "mode": "variable", "variable": "caller_number" }
  ]
}
```

Les clés des champs dépendent de l’action. `confirmation` vaut `ask_first` ou `none` ; les actions qui lisent des données ne demandent jamais. Pour vous assurer que l’action n’a pas changé depuis votre lecture, envoyez aussi sa `version` : la requête échoue alors si l’action a une version plus récente. Enregistrez le corps sous `tool.json` et envoyez-le avec `famulor create-app-action-tool --input tool.json` ou `POST /api/v1/tools/app-actions`.

Testez ensuite l’outil. `values` contient des valeurs d’exemple pour les champs IA et les variables. Utilisez le `param` de chaque champ, c’est-à-dire le nom de paramètre que voit l’assistant, et non sa `key`. Les deux diffèrent souvent : le champ `startTime` a le `param` `start_time`, et une colonne reprend son nom de colonne, par exemple `name`. Pour un champ variable, le nom de la variable, comme `caller_number`, fonctionne aussi :

```json theme={null}
{
  "values": { "name": "Anna Weber", "request": "Rappel au sujet d’un rendez-vous couleur" },
  "mode": "dry_run"
}
```

`mode` vaut `dry_run`, la valeur par défaut, ou `live`. Pour une action qui modifie des données, un test réel exige en plus `"confirm_write": true` et modifie de vraies données dans l’application. La réponse contient `model_text`, c’est-à-dire le texte exact que recevrait l’assistant. Pour une action qui modifie des données, `read_back` indique ce que l’assistant relirait, y compris lors d’un essai à blanc.

## Prochaines étapes

> [card] [Agent Tools](https://docs.famulor.io/fr/assistants/agent-tools.md)
>
> Attribuer, modifier et surveiller tous les outils de votre espace de travail

> [card] [App Catalog](https://docs.famulor.io/fr/automations/app-catalog.md)
>
> Connecter des applications et voir ce qu’elles permettent dans les automatisations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.