# Se connecter à des outils personnalisés

Les outils personnalisés permettent à l’Assistant GitBook, dans le [l’intégration Docs](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/publishing-documentation/embedding) d’effectuer de véritables actions.

Vous pouvez le connecter à *n’importe quel* outil auquel votre application peut accéder. Cela inclut vos API backend, les SDK tiers et les systèmes internes.

Si votre application peut l’appeler, l’Assistant peut l’appeler.

Exemples courants :

* Créer ou mettre à jour des tickets d’assistance au nom de l’utilisateur
* Passer à l’assistance en ouvrant un chat de support avec un message prérempli

  <div data-gb-custom-block data-tag="hint" data-style="success" class="hint hint-success"><p><strong>Transfert vers l’assistance</strong> est un excellent moyen de commencer avec les outils personnalisés. C’est la façon la plus rapide de débloquer les utilisateurs.</p></div>
* Déclencher des actions produit (réinitialiser le MFA, renvoyer une invitation, activer un flag de fonctionnalité)
* Consulter l’état du compte dans votre backend
* Lancer des workflows dans des outils comme Jira, Linear, Slack ou Zendesk

{% hint style="info" %}
En plus des outils que vous définissez dans la configuration de l’embed, l’Assistant peut également utiliser n’importe quel [serveurs MCP que vous configurez](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/mcp-servers-for-published-docs) dans **Paramètres → IA et MCP**.
{% endhint %}

### Où les outils s’exécutent

La `fonction execute` de l’outil s’exécute dans le même environnement que votre intégration d’embed.

Cela signifie généralement qu’elle s’exécute dans le navigateur de l’utilisateur, à l’intérieur de votre application.

Vous pouvez donc :

* Appeler vos propres points de terminaison backend
* Appeler n’importe quel SDK tiers déjà chargé dans votre application (par exemple, Intercom)
* Ouvrir des modales, des liens profonds ou des interfaces intégrées au produit

{% hint style="warning" %}
Évitez de mettre des secrets dans le code côté client — appelez plutôt votre backend.
{% endhint %}

### Ajouter un outil

Définir des outils :

* Via `window.GitBook("configure", …)` pour l’implémentation [balise script](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/script) implémentation
* Via la `tools` prop pour le [Node.js/NPM](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/nodejs) package et les [composants](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/react) React

{% hint style="info" %}
Les outils ne sont pas la même chose que l’embed **actions**.

* Utiliser **actions** pour les boutons sur lesquels l’utilisateur clique.
* Utilisez des outils lorsque vous voulez que l’Assistant choisisse et exécute du code.
  {% endhint %}

#### Modèle d’outil (renvoyer un e-mail d’invitation)

Examinons un exemple :

```javascript
window.GitBook("configure", {
  tools: [
    {
      // Enregistrer l’outil avec un nom et une description.
      name: "resend_invite",
      description:
        "Renvoyer un e-mail d’invitation lorsque l’utilisateur ne le trouve pas ou indique qu’il a expiré.",

      // Le schéma d’entrée est une donnée accessible dans la fonction execute.
      inputSchema: {
        type: "object",
        properties: {
          email: {
            type: "string",
            description:
              "L’adresse e-mail à laquelle renvoyer l’invitation. Si elle est inconnue, demandez d’abord à l’utilisateur.",
          },
        },
        required: ["email"],
      },

      // Un bouton de confirmation facultatif affiché avant l’exécution de la fonction execute.
      confirmation: { icon: "paper-plane", label: "Renvoyer l’invitation ?" },

      // La fonction execute est la fonction qui sera appelée lorsque l’outil est utilisé.
      execute: async (input) => {
        const { email } = input;

        const result = await fetch("/api/invites/resend", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ email }),
        }).then((r) => r.json());

        return {
          // La sortie est renvoyée à l’IA.
          output: {
            recipient: email,
            status: result.status ?? "success",
          },
          // Le résumé est affiché à l’utilisateur.
          summary: {
            icon: "check",
            text: "Invitation renvoyée.",
          },
        };
      },
    },
  ],
});
```

### Comment les outils sont utilisés

Une fois que vous avez enregistré des outils, l’Assistant peut les choisir automatiquement — en fonction de la question de l’utilisateur et de votre outil `description`.

Si des champs obligatoires manquent, l’Assistant doit poser des questions de suivi.

Si vous ajoutez `confirmation`, l’utilisateur doit approuver avant l’exécution de l’outil.

### Champs de l’outil

* `name`: Identifiant unique.
* `description`: L’indication « quand utiliser ceci » pour l’Assistant.
* `inputSchema`: Schéma JSON pour les entrées de l’outil.
* `confirmation` (facultatif) : Un bouton de confirmation affiché avant l’exécution de l’outil.
* `execute(input)`: Fonction asynchrone qui exécute l’action.
  * Retourner `{ output, summary }`.
  * `output` est renvoyé à l’Assistant.
  * `summary` est affiché à l’utilisateur.

#### Confirmation

Utiliser `confirmation` quand vous voulez que l’utilisateur approuve une action. Cela aide à éviter des effets secondaires inattendus.

`confirmation` accepte :

* `label` (obligatoire) : Texte du bouton.
* `icon` (facultatif) : Un [Font Awesome](https://fontawesome.com/search) nom d’icône.

### Workflow de support

Le support est le cas d’usage le plus intéressant pour les outils.

Vous pouvez laisser l’Assistant :

* Collecter les détails manquants
* Créer un ticket dans votre système
* Ouvrir un canal de support humain avec le contexte prérempli

#### Modèle : ouvrir un chat d’assistance avec un message prérempli

Utilisez ceci lorsque vous voulez un transfert propre vers un humain.

```javascript
window.GitBook("configure", {
  tools: [
    {
      name: "open_support_chat",
      description:
        "Ouvrir le chat d’assistance avec un message prérempli afin que l’utilisateur puisse contacter rapidement le support.",
      inputSchema: {
        type: "object",
        properties: {
          message: {
            type: "string",
            description:
              "Le message à envoyer au support. S’il manque, demandez d’abord à l’utilisateur.",
          },
        },
      },
      confirmation: { icon: "circle-question", label: "Ouvrir le chat d’assistance" },
      execute: (input) => {
        // Fermer l’Assistant GitBook
        window.GitBook('close');
     
        // Exemples :
        // - Intercom : Intercom('showNewMessage', input.message);
        // - Zendesk : zE('messenger', 'open');
        
        return {
          output: {
            status: "success",
          },
          summary: { icon: 'check', text: "Transféré vers le support." },
        };
      },
    },
  ],
});
```

{% hint style="info" %}
Associez cela à une action toujours visible **Contacter le support** dans la barre latérale de l’embed. Vous pouvez configurer les actions en suivant [Personnalisation de l’Embed](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/customizing-docs-embed).
{% endhint %}

### Étapes suivantes

* Besoin de l’ensemble complet de l’API d’embed ? Consultez [Référence de l’API](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/reference).
* Vous voulez plus de contrôles d’interface (message d’accueil, suggestions, actions) ? Consultez [Personnalisation de l’Embed](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/customizing-docs-embed).